OSAPI Mutex

Mutex API. More...

Data Structures
struct	OSAPI_MutexBase

Typedefs
typedef struct OSAPI_Mutex	OSAPI_Mutex_T

Functions
RTI_BOOL	OSAPI_Mutex_delete (OSAPI_Mutex_T *mutex)
	Delete a mutex.
OSAPI_Mutex_T *	OSAPI_Mutex_new (void)
	Create a mutex.
RTI_BOOL	OSAPI_Mutex_take (OSAPI_Mutex_T *self)
	Take a mutex.
RTI_BOOL	OSAPI_Mutex_give (OSAPI_Mutex_T *self)
	Give a mutex.
RTI_BOOL	OSAPI_Mutex_release (OSAPI_Mutex_T *self, RTI_UINT32 *level)
	Release a mutex temporarily at an arbitrary point in the code.
RTI_BOOL	OSAPI_Mutex_resume (OSAPI_Mutex_T *self, RTI_UINT32 level)
	Resume taking a mutex passing in the corrent state.

---

Detailed Description

Mutex API.

---

Typedef Documentation

typedef struct OSAPI_Mutex OSAPI_Mutex_T

Abstract Mutex type

---

Function Documentation

RTI_BOOL OSAPI_Mutex_delete

(

OSAPI_Mutex_T *

mutex

)

Delete a mutex.

Parameters:

[in]

mutex

Delete a mutex created with OSAPI_Mutex_new.

Returns:

RTI_TRUE on success, RTI_FALSE on failure

OSAPI_Mutex_T* OSAPI_Mutex_new

(

void

)

Create a mutex.

Returns:

Pointer to a mutex in a not taken condition. NULL on failure.

See also:

OSAPI_Mutex_delete

RTI_BOOL OSAPI_Mutex_take

(

OSAPI_Mutex_T *

self

)

Take a mutex.

A mutex can only be taken if it is not currently already taken by another thread; it CAN be taken if is it already taken by the same thread. In order to release a mutex, it must be given as many times a it has been taken. Note that take will block indefinitely.

Note: the mutex is not required to support priority inversion; there is no protection against deadlocks or starvation.

Parameters:

[in]

self

Take a mutex previously created with OSAPI_Mutex_new.

Returns:

RTI_TRUE on success, RTI_FALSE on failure

See also:

OSAPI_Mutex_give, OSAPI_Mutex_new

RTI_BOOL OSAPI_Mutex_give

(

OSAPI_Mutex_T *

self

)

Give a mutex.

A mutex can only be given if it is owned by the calling thread. Furthermore, it must be given as many times as it has been taken.

Parameters:

[in]

self

Take a mutex previously created with OSAPI_Mutex_new.

Returns:

RTI_TRUE on success, RTI_FALSE on failure

See also:

OSAPI_Mutex_take, OSAPI_Mutex_new

RTI_BOOL OSAPI_Mutex_release	(	OSAPI_Mutex_T *	self,
		RTI_UINT32 *	level
	)

Release a mutex temporarily at an arbitrary point in the code.

The normal use of a mutex to take/return an equal number of times as part of the code-path. However, in some cases it is necessary to temporarily release a mutex (and save its state) and then later resume it.

Parameters:

[in]	self	The mutex to release
[out]	level	The current level of the mutex. This level must passed to OSAPI_Mutex_resume.

Returns:

RTI_TRUE on success, RTI_FALSE on failure

See also:

OSAPI_Mutex_take, OSAPI_Mutex_new

RTI_BOOL OSAPI_Mutex_resume	(	OSAPI_Mutex_T *	self,
		RTI_UINT32	level
	)

Resume taking a mutex passing in the corrent state.

Parameters:

[in]	self	The mutex to resume
	[level]	level The current state of the mutex, returned from OSAPI_Mutex_release.

Returns:

RTI_TRUE on success, RTI_FALSE on failure