PinCRT
Classes | Macros | Typedefs | Functions
Mutex

Classes

struct  _OS_APIS_MUTEX_TYPE
 

Macros

#define OS_APIS_MUTEX_DEPTH_SIMPLE_INITIALIZER
 
#define OS_APIS_MUTEX_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)
 

Detailed Description

Macro Definition Documentation

◆ OS_APIS_MUTEX_DEPTH_RECURSIVE_INITIALIZER

#define OS_APIS_MUTEX_DEPTH_RECURSIVE_INITIALIZER
Value:
{ \
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

◆ OS_APIS_MUTEX_DEPTH_SIMPLE_INITIALIZER

#define OS_APIS_MUTEX_DEPTH_SIMPLE_INITIALIZER
Value:
{ \
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

◆ OS_MUTEX_TYPE_IMPL

typedef struct _OS_APIS_MUTEX_TYPE OS_MUTEX_TYPE_IMPL

This type holds a representation of a mutex.

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

Function Documentation

◆ OS_MutexDestroy()

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

◆ OS_MutexGetOwner()

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

◆ OS_MutexGetRecursionLevel()

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

◆ OS_MutexInit()

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

◆ OS_MutexIsLocked()

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

◆ OS_MutexLock()

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

◆ OS_MutexLockTid()

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

◆ OS_MutexRecursiveInit()

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

◆ OS_MutexTimedLock()

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

◆ OS_MutexTimedLockTid()

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

◆ OS_MutexTryLock()

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

◆ OS_MutexTryLockTid()

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

◆ OS_MutexUnlock()

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
Generated by   doxygen 1.8.17