4.2.0.0R6
Software Development Kit
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Modules
Mutual Exclusion

Macros

#define LTRX_MUTEX_WAIT(mutex, timeout_in_milliseconds)
 Wait for a mutex. More...
 

Functions

bool ltrx_mutex_create (struct ltrx_mutex *mutex, const char *name)
 Create a mutex. More...
 
bool ltrx_mutex_destroy (struct ltrx_mutex *mutex)
 Destroy a mutex. More...
 
struct ltrx_thread * ltrx_mutex_held_by (const struct ltrx_mutex *mutex)
 Get ID of thread holding mutex. More...
 
void ltrx_mutex_signal (struct ltrx_mutex *mutex)
 Relinquish a mutex. More...
 

Detailed Description

A mutex facilitates mutual exclusion among two or more concurrent threads.

Nested usage of the same mutex is allowed.

Warning: If two or more distinct mutexes are to be acquired at the same time, all of your threads must acquire them in the same sequence; otherwise deadlock will result.

Macro Definition Documentation

#define LTRX_MUTEX_WAIT (   mutex,
  timeout_in_milliseconds 
)
Value:
ltrx_mutex_wait_do_not_call_directly( \
__FILE__, __LINE__, mutex, timeout_in_milliseconds \
)

Wait for a mutex.

Block this thread up to the specified timeout_in_milliseconds while waiting to acquire exclusive control of mutex.

Warning: Check the return value even if you specify TIME_WAIT_FOREVER because your thread can return early if another thread calls ltrx_thread_wake().

Parameters
[in,out]mutexPointer to the mutex.
[in]timeout_in_millisecondsTime to wait for the mutex before giving up. To wait indefinitely, use TIME_WAIT_FOREVER.
Return values
trueMutex was successfully acquired.
falseFailed to acquire the mutex.

Function Documentation

bool ltrx_mutex_create ( struct ltrx_mutex *  mutex,
const char *  name 
)

Create a mutex.

First you declare a struct to house the mutex, then initialize it by calling this function.

Return values
trueMutex was successfully initialized.
falseFailed to initialize the mutex.
Parameters
[out]mutexMutex struct to initialize.
[in]nameName of mutex.
bool ltrx_mutex_destroy ( struct ltrx_mutex *  mutex)

Destroy a mutex.

First you create the mutex via ltrx_mutex_create(). Later you may destroy it by calling this function.

Warning: This function must be called before the mutex struct itself is destroyed by going out of scope; otherwise the operating environment will be corrupted.

Return values
trueMutex was successfully destroyed.
falseFailed to destroy the mutex.
Parameters
[in,out]mutexPointer to the mutex.
struct ltrx_thread* ltrx_mutex_held_by ( const struct ltrx_mutex *  mutex)

Get ID of thread holding mutex.

Returns
Pointer to the thread holding the mutex.
Return values
NULLNo thread holds the mutex.
Parameters
[in]mutexPointer to the mutex.
void ltrx_mutex_signal ( struct ltrx_mutex *  mutex)

Relinquish a mutex.

First you acquire the mutex via LTRX_MUTEX_WAIT. Later you may relinquish it by calling this function.

Parameters
[in,out]mutexPointer to the mutex.