rt-kernel: User & Reference Manual  424
Functions
Mutexes

Functions

void mtx_init (mtx_t *mtx)
mtx_t * mtx_create (void)
void mtx_destroy (mtx_t *mtx)
void mtx_lock (mtx_t *mtx)
int mtx_lock_tmo (mtx_t *mtx, tick_t time)
void mtx_unlock (mtx_t *mtx)

Function Documentation

mtx_t* mtx_create ( void  )

Allocates and initialises a mutex handle. See mtx_init() for further details.

Returns:
The mutex handle to be used in all subsequent operations on the mutex.
void mtx_destroy ( mtx_t *  mtx)

Frees the resources allocated by the mutex. The mutex must not be in use when this function is called (no task can be waiting for the mutex, nor can they do so at any time after calling this function).

This function must only be called with a handle that was returned by mtx_create().

Parameters:
mtxMutex handle
void mtx_init ( mtx_t *  mtx)

Initialises a mutex handle. The mutex is unlocked when created.

void mtx_lock ( mtx_t *  mtx)

Locks the mutex. If the mutex is available the function will return immediately. If it is not available, the calling task will be put in the WAITING state until the mutex becomes available.

Additionally, if the mutex is not available, and it is currently locked by a task with a lower priority than the calling task, then the priority of that task will be raised to the priority of the calling task. The priority is restored when the mutex is unlocked. This is known as the priority inheritance protocol and is used to overcome the priority inversion problem.

Mutexes can be locked recursively. Recursive locking occurs when a task locks a mutex more than once. In this case the task is not blocked. rt-kernel keeps track of the recursive lock count on the mutex so that the mutex is only unlocked when the lock count reaches zero. In other words, the mutex is unlocked when the number of calls to mtx_unlock() is equal to the number of calls to mtx_lock().

Parameters:
mtxMutex handle
int mtx_lock_tmo ( mtx_t *  mtx,
tick_t  time 
)

Analogous to mtx_lock(), but a maximum time to wait can be specified. If the mutex is not available, the calling task will wait until the mutex becomes available, or the number of ticks given by time expires.

Parameters:
mtxMutex handle
timeNumber of ticks to wait
Returns:
0 if the mutex was acquired successfully, 1 if the service timed out.
void mtx_unlock ( mtx_t *  mtx)

Unlocks the mutex. The call will reduce the recursive lock count and return immediately if the calling task has locked the mutex more than once. Otherwise, the first task that was waiting on the mutex (if any) will be put in the READY state.

The priority of the task will be restored to its original state if it had been increased due to the priority inheritance protocol.

Parameters:
mtxMutex handle

rt-kernel