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 if system is out of
  79  *    memory.
  80  *
  81  ***/
  82 SilcBool silc_cond_alloc(SilcCond *cond);
  83
  84 /****s* silcutil/SilcCondAPI/silc_cond_free
  85  *
  86  * SYNOPSIS
  87  *
  88  *    void silc_cond_free(SilcCond cond);
  89  *
  90  * DESCRIPTION
  91  *
  92  *    Free condition variable context.  If `cond' is NULL this function
  93  *    has no effect.
  94  *
  95  ***/
  96 void silc_cond_free(SilcCond cond);
  97
  98 /****s* silcutil/SilcCondAPI/silc_cond_wait
  99  *
 100  * SYNOPSIS
 101  *
 102  *    void silc_cond_wait(SilcCond cond, SilcMutex mutex);
 103  *
 104  * DESCRIPTION
 105  *
 106  *    Waits for condition variable `cond' to be signalled.  This function
 107  *    will block the calling thread until the condition variable is
 108  *    signalled.  The `mutex' must be locked before calling this function.
 109  *    The `mutex' will be unlocked inside this function.  After this
 110  *    function returns the `mutex' is in locked state again.
 111  *
 112  * EXAMPLE
 113  *
 114  *    silc_mutex_lock(lock);
 115  *    while (c->a == NULL)
 116  *      silc_cond_wait(cond, lock);
 117  *    ...
 118  *    silc_mutex_unlock(lock);
 119  *
 120  ***/
 121 void silc_cond_wait(SilcCond cond, SilcMutex mutex);
 122
 123 /****s* silcutil/SilcCondAPI/silc_cond_timedwait
 124  *
 125  * SYNOPSIS
 126  *
 127  *    void silc_cond_timedwait(SilcCond cond, SilcMutex mutex, int timeout);
 128  *
 129  * DESCRIPTION
 130  *
 131  *    Waits for condition variable `cond' to be signalled or for the
 132  *    `timeout' to expire.  The timeout is in milliseconds.  If it is 0
 133  *    no timeout exist.  Returns FALSE if timeout expired, TRUE when
 134  *    signalled.  This function will block the calling thread until the
 135  *    condition variable is signalled.  The `mutex' must be locked before
 136  *    calling this function.  The `mutex' will be unlocked inside this
 137  *    function.  After this function returns the `mutex' is in locked
 138  *    state again.
 139  *
 140  ***/
 141 SilcBool silc_cond_timedwait(SilcCond cond, SilcMutex mutex, int timeout);
 142
 143 /****s* silcutil/SilcCondAPI/silc_cond_signal
 144  *
 145  * SYNOPSIS
 146  *
 147  *    void silc_cond_signal(SilcCond cond);
 148  *
 149  * DESCRIPTION
 150  *
 151  *    Signals a waiting thread and wakes it up.  If there are no waiters
 152  *    this function has no effect.  In case of multiple waiters only one
 153  *    is signalled.  To signal all of them use silc_cond_broadcast.
 154  *
 155  * NOTES
 156  *
 157  *    Before calling this function the mutex used with the silc_cond_wait
 158  *    must be acquired.
 159  *
 160  * EXAMPLE
 161  *
 162  *    silc_mutex_lock(lock);
 163  *    c->a = context;
 164  *    silc_cond_signal(cond);
 165  *    silc_mutex_unlock(lock);
 166  *
 167  ***/
 168 void silc_cond_signal(SilcCond cond);
 169
 170 /****s* silcutil/SilcCondAPI/silc_cond_broadcast
 171  *
 172  * SYNOPSIS
 173  *
 174  *    void silc_cond_broadcast(SilcCond cond);
 175  *
 176  * DESCRIPTION
 177  *
 178  *    Signals and wakes up all waiters.  If there are no waiters this
 179  *    function has no effect.
 180  *
 181  * NOTES
 182  *
 183  *    Before calling this function the mutex used with the silc_cond_wait
 184  *    must be acquired.
 185  *
 186  ***/
 187 void silc_cond_broadcast(SilcCond cond);
 188
 189 #endif /* SILCCOND_H */