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]	mutex	Pointer to the mutex.
[in]	timeout_in_milliseconds	Time to wait for the mutex before giving up. To wait indefinitely, use TIME_WAIT_FOREVER.

Return values

true	Mutex was successfully acquired.
false	Failed 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

true	Mutex was successfully initialized.
false	Failed to initialize the mutex.

Parameters

[out]	mutex	Mutex struct to initialize.
[in]	name	Name 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

true	Mutex was successfully destroyed.
false	Failed to destroy the mutex.

Parameters

[in,out]

mutex

Pointer 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

NULL	No thread holds the mutex.

Parameters

[in]

mutex

Pointer 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]

mutex

Pointer to the mutex.