|void||mtx_init (mtx_t *mtx)|
|void||mtx_deinit (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)|
|void||mtx_set_name (mtx_t *mtx, const char *name)|
|void||mtx_show_with_fmt_fn (fmt_fn_t fn)|
Allocates and initialises a mutex handle. See mtx_init() for further details.
|void mtx_deinit||(||mtx_t *||mtx||)|
Deinitialises a mutex handle. 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).
|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().
|void mtx_init||(||mtx_t *||mtx||)|
Initialises a mutex handle. The mutex is unlocked when created.
This function must not be called with a handle that was returned by mtx_create().
|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().
|int mtx_lock_tmo||(||mtx_t *||mtx,|
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.
|time||Number of ticks to wait|
|void mtx_set_name||(||mtx_t *||mtx,|
|const char *||name|
Sets the name of the mutex.
This function is only used for debugging purposes, where a kernel-aware debugger may present this name to the user.
The name will be stored in a separate table for kernel objects. If the name could not be set, the error is silently ignored.
|name||String describing mutex|
Prints all allocated mutexes to stdout using rprintp(). This may prove useful for debugging purposes. This function should not be called from application code, but may be called from e.g. uerror() or an exception handler.
Same as mtx_show(), but using supplied function for formatted output.
|fn||Function for formatted output|
|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.