lib/silcutil/silccond.h

   1 /*
   2
   3   silccond.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 2006 - 2007 Pekka Riikonen
   8
   9   This program is free software; you can redistribute it and/or modify
  10   it under the terms of the GNU General Public License as published by
  11   the Free Software Foundation; version 2 of the License.
  12
  13   This program is distributed in the hope that it will be useful,
  14   but WITHOUT ANY WARRANTY; without even the implied warranty of
  15   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16   GNU General Public License for more details.
  17
  18 */
  19
  20 /****h* silcutil/SILC Condition Variable Interface
  21  *
  22  * DESCRIPTION
  23  *
  24  * A condition variable interface for multi-thread synchronization.
  25  * Condition variables enable threads to suspend execution and yield
  26  * the processors until some predicate on some shared data is satisfied.
  27  *
  28  * EXAMPLE
  29  *
  30  * Thread 1:
  31  *
  32  * // Wait for signal
  33  * silc_mutex_lock(lock);
  34  * while (c->a == NULL)
  35  *   silc_cond_wait(cond, lock);
  36  * ...
  37  * silc_mutex_unlock(lock);
  38  *
  39  * Thread 2:
  40  *
  41  * // Signal
  42  * silc_mutex_lock(lock);
  43  * c->a = context;
  44  * silc_cond_signal(cond);
  45  * silc_mutex_unlock(lock);
  46  *
  47  ***/
  48
  49 #ifndef SILCCOND_H
  50 #define SILCCOND_H
  51
  52 /****s* silcutil/SilcCondAPI/SilcCond
  53  *
  54  * NAME
  55  *
  56  *    typedef struct SilcCondStruct *SilcCond;
  57  *
  58  * DESCRIPTION
  59  *
  60  *    This context is the actual condition variable and is allocated
  61  *    by silc_cond_alloc and given as argument to all silc_cond_*
  62  *    functions.  It is freed by the silc_cond_free function.
  63  *
  64  ***/
  65 typedef struct SilcCondStruct *SilcCond;
  66
  67 /****s* silcutil/SilcCondAPI/silc_cond_alloc
  68  *
  69  * SYNOPSIS
  70  *
  71  *    SilcBool silc_cond_alloc(SilcCond *cond);
  72  *
  73  * DESCRIPTION
  74  *
  75  *    Allocates SILC Condition variable context.  The condition must
  76  *    be allocated before it can be used.  It is freed by the
  77  *    silc_cond_free function.  This returns TRUE and allocated
  78  *    condition in to the `cond' pointer and FALSE on error.
  79  *
  80  ***/
  81 SilcBool silc_cond_alloc(SilcCond *cond);
  82
  83 /****s* silcutil/SilcCondAPI/silc_cond_free
  84  *
  85  * SYNOPSIS
  86  *
  87  *    void silc_cond_free(SilcCond cond);
  88  *
  89  * DESCRIPTION
  90  *
  91  *    Free condition variable context.  If `cond' is NULL this function
  92  *    has no effect.
  93  *
  94  ***/
  95 void silc_cond_free(SilcCond cond);
  96
  97 /****s* silcutil/SilcCondAPI/silc_cond_wait
  98  *
  99  * SYNOPSIS
 100  *
 101  *    void silc_cond_wait(SilcCond cond, SilcMutex mutex);
 102  *
 103  * DESCRIPTION
 104  *
 105  *    Waits for condition variable `cond' to be signalled.  This function
 106  *    will block the calling thread until the condition variable is
 107  *    signalled.  The `mutex' must be locked before calling this function.
 108  *    The `mutex' will be unlocked inside this function.  After this
 109  *    function returns the `mutex' is in locked state again.
 110  *
 111  * EXAMPLE
 112  *
 113  *    silc_mutex_lock(lock);
 114  *    while (c->a == NULL)
 115  *      silc_cond_wait(cond, lock);
 116  *    ...
 117  *    silc_mutex_unlock(lock);
 118  *
 119  ***/
 120 void silc_cond_wait(SilcCond cond, SilcMutex mutex);
 121
 122 /****s* silcutil/SilcCondAPI/silc_cond_timedwait
 123  *
 124  * SYNOPSIS
 125  *
 126  *    void silc_cond_timedwait(SilcCond cond, SilcMutex mutex, int timeout);
 127  *
 128  * DESCRIPTION
 129  *
 130  *    Waits for condition variable `cond' to be signalled or for the
 131  *    `timeout' to expire.  The timeout is in milliseconds.  If it is 0
 132  *    no timeout exist.  Returns FALSE if timeout expired, TRUE when
 133  *    signalled.  This function will block the calling thread until the
 134  *    condition variable is signalled.  The `mutex' must be locked before
 135  *    calling this function.  The `mutex' will be unlocked inside this
 136  *    function.  After this function returns the `mutex' is in locked
 137  *    state again.
 138  *
 139  ***/
 140 SilcBool silc_cond_timedwait(SilcCond cond, SilcMutex mutex, int timeout);
 141
 142 /****s* silcutil/SilcCondAPI/silc_cond_signal
 143  *
 144  * SYNOPSIS
 145  *
 146  *    void silc_cond_signal(SilcCond cond);
 147  *
 148  * DESCRIPTION
 149  *
 150  *    Signals a waiting thread and wakes it up.  If there are no waiters
 151  *    this function has no effect.  In case of multiple waiters only one
 152  *    is signalled.  To signal all of them use silc_cond_broadcast.
 153  *
 154  * NOTES
 155  *
 156  *    Before calling this function the mutex used with the silc_cond_wait
 157  *    must be acquired.
 158  *
 159  * EXAMPLE
 160  *
 161  *    silc_mutex_lock(lock);
 162  *    c->a = context;
 163  *    silc_cond_signal(cond);
 164  *    silc_mutex_unlock(lock);
 165  *
 166  ***/
 167 void silc_cond_signal(SilcCond cond);
 168
 169 /****s* silcutil/SilcCondAPI/silc_cond_broadcast
 170  *
 171  * SYNOPSIS
 172  *
 173  *    void silc_cond_broadcast(SilcCond cond);
 174  *
 175  * DESCRIPTION
 176  *
 177  *    Signals and wakes up all waiters.  If there are no waiters this
 178  *    function has no effect.
 179  *
 180  * NOTES
 181  *
 182  *    Before calling this function the mutex used with the silc_cond_wait
 183  *    must be acquired.
 184  *
 185  ***/
 186 void silc_cond_broadcast(SilcCond cond);
 187
 188 #endif /* SILCCOND_H */