diff options
Diffstat (limited to 'os/kernel/src/chmtx.c')
| -rw-r--r-- | os/kernel/src/chmtx.c | 61 |
1 files changed, 44 insertions, 17 deletions
diff --git a/os/kernel/src/chmtx.c b/os/kernel/src/chmtx.c index 93943bba0..9698d3cd8 100644 --- a/os/kernel/src/chmtx.c +++ b/os/kernel/src/chmtx.c @@ -27,8 +27,8 @@ * <h2>Operation mode</h2>
* A mutex is a threads synchronization object that can be in two
* distinct states:
- * - Not owned.
- * - Owned by a thread.
+ * - Not owned (unlocked).
+ * - Owned by a thread (locked).
* .
* Operations defined for mutexes:
* - <b>Lock</b>: The mutex is checked, if the mutex is not owned by
@@ -39,8 +39,6 @@ * priority thread waiting in the queue, if any, is resumed and made
* owner of the mutex.
* .
- * In order to use the Mutexes APIs the @p CH_USE_MUTEXES option must
- * be enabled in @p chconf.h.
* <h2>Constraints</h2>
* In ChibiOS/RT the Unlock operations are always performed in
* lock-reverse order. The unlock API does not even have a parameter,
@@ -59,15 +57,21 @@ * 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.
+ * @pre In order to use the mutex APIs the @p CH_USE_MUTEXES option
+ * must be enabled in @p chconf.h.
+ * @post Enabling mutexes requires 5-12 (depending on the architecture)
+ * extra bytes in the @p Thread structure.
* @{
*/
#include "ch.h"
-#if CH_USE_MUTEXES
+#if CH_USE_MUTEXES || defined(__DOXYGEN__)
/**
* @brief Initializes s @p Mutex structure.
+ * @note This function can be invoked before the kernel is initialized
+ * because it just prepares a @p Mutex structure.
*
* @param[out] mp pointer to a @p Mutex structure
*/
@@ -81,6 +85,8 @@ void chMtxInit(Mutex *mp) { /**
* @brief Locks the specified mutex.
+ * @post The mutex is locked and inserted in the per-thread stack of owned
+ * mutexes.
*
* @param[in] mp pointer to the @p Mutex structure
*/
@@ -95,6 +101,8 @@ void chMtxLock(Mutex *mp) { /**
* @brief Locks the specified mutex.
+ * @post The mutex is locked and inserted in the per-thread stack of owned
+ * mutexes.
*
* @param[in] mp pointer to the @p Mutex structure
*/
@@ -164,12 +172,17 @@ void chMtxLockS(Mutex *mp) { /**
* @brief Tries to lock a mutex.
- * @details 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.
+ * @details This function attempts to lock a mutex, if the mutex is already
+ * locked by another thread then the function exits without waiting.
+ * @post The mutex is locked and inserted in the per-thread stack of owned
+ * mutexes.
+ * @note This function does not have any overhead related to the
+ * priority inheritance mechanism because it does not try to
+ * enter a sleep state.
*
* @param[in] mp pointer to the @p Mutex structure
- * @retval TRUE if the mutex was successfully acquired
+ * @return The operation status.
+ * @retval TRUE if the mutex has been successfully acquired
* @retval FALSE if the lock attempt failed.
*/
bool_t chMtxTryLock(Mutex *mp) {
@@ -185,12 +198,17 @@ bool_t chMtxTryLock(Mutex *mp) { /**
* @brief Tries to lock a mutex.
- * @details 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.
+ * @details This function attempts to lock a mutex, if the mutex is already
+ * taken by another thread then the function exits without waiting.
+ * @post The mutex is locked and inserted in the per-thread stack of owned
+ * mutexes.
+ * @note This function does not have any overhead related to the
+ * priority inheritance mechanism because it does not try to
+ * enter a sleep state.
*
* @param[in] mp pointer to the @p Mutex structure
- * @retval TRUE if the mutex was successfully acquired
+ * @return The operation status.
+ * @retval TRUE if the mutex has been successfully acquired
* @retval FALSE if the lock attempt failed.
*/
bool_t chMtxTryLockS(Mutex *mp) {
@@ -207,8 +225,11 @@ bool_t chMtxTryLockS(Mutex *mp) { /**
* @brief Unlocks the next owned mutex in reverse lock order.
+ * @pre The invoking thread <b>must</b> have at least one owned mutex.
+ * @post The mutex is unlocked and removed from the per-thread stack of
+ * owned mutexes.
*
- * @return The pointer to the unlocked mutex.
+ * @return A pointer to the unlocked mutex.
*/
Mutex *chMtxUnlock(void) {
Thread *ctp = currp;
@@ -260,9 +281,13 @@ Mutex *chMtxUnlock(void) { /**
* @brief Unlocks the next owned mutex in reverse lock order.
- * @note This function does not reschedule internally.
+ * @pre The invoking thread <b>must</b> have at least one owned mutex.
+ * @post The mutex is unlocked and removed from the per-thread stack of
+ * owned mutexes.
+ * @post This function does not reschedule so a call to a rescheduling
+ * function must be performed before unlocking the kernel.
*
- * @return The pointer to the unlocked mutex.
+ * @return A pointer to the unlocked mutex.
*/
Mutex *chMtxUnlockS(void) {
Thread *ctp = currp;
@@ -311,7 +336,9 @@ Mutex *chMtxUnlockS(void) { /**
* @brief Unlocks all the mutexes owned by the invoking thread.
- * @details This function is <b>MUCH MORE</b> efficient than releasing the
+ * @post The stack of owned mutexes is emptied and all the found
+ * mutexes are unlocked.
+ * @note This function is <b>MUCH MORE</b> 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.
|