# OS_TryLockMutexFrom[RToW|WToR]

## Syntax

  `#include <nitro/os.h>`
  `BOOL OS_TryLockMutexFromRToW( OSMutex* mutex );`
  `BOOL OS_TryLockMutexFromWToR( OSMutex* mutex );`

## Arguments

`mutex` | Pointer to the `OSMutex` structure

## Return Values

Returns TRUE if the `mutex` lock can be changed from `read lock` to `write lock`, or conversely from `write lock` to `read lock`. If not, the function returns FALSE.

## Description

Changes the type of the `mutex` that is locked.

`mutex` is the pointer to the `OSMutex` structure to be changed.

The `OS_TryLockMutexFromWToR` function takes a `mutex` that is set to `write lock` and changes the setting to `read lock`. When the function succeeds, the `mutex` type is `read lock`. To unlock it you need to execute either the `OS_UnlockMutexR` or `OS_UnlockMutexRW` function.

The `OS_TryLockMutexFromRToW` takes a `mutex` that is set to `read lock` and changes the setting to `write lock`. When the function succeeds, the `mutex` type is `write lock`. To unlock it you need to execute either the `OS_UnlockMutexW` or `OS_UnlockMutexRW` function.

If `mutex` is locked at multiple levels or if the type is wrong, the function fails and returns FALSE. A multi-level locked mutex is one that is either locked by multiple threads, or by one thread in which more than one lock function calls the same `OSMutex` structure. A wrong type, for example, is when the function attempts to change a `read lock` mutex into a `write lock` mutex, but the target is not a `read lock` mutex.

> `Example 1
> OSMutex mutex;
> OS_LockMutexR( &mutex );
> OS_LockMutexR( &mutex );
> if ( OS_TryLockMutexFromRToW( &mutex ) == FALSE ) Returns FALSE because mutex is locked at multiple levels.
> {
> :
> }`

> `Example 2
> OSMutex mutex;
> OS_LockMutexR( &mutex );
> if ( OS_TryLockMutexFromWToR( &mutex ) == FALSE ) Returns FALSE because mutex is read lock, thus the wrong type for FromWToR.
> {
> :
> }`

This function returns immediately, regardless of whether it succeeds or fails. Threads are not switched.

## See Also

`OS_InitMutex
OS_LockMutex
OS_UnlockMutex
OS_LockMutexR
OS_LockMutexW
OS_UnlocMutexR
OS_UnlocMutexW
OS_TryLockMutexR
OS_TryLockMutexW
OS_LockMutexFromRToW
OS_LockMutexFromWToR`

## Revision History

2008/12/16 Initial version.

CONFIDENTIAL