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


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


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,
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().

[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.
[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.
[in,out]mutexPointer to the mutex.
struct ltrx_thread* ltrx_mutex_held_by ( const struct ltrx_mutex *  mutex)

Get ID of thread holding mutex.

Pointer to the thread holding the mutex.
Return values
NULLNo thread holds the mutex.
[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.

[in,out]mutexPointer to the mutex.