Changeset 922c7ce in mainline


Ignore:
Timestamp:
2005-10-01T22:51:14Z (19 years ago)
Author:
Jakub Jermar <jakub@…>
Branches:
lfn, master, serial, ticket/834-toolchain-update, topic/msim-upgrade, topic/simplify-dev-export
Children:
5e04b48d
Parents:
941d1e9
Message:

Doxygen-style comments for waitq.c.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • src/synch/waitq.c

    r941d1e9 r922c7ce  
    2727 */
    2828
    29 #include <context.h>
     29#include <synch/waitq.h>
     30#include <synch/synch.h>
     31#include <synch/spinlock.h>
    3032#include <proc/thread.h>
    31 
    32 #include <synch/synch.h>
    33 #include <synch/waitq.h>
    34 #include <synch/spinlock.h>
    35 
    3633#include <arch/asm.h>
    3734#include <arch/types.h>
     35#include <time/timeout.h>
    3836#include <arch.h>
    39 
     37#include <context.h>
    4038#include <list.h>
    4139
    42 #include <time/timeout.h>
    43 
     40/** Initialize wait queue
     41 *
     42 * Initialize wait queue.
     43 *
     44 * @param wq Pointer to wait queue to be initialized.
     45 */
    4446void waitq_initialize(waitq_t *wq)
    4547{
    … …  
    4951}
    5052
    51 /*
    52  * Called with interrupts disabled from clock() when sleep_timeout
    53  * timeouts. This function is not allowed to enable interrupts.
    54  *
    55  * It is supposed to try to remove 'its' thread from the waitqueue; it
    56  * can eventually fail to achieve this goal when these two events
    57  * overlap; in that case it behaves just as though there was no
    58  * timeout at all
     53/** Handle timeout during waitq_sleep_timeout() call
     54 *
     55 * This routine is called when waitq_sleep_timeout() timeouts.
     56 * Interrupts are disabled.
     57 *
     58 * It is supposed to try to remove 'its' thread from the wait queue;
     59 * it can eventually fail to achieve this goal when these two events
     60 * overlap. In that case it behaves just as though there was no
     61 * timeout at all.
     62 *
     63 * @param data Pointer to the thread that called waitq_sleep_timeout().
    5964 */
    6065void waitq_interrupted_sleep(void *data)
    … …  
    9398}
    9499
    95 /*
     100/** Sleep until either wakeup or timeout occurs
     101 *
    96102 * This is a sleep implementation which allows itself to be
    97103 * interrupted from the sleep, restoring a failover context.
    98104 *
     105 * Sleepers are organised in FIFO fashion in a structure called wait queue.
     106 *
    99107 * This function is really basic in that other functions as waitq_sleep()
    100108 * and all the *_timeout() functions use it.
    101109 *
    102  * The third argument controls whether only a conditional sleep
    103  * (non-blocking sleep) is called for when the second argument is 0.
     110 * @param wq Pointer to wait queue.
     111 * @param usec Timeout value in microseconds.
     112 * @param nonblocking Controls whether only a conditional sleep
     113 *        (non-blocking sleep) is called for when the usec argument is 0.
     114 *
     115 * Relation between 'usec' and 'nonblocking' is described by this table:
    104116 *
    105117 * usec | nonblocking | what happens if there is no missed_wakeup
    … …  
    109121 *  > 0 | x           | blocks with timeout until timeout or wakeup
    110122 *
    111  * return values:
    112  *  ESYNCH_WOULD_BLOCK
    113  *  ESYNCH_TIMEOUT
    114  *  ESYNCH_OK_ATOMIC
    115  *  ESYNCH_OK_BLOCKED
     123 * @return Returns one of: ESYNCH_WOULD_BLOCK, ESYNCH_TIMEOUT,
     124 *         ESYNCH_OK_ATOMIC, ESYNCH_OK_BLOCKED.
     125 *
     126 * Meaning of the return values is described by the following chart:
     127 *
     128 * ESYNCH_WOULD_BLOCK   Sleep failed because at the time of the call,
     129 *                      there was no pending wakeup.
     130 * ESYNCH_TIMEOUT       Sleep timed out.
     131 * ESYNCH_OK_ATOMIC     Sleep succeeded; at the time of the call,
     132 *                      where was a pending wakeup.
     133 * ESYNCH_OK_BLOCKED    Sleep succeeded; the full sleep was attempted.
    116134 */
    117135int waitq_sleep_timeout(waitq_t *wq, __u32 usec, int nonblocking)
    … …  
    193211
    194212
    195 /*
    196  * This is the SMP- and IRQ-safe wrapper meant for general use.
    197  */
    198 /*
    199  * Besides its 'normal' wakeup operation, it attempts to unregister possible timeout.
     213/** Wake up first thread sleeping in a wait queue
     214 *
     215 * Wake up first thread sleeping in a wait queue.
     216 * This is the SMP- and IRQ-safe wrapper meant for
     217 * general use.
     218 *
     219 * Besides its 'normal' wakeup operation, it attempts
     220 * to unregister possible timeout.
     221 *
     222 * @param wq Pointer to wait queue.
     223 * @param all If this is non-zero, all sleeping threads
     224 *        will be woken up and missed count will be zeroed.
    200225 */
    201226void waitq_wakeup(waitq_t *wq, int all)
    … …  
    212237}
    213238
    214 /*
    215  * This is the internal SMP- and IRQ-unsafe version of waitq_wakeup.
    216  * It assumes wq->lock is already locked.
     239/** Internal SMP- and IRQ-unsafe version of waitq_wakeup()
     240 *
     241 * This is the internal SMP- and IRQ-unsafe version
     242 * of waitq_wakeup(). It assumes wq->lock is already
     243 * locked and interrupts are already disabled.
     244 *
     245 * @param wq Pointer to wait queue.
     246 * @param all If this is non-zero, all sleeping threads
     247 *        will be woken up and missed count will be zeroed.
    217248 */
    218249void _waitq_wakeup_unsafe(waitq_t *wq, int all)
Note: See TracChangeset for help on using the changeset viewer.