# OS_LockMutex[R|W]

## Syntax

  `#include <nitro/os.h>`
  `void OS_LockMutexR( OSMutex* mutex );`
  `void OS_LockMutexW( OSMutex* mutex );`

## Arguments

`mutex` | Pointer to the `OSMutex` structure

## Return Values

None.

## Description

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);
> `

###
Corresponding Unlock Functions

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.

###
Exiting the Thread

When the thread that is locking `mutex` is ended by the `OS_ExitThread` function, that mutex is automatically unlocked.

###
Changing between `read lock` and `write lock`

The 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.

### Example

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`.

## See Also

`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
`

## Revision History

2008/12/16 Initial version.

CONFIDENTIAL