From ad3d21e81592481539a56e93234f5bf1fa2c0504 Mon Sep 17 00:00:00 2001
From: gdisirio <gdisirio@35acf78f-673a-0410-8e92-d51de3d6d3f4>
Date: Tue, 16 Mar 2010 19:36:21 +0000
Subject: Documentation reorganization. Moved the description from kernel.dox
 into the source code for ease of editing and reference.

git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1746 35acf78f-673a-0410-8e92-d51de3d6d3f4
---
 os/kernel/src/chcond.c | 52 +++++++++++++++++++++++++++++++++-----------------
 1 file changed, 35 insertions(+), 17 deletions(-)

(limited to 'os/kernel/src/chcond.c')

diff --git a/os/kernel/src/chcond.c b/os/kernel/src/chcond.c
index 33ffe98b1..c450b0c32 100644
--- a/os/kernel/src/chcond.c
+++ b/os/kernel/src/chcond.c
@@ -26,6 +26,15 @@
  * @brief   Condition Variables code.
  *
  * @addtogroup condvars Condition Variables
+ * @details This module implements the Condition Variables mechanism. Condition
+ *          variables are an extensions to the Mutex subsystem and cannot
+ *          work alone.
+ *          <h2>Operation mode</h2>
+ *          The condition variable is a synchronization object meant to be
+ *          used inside a zone protected by a @p Mutex. Mutexes and CondVars
+ *          together can implement a Monitor construct.<br>
+ *          In order to use the Condition Variables APIs the @p CH_USE_CONDVARS
+ *          option must be enabled in @p chconf.h.
  * @{
  */
 
@@ -107,10 +116,11 @@ void chCondBroadcastI(CondVar *cp) {
 
 /**
  * @brief   Waits on the condition variable releasing the mutex lock.
- * @details Releases the mutex, waits on the condition variable, and finally
- *          acquires the mutex again. This is done atomically.
- * @note    The thread MUST already have locked the mutex when calling
- *          @p chCondWait().
+ * @details Releases the currently owned mutex, waits on the condition
+ *          variable, and finally acquires the mutex again. All the sequence
+ *          is performed atomically.
+ * @note    The invoking thread <b>must</b> have at least one owned mutex on
+ *          entry.
  *
  * @param[in] cp        pointer to the @p CondVar structure
  * @return              The wakep mode.
@@ -128,10 +138,11 @@ msg_t chCondWait(CondVar *cp) {
 
 /**
  * @brief   Waits on the condition variable releasing the mutex lock.
- * @details Releases the mutex, waits on the condition variable, and finally
- *          acquires the mutex again. This is done atomically.
- * @note    The thread MUST already have locked the mutex when calling
- *          @p chCondWaitS().
+ * @details Releases the currently owned mutex, waits on the condition
+ *          variable, and finally acquires the mutex again. All the sequence
+ *          is performed atomically.
+ * @note    The invoking thread <b>must</b> have at least one owned mutex on
+ *          entry.
  *
  * @param[in] cp        pointer to the @p CondVar structure
  * @return              The wakep mode.
@@ -160,10 +171,13 @@ msg_t chCondWaitS(CondVar *cp) {
 #if CH_USE_CONDVARS_TIMEOUT
 /**
  * @brief   Waits on the condition variable releasing the mutex lock.
- * @details Releases the mutex, waits on the condition variable, and finally
- *          acquires the mutex again. This is done atomically.
- * @note    The thread MUST already have locked the mutex when calling
- *          @p chCondWaitTimeout().
+ * @details Releases the currently owned mutex, waits on the condition
+ *          variable, and finally acquires the mutex again. All the sequence
+ *          is performed atomically.
+ * @note    The invoking thread <b>must</b> have at least one owned mutex on
+ *          entry.
+ * @note    Exiting the function because a timeout does not re-acquire the
+ *          mutex, the mutex ownership is lost.
  *
  * @param[in] cp        pointer to the @p CondVar structure
  * @param[in] time      the number of ticks before the operation timeouts,
@@ -188,10 +202,13 @@ msg_t chCondWaitTimeout(CondVar *cp, systime_t time) {
 
 /**
  * @brief   Waits on the condition variable releasing the mutex lock.
- * @details Releases the mutex, waits on the condition variable, and finally
- *          acquires the mutex again. This is done atomically.
- * @note    The thread MUST already have locked the mutex when calling
- *          @p chCondWaitTimeoutS().
+ * @details Releases the currently owned mutex, waits on the condition
+ *          variable, and finally acquires the mutex again. All the sequence
+ *          is performed atomically.
+ * @note    The invoking thread <b>must</b> have at least one owned mutex on
+ *          entry.
+ * @note    Exiting the function because a timeout does not re-acquire the
+ *          mutex, the mutex ownership is lost.
  *
  * @param[in] cp        pointer to the @p CondVar structure
  * @param[in] time      the number of ticks before the operation timeouts,
@@ -218,7 +235,8 @@ msg_t chCondWaitTimeoutS(CondVar *cp, systime_t time) {
   currp->p_u.wtobjp = cp;
   prio_insert(currp, &cp->c_queue);
   msg = chSchGoSleepTimeoutS(THD_STATE_WTCOND, time);
-  chMtxLockS(mp);
+  if (msg != RDY_TIMEOUT)
+    chMtxLockS(mp);
   return msg;
 }
 #endif /* CH_USE_CONDVARS_TIMEOUT */
-- 
cgit v1.2.3