PinCRT
Classes | Defines | Typedefs | Functions
Mutex

Implementation of mutex lock.

Classes

struct  _OS_APIS_MUTEX_TYPE

Defines

#define OS_APIS_MUTEX_DEPTH_SIMPLE_INITIALIZER   {OS_APIS_MUTEX_IMPL_DEPTH_SIMPLE_INITIALIZER}
#define OS_APIS_MUTEX_DEPTH_RECURSIVE_INITIALIZER   {OS_APIS_MUTEX_IMPL_DEPTH_RECURSIVE_INITIALIZER}

Typedefs

typedef struct _OS_APIS_MUTEX_TYPE OS_MUTEX_TYPE_IMPL

Functions

void OS_MutexInit (volatile OS_MUTEX_TYPE *lock)
void OS_MutexRecursiveInit (volatile OS_MUTEX_TYPE *lock)
void OS_MutexDestroy (volatile OS_MUTEX_TYPE *lock)
void OS_MutexLock (volatile OS_MUTEX_TYPE *lock)
void OS_MutexLockTid (volatile OS_MUTEX_TYPE *lock, NATIVE_TID myTid)
BOOL_T OS_MutexTryLock (volatile OS_MUTEX_TYPE *lock)
BOOL_T OS_MutexTryLockTid (volatile OS_MUTEX_TYPE *lock0, NATIVE_TID myTid)
BOOL_T OS_MutexIsLocked (volatile OS_MUTEX_TYPE *lock)
BOOL_T OS_MutexTimedLock (volatile OS_MUTEX_TYPE *lock, UINT32 timeoutMillis)
BOOL_T OS_MutexTimedLockTid (volatile OS_MUTEX_TYPE *lock0, NATIVE_TID myTid, UINT32 timeoutMillis)
NATIVE_TID OS_MutexGetOwner (volatile OS_MUTEX_TYPE *lock)
UINT32 OS_MutexGetRecursionLevel (volatile OS_MUTEX_TYPE *lock)
BOOL_T OS_MutexUnlock (volatile OS_MUTEX_TYPE *lock)

Define Documentation

#define OS_APIS_MUTEX_DEPTH_RECURSIVE_INITIALIZER   {OS_APIS_MUTEX_IMPL_DEPTH_RECURSIVE_INITIALIZER}

Static initializer for a mutex. It is guaranteed that a (recursive) mutex initialized this way:

OS_MUTEX_TYPE mutex = OS_APIS_MUTEX_DEPTH_SIMPLE_INITIALIZER;

Will be initialized before any constuctor will be called.

Availability:
  • O/S: Windows, Linux & macOS*
  • CPU: All
#define OS_APIS_MUTEX_DEPTH_SIMPLE_INITIALIZER   {OS_APIS_MUTEX_IMPL_DEPTH_SIMPLE_INITIALIZER}

Static initializer for a mutex. It is guaranteed that a (simple) mutex initialized this way:

OS_MUTEX_TYPE mutex = OS_APIS_MUTEX_DEPTH_SIMPLE_INITIALIZER;

Will be initialized before any constuctor will be called. Also, the static initializer for a simple mutex must be all zeros. This is because we want mutex that is initialized in a default way (all zeros according to the C++ standard) will be initialized correctly to a simple mutex.

Availability:
  • O/S: Windows, Linux & macOS*
  • CPU: All

Typedef Documentation

This type holds a representation of a mutex.

Availability:
  • O/S: Windows, Linux & macOS*
  • CPU: All

Function Documentation

void OS_MutexDestroy ( volatile OS_MUTEX_TYPE *  lock)

Destroys a mutex after it is no longer in use.

Note:
The behavior of a mutex after it was destroyed is undefined. It is the responsibility of the user to verify that no other thread is using the mutex when it comes to destroy it.
Parameters:
[in]lockThe mutex to destroy.
Availability:
  • O/S: Windows, Linux & macOS*
  • CPU: All
NATIVE_TID OS_MutexGetOwner ( volatile OS_MUTEX_TYPE *  lock)

Queries the owner of a recursive mutex.

Parameters:
[in]lockThe mutex to query.
Return values:
NATIVE_TIDThe owner of the mutex of INVALID_NATIVE_TID is the mutex is not locked.
Note:
The return value of this function is undefined for non-recursive (simple) mutex.
Availability:
  • O/S: Windows, Linux & macOS*
  • CPU: All
UINT32 OS_MutexGetRecursionLevel ( volatile OS_MUTEX_TYPE *  lock)

Queries the recursion of a recursive mutex. I.e. the number of times that the unlock functions needs to be called before the mutex can be acquired by other thread.

Parameters:
[in]lockThe mutex to query.
Return values:
UINT32The recursion level of the mutex.
Note:
For non-recursive (simple) mutex, the return value of this function is 1 if the mutex is lock, or 0 if the mutex is unlocked.
Availability:
  • O/S: Windows, Linux & macOS*
  • CPU: All
void OS_MutexInit ( volatile OS_MUTEX_TYPE *  lock)

Initialize a mutex. A mutex must be initialized before being used. Use this function to initialize the mutex or use one of the static initializers.

