Mutexes

Functions

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 (void)
 
void mtx_show_with_fmt_fn (fmt_fn_t fn)
 

Detailed Description

Function Documentation

◆ mtx_create()

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.

◆ mtx_deinit()

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

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

Parameters
mtxMutex handle

◆ mtx_destroy()

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

◆ mtx_init()

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

Parameters
mtxMutex handle

◆ mtx_lock()

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

◆ mtx_lock_tmo()

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.

◆ mtx_set_name()

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.

Parameters
mtxMutex handle
nameString describing mutex

◆ mtx_show()

void mtx_show ( void  )

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.

◆ mtx_show_with_fmt_fn()

void mtx_show_with_fmt_fn ( fmt_fn_t  fn)

Same as mtx_show(), but using supplied function for formatted output.

Parameters
fnFunction for formatted output

◆ mtx_unlock()

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