Changeset a783ca4 in mainline for src/synch

Timestamp:

2005-10-11T20:25:46Z (20 years ago)

Author:

Jakub Jermar <jakub@…>

Branches:

lfn, master, serial, ticket/834-toolchain-update, topic/msim-upgrade, topic/simplify-dev-export

Children:

26f9943

Parents:

a016b63

Message:

Fix doxygen comments.

Location:

src/synch

Files:

• condvar.c (modified) (3 diffs)
• mutex.c (modified) (1 diff)
• waitq.c (modified) (1 diff)

src/synch/condvar.c

@@ -48 +48 @@
  * to the first waiting thread by waking it up.
  *
- * @param Condition variable.
+ * @param cv Condition variable.
  */
 void condvar_signal(condvar_t *cv)
@@ -60 +60 @@
  * to all waiting threads by waking them up.
  *
- * @param Condition variable.
+ * @param cv Condition variable.
  */
 void condvar_broadcast(condvar_t *cv)
@@ -71 +71 @@
  * Wait for the condition becoming true.
  *
- * @param Condition variable.
+ * @param cv Condition variable.
+ * @param mtx Mutex.
+ * @param usec Timeout value in microseconds.
+ * @param trywait Blocking versus non-blocking operation mode switch.
+ *
+ * For exact description of possible combinations of
+ * 'usec' and 'trywait', see comment for waitq_sleep_timeout().
+ *
+ * @return See comment for waitq_sleep_timeout().
  */
 int _condvar_wait_timeout(condvar_t *cv, mutex_t *mtx, __u32 usec, int trywait)

src/synch/mutex.c

@@ -47 +47 @@
  * Timeout mode and non-blocking mode can be requested.
  *
- * @param mxt Mutex.
+ * @param mtx Mutex.
  * @param usec Timeout in microseconds.
  * @param trylock Switches between blocking and non-blocking mode.

src/synch/waitq.c

@@ -109 +109 @@
  *
  * @param wq Pointer to wait queue.
- * @param usec Timeout value in microseconds.
- * @param nonblocking Controls whether only a conditional sleep
- *        (non-blocking sleep) is called for when the usec argument is 0.
- *
- * Relation between 'usec' and 'nonblocking' is described by this table:
- *
- * usec | nonblocking | what happens if there is no missed_wakeup
- * -----+-------------+--------------------------------------------
- *  0   | 0           | blocks without timeout until wakeup
- *  0   | <> 0        | immediately returns ESYNCH_WOULD_BLOCK
- *  > 0 | x           | blocks with timeout until timeout or wakeup
+ * @param usec Timeout in microseconds.
+ * @param nonblocking Blocking vs. non-blocking operation mode switch.
+ *
+ * If usec is greater than zero, regardless of the value of @nonblocking,
+ * the call will not return until either timeout or wakeup comes.
+ *
+ * If usec is zero and nonblocking is zero (false), the call
+ * will not return until wakeup comes.
+ *
+ * If usec is zero and nonblocking is non-zero (true), the call will
+ * immediately return, reporting either success or failure.
  *
  * @return Returns one of: ESYNCH_WOULD_BLOCK, ESYNCH_TIMEOUT,
  *         ESYNCH_OK_ATOMIC, ESYNCH_OK_BLOCKED.
  *
- * Meaning of the return values is described by the following chart:
- *
- * ESYNCH_WOULD_BLOCK   Sleep failed because at the time of the call,
- *                      there was no pending wakeup.
- * ESYNCH_TIMEOUT       Sleep timed out.
- * ESYNCH_OK_ATOMIC     Sleep succeeded; at the time of the call,
- *                      where was a pending wakeup.
- * ESYNCH_OK_BLOCKED    Sleep succeeded; the full sleep was attempted.
+ * ESYNCH_WOULD_BLOCK means that the sleep failed because at the time
+ * of the call there was no pending wakeup.
+ *
+ * ESYNCH_TIMEOUT means that the sleep timed out.
+ *
+ * ESYNCH_OK_ATOMIC means that the sleep succeeded and that there was
+ * a pending wakeup at the time of the call. The caller was not put
+ * asleep at all.
+ * 
+ * ESYNCH_OK_BLOCKED means that the sleep succeeded; the full sleep was 
+ * attempted.
  */
 int waitq_sleep_timeout(waitq_t *wq, __u32 usec, int nonblocking)