Architecture - Reference Manual - Guides
|
ChibiOS/RT Architecture - Reference Manual - Guides |
|
Mutexes related APIs and services.
A mutex is a threads synchronization object that can be in two distinct states:
Operations defined for mutexes:
In order to use the Mutexes APIs the CH_USE_MUTEXES option must be enabled in chconf.h.
In ChibiOS/RT the Unlock operations are always performed in lock-reverse order. The unlock API does not even have a parameter, the mutex to unlock is selected from an internal, per-thread, stack of owned mutexes. This both improves the performance and is required for an efficient implementation of the priority inheritance mechanism.
The mutexes in ChibiOS/RT implements the full priority inheritance mechanism in order handle the priority inversion problem.
When a thread is queued on a mutex, any thread, directly or indirectly, holding the mutex gains the same priority of the waiting thread (if their priority was not already equal or higher). The mechanism works with any number of nested mutexes and any number of involved threads. The algorithm complexity (worst case) is N with N equal to the number of nested mutexes.
Data Structures | |
| struct | Mutex |
| Mutex structure. More... | |
Defines | |
| #define | _MUTEX_DATA(name) {_THREADSQUEUE_DATA(name.m_queue), NULL, NULL} |
| Data part of a static mutex initializer. | |
| #define | MUTEX_DECL(name) Mutex name = _MUTEX_DATA(name) |
| Static mutex initializer. | |
| #define | chMtxQueueNotEmptyS(mp) notempty(&(mp)->m_queue) |
Returns TRUE if the mutex queue contains at least a waiting thread. | |
Typedefs | |
| typedef struct Mutex | Mutex |
| Mutex structure. | |
Functions | |
| void | chMtxInit (Mutex *mp) |
Initializes s Mutex structure. | |
| void | chMtxLock (Mutex *mp) |
| Locks the specified mutex. | |
| void | chMtxLockS (Mutex *mp) |
| Locks the specified mutex. | |
| bool_t | chMtxTryLock (Mutex *mp) |
| Tries to lock a mutex. | |
| bool_t | chMtxTryLockS (Mutex *mp) |
| Tries to lock a mutex. | |
| Mutex * | chMtxUnlock (void) |
| Unlocks the next owned mutex in reverse lock order. | |
| Mutex * | chMtxUnlockS (void) |
| Unlocks the next owned mutex in reverse lock order. | |
| void | chMtxUnlockAll (void) |
| Unlocks all the mutexes owned by the invoking thread. | |
| #define _MUTEX_DATA | ( | name | ) | {_THREADSQUEUE_DATA(name.m_queue), NULL, NULL} |
| #define MUTEX_DECL | ( | name | ) | Mutex name = _MUTEX_DATA(name) |
Static mutex initializer.
Statically initialized mutexes require no explicit initialization using chMtxInit().
| [in] | name | the name of the mutex variable |
| #define chMtxQueueNotEmptyS | ( | mp | ) | notempty(&(mp)->m_queue) |
Returns TRUE if the mutex queue contains at least a waiting thread.
Definition at line 89 of file chmtx.h.
Referenced by chMtxUnlock(), chMtxUnlockAll(), and chMtxUnlockS().
| void chMtxInit | ( | Mutex * | mp | ) |
Initializes s Mutex structure.
| [out] | mp | pointer to a Mutex structure |
Definition at line 81 of file chmtx.c.
References chDbgCheck, Mutex::m_owner, Mutex::m_queue, and queue_init.
Referenced by chHeapInit(), heap_init(), chibios_rt::Mutex::Mutex(), and spiObjectInit().
| void chMtxLock | ( | Mutex * | mp | ) |
Locks the specified mutex.
| [in] | mp | pointer to the Mutex structure |
Definition at line 94 of file chmtx.c.
References chMtxLockS(), chSysLock, and chSysUnlock.
Referenced by chibios_rt::Mutex::Lock(), and spiAcquireBus().
| void chMtxLockS | ( | Mutex * | mp | ) |
Locks the specified mutex.
| [in] | mp | pointer to the Mutex structure |
Definition at line 108 of file chmtx.c.
References chDbgAssert, chDbgCheck, chSchGoSleepS(), chSchReadyI(), dequeue(), Mutex::m_next, Mutex::m_owner, Mutex::m_queue, Thread::p_mtxlist, Thread::p_prio, Thread::p_state, Thread::p_u, prio_insert(), THD_STATE_READY, THD_STATE_SNDMSG, THD_STATE_WTCOND, THD_STATE_WTMTX, THD_STATE_WTSEM, and Thread::wtobjp.
Referenced by chCondWaitS(), chCondWaitTimeoutS(), and chMtxLock().
Tries to lock a mutex.
This function does not have any overhead related to the priority inheritance mechanism because it does not try to enter a sleep state on the mutex.
| [in] | mp | pointer to the Mutex structure |
| TRUE | if the mutex was successfully acquired | |
| FALSE | if the lock attempt failed. |
Definition at line 178 of file chmtx.c.
References chMtxTryLockS(), chSysLock, and chSysUnlock.
Referenced by chibios_rt::Mutex::TryLock().
Tries to lock a mutex.
This function does not have any overhead related to the priority inheritance mechanism because it does not try to enter a sleep state on the mutex.
| [in] | mp | pointer to the Mutex structure |
| TRUE | if the mutex was successfully acquired | |
| FALSE | if the lock attempt failed. |
Definition at line 199 of file chmtx.c.
References chDbgCheck, currp, Mutex::m_next, and Mutex::m_owner.
Referenced by chMtxTryLock().
| Mutex * chMtxUnlock | ( | void | ) |
Unlocks the next owned mutex in reverse lock order.
Definition at line 216 of file chmtx.c.
References chDbgAssert, chMtxQueueNotEmptyS, chSchWakeupS(), chSysLock, chSysUnlock, fifo_remove(), Mutex::m_next, Mutex::m_owner, Mutex::m_queue, Thread::p_mtxlist, ThreadsQueue::p_next, Thread::p_prio, Thread::p_realprio, and RDY_OK.
Referenced by spiReleaseBus(), and chibios_rt::Mutex::Unlock().
| Mutex * chMtxUnlockS | ( | void | ) |
Unlocks the next owned mutex in reverse lock order.
Definition at line 270 of file chmtx.c.
References chDbgAssert, chMtxQueueNotEmptyS, chSchReadyI(), fifo_remove(), Mutex::m_next, Mutex::m_owner, Mutex::m_queue, Thread::p_mtxlist, ThreadsQueue::p_next, Thread::p_prio, and Thread::p_realprio.
Referenced by chCondWaitS(), and chCondWaitTimeoutS().
| void chMtxUnlockAll | ( | void | ) |
Unlocks all the mutexes owned by the invoking thread.
This function is MUCH MORE efficient than releasing the mutexes one by one and not just because the call overhead, this function does not have any overhead related to the priority inheritance mechanism.
Definition at line 322 of file chmtx.c.
References chMtxQueueNotEmptyS, chSchReadyI(), chSchRescheduleS(), chSysLock, chSysUnlock, fifo_remove(), Mutex::m_next, Mutex::m_owner, Mutex::m_queue, Thread::p_mtxlist, Thread::p_prio, and Thread::p_realprio.
1.7.1