Parameters:
[in]lockThe mutex to initialize.
Availability:
  • O/S: Windows, Linux & macOS*
  • CPU: All
BOOL_T OS_MutexIsLocked ( volatile OS_MUTEX_TYPE *  lock)

Checks whether a mutex state is locked.
Doesn't affect the mutex state and doesn't block.

Parameters:
[in]lockThe mutex to check.
Return values:
TRUEIf the mutex is locked.
Availability:
  • O/S: Windows, Linux & macOS*
  • CPU: All
void OS_MutexLock ( volatile OS_MUTEX_TYPE *  lock)

Aquire a mutex, blocks until the mutex becomes available (according to the mutex's semantics).

Parameters:
[in]lockThe mutex to acquire.
Availability:
  • O/S: Windows, Linux & macOS*
  • CPU: All
void OS_MutexLockTid ( volatile OS_MUTEX_TYPE *  lock,
NATIVE_TID  myTid 
)

Aquire a mutex, blocks until the mutex becomes available (according to the mutex's semantics). This function is similar to OS_MutexLock() except that it accept as an argument the thread ID of the thread that want to acquire the lock (which is usually the current thread).

Parameters:
[in]lockThe mutex to acquire.
[in]tidThe thread ID of the thread that wants to acquire the mutex. This argument can be INVALID_NATIVE_TID if the thread ID is not known (e.g. in a mutex of type OS_MUTEX_DEPTH_SIMPLE).
Availability:
  • O/S: Windows, Linux & macOS*
  • CPU: All
void OS_MutexRecursiveInit ( volatile OS_MUTEX_TYPE *  lock)

Initialize a recursive mutex. A mutex must be initialized before being used. Use this function to initialize a recursive mutex or use one of the static initializers.

Parameters:
[in]lockThe mutex to initialize.
Availability:
  • O/S: Windows, Linux & macOS*
  • CPU: All
BOOL_T OS_MutexTimedLock ( volatile OS_MUTEX_TYPE *  lock,
UINT32  timeoutMillis 
)

Aquire a mutex, blocks until the mutex becomes available (according to the mutex's semantics). or 'timeoutMillis' milli seconds passed. When 'timeoutMillis' is zero, this function is identical to OS_MutexTryLock().

Parameters:
[in]lockThe mutex to acquire.
[in]timeoutMillisThe timeout to block.
Return values:
TRUEIf the mutex is locked. FALSE If the timeout was expired and the mutex can't be acquired during that time.
Availability:
  • O/S: Windows, Linux & macOS*
  • CPU: All
BOOL_T OS_MutexTimedLockTid ( volatile OS_MUTEX_TYPE *  lock0,
NATIVE_TID  myTid,
UINT32  timeoutMillis 
)

Aquire a mutex, blocks until the mutex becomes available (according to the mutex's semantics). or 'timeoutMillis' milli seconds passed. When 'timeoutMillis' is zero, this function is identical to OS_MutexTryLock(). This function is similar to OS_MutexTimedLock() except that it accept as an argument the thread ID of the thread that want to acquire the lock (which is usually the current thread).

Parameters:
[in]lockThe mutex to acquire.
[in]timeoutMillisThe timeout to block.
[in]tidThe thread ID of the thread that wants to acquire the mutex. This argument can be INVALID_NATIVE_TID if the thread ID is not known (e.g. in a mutex of type OS_MUTEX_DEPTH_SIMPLE).
Return values:
TRUEIf the mutex is locked. FALSE If the timeout was expired and the mutex can't be acquired during that time.
Availability:
  • O/S: Windows, Linux & macOS*
  • CPU: All
BOOL_T OS_MutexTryLock ( volatile OS_MUTEX_TYPE *  lock)

Tries to aquire a mutex:

  • If the mutex is available, acquire it and return true.
  • Otherwise, return false.
Parameters:
[in]lockThe mutex to acquire.
Return values:
TRUEIf the mutex was acquired.
Availability:
  • O/S: Windows, Linux & macOS*
  • CPU: All
BOOL_T OS_MutexTryLockTid ( volatile OS_MUTEX_TYPE *  lock0,
NATIVE_TID  myTid 
)

Tries to aquire a mutex:

  • If the mutex is available, acquire it and return true.
  • Otherwise, return false. This function is similar to OS_MutexTryLock() except that it accept as an argument the thread ID of the thread that want to acquire the lock (which is usually the current thread).
Parameters:
[in]lockThe mutex to acquire.
[in]tidThe thread ID of the thread that wants to acquire the mutex. This argument can be INVALID_NATIVE_TID if the thread ID is not known (e.g. in a mutex of type OS_MUTEX_DEPTH_SIMPLE).
Return values:
TRUEIf the mutex was acquired.
Availability:
  • O/S: Windows, Linux & macOS*
  • CPU: All
BOOL_T OS_MutexUnlock ( volatile OS_MUTEX_TYPE *  lock)

Releases a mutex.

Parameters:
[in]lockThe mutex to release.
Return values:
TRUEIf the mutex was locked and as a result of this call was unlocked.
Availability:
  • O/S: Windows, Linux & macOS*
  • CPU: All
 All Classes Variables