

#include <nitro/os.h>void OS_LockMutexR( OSMutex* mutex );void OS_LockMutexW( OSMutex* mutex );mutex |
Pointer to the OSMutex structure |
None.
The calling thread attempts to lock the mutex specified by mutex.
mutex is a pointer to an OSMutex structure.
The OS_LockMutexR function attempts to read lock the mutex. If mutex is not being used or if is already set to read lock by another thread, the function returns immediately. The number of attempts is recorded, and mutex is not released if it has not been unlocked that same number of times. If mutex is set to write lock or if it is locked by the OS_LockMutex function, the called thread is paused until mutex is released.
OS_LockMutexW attempts to write lock the mutex. If mutex is not being used or if it is already locked by the current thread, the function returns immediately. The number of attempts is recorded, and mutex is not released if it has not been unlocked that same number of times. If mutex is set to read lock, or if it is set to write lock but is locked by another thread, or if it is locked by the OS_LockMutex function, the called thread is paused until mutex is released.
Note that mutex must be initialized by the OS_InitMutex function. (If the mutex was just used in another lock-unlock process, it can be used again without initialization.)
Example
OSMutex myMutex;
// Init mutex
OS_InitMutex(&myMutex);
// read lock
OS_LockMutexR(&myMutex);
:
OS_UnlockMutexR(&myMutex);
// write lock
OS_LockMutexW(&myMutex); myMutex can be used since it is finished being used in a read lock
:
OS_UnlockMutexW(&myMutex);
If mutex has been locked by the OS_LockMutexR function, unlock it using the OS_UnlockMutexR or OS_UnlockMutexRW function. You cannot unlock it using the OS_UnlockMutexW function.
If mutex has been locked by the OS_LockMutexW function, unlock it using the OS_UnlockMutexW or OS_UnlockMutexRW function. You cannot unlock it using the OS_UnlockMutexR function.
When the thread that is locking mutex is ended by the OS_ExitThread function, that mutex is automatically unlocked.
read lock and write lockThe change from read lock to write lock is performed using the OS_LockMutexFromRToW and OS_TryLockMutexFromRToW functions. In addition, the change from write lock to read lock is performed using the OS_LockMutexFromWToR and OS_TryLockMutexFromWToR functions. With both sets of functions, the transition does not involve switching threads.
Consider the following situation.
read is a function that can be simultaneously called from multiple threads because it reads but does not write data. This and the write function must be mutually exclusive because this data must not be read while it is being written, nor written while it is being read. While the mutex is locked by read, the calling thread will be suspended when control reaches the locking function in write. When the mutex is locked by write, it will also be locked by read. When the mutex is locked by read, however, other threads can execute read.
Because write is a function that writes data, it would be a problem if other threads could read and write data while write is executing. When the mutex is locked by the write lock function, that same mutex is read locked. In short, during a write lock other threads cannot execute read or write.
OS_InitMutex
OS_UnlockMutex
OS_TryLockMutex
OS_ExitThread
OS_UnlockMutexR
OS_UnlockMutexW
OS_UnlockMutexRW
OS_TryLockMutexR
OS_TryLockMutexW
OS_LockMutexFromRToW
OS_LockMutexFromWToR
OS_TryLockMutexFromRToW
OS_TryLockMutexFromWToR
2008/12/16 Initial version.
CONFIDENTIAL