lib/silcutil/silccondvar.h

   1 /*
   2
   3   silccondvar.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 2006 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 Conditional Variable Interface
  21  *
  22  * DESCRIPTION
  23  *
  24  * A conditional variable interface for multi-thread synchronization.
  25  * Conditional variables enable threads to suspend execution and yield
  26  * the processors until some predicate on some shared data is satisfied.
  27  *
  28  ***/
  29
  30 #ifndef SILCCONDVAR_H
  31 #define SILCCONDVAR_H
  32
  33 /****s* silcutil/SilcCondVarAPI/SilcCondVar
  34  *
  35  * NAME
  36  *
  37  *    typedef struct SilcCondVarStruct *SilcCondVar;
  38  *
  39  * DESCRIPTION
  40  *
  41  *    This context is the actual conditional variable and is allocated
  42  *    by silc_condvar_alloc and given as argument to all silc_condvar_*
  43  *    functions.  It is freed by the silc_condvar_free function.
  44  *
  45  ***/
  46 typedef struct SilcCondVarStruct *SilcCondVar;
  47
  48 /****s* silcutil/SilcCondVarAPI/silc_condvar_alloc
  49  *
  50  * SYNOPSIS
  51  *
  52  *    SilcBool silc_condvar_alloc(SilcCondVar *cond);
  53  *
  54  * DESCRIPTION
  55  *
  56  *    Allocates SILC Conditional variable context.  The conditional must
  57  *    be allocated before it can be used.  It is freed by the
  58  *    silc_condvar_free function.  This returns TRUE and allocated
  59  *    conditional in to the `cond' pointer and FALSE on error.
  60  *
  61  ***/
  62 SilcBool silc_condvar_alloc(SilcCondVar *cond);
  63
  64 /****s* silcutil/SilcCondVarAPI/silc_condvar_free
  65  *
  66  * SYNOPSIS
  67  *
  68  *    void silc_condvar_free(SilcCondVar cond);
  69  *
  70  * DESCRIPTION
  71  *
  72  *    Free conditional variable context.  If `cond' is NULL this function
  73  *    has no effect.
  74  *
  75  ***/
  76 void silc_condvar_free(SilcCondVar cond);
  77
  78 /****s* silcutil/SilcCondVarAPI/silc_condvar_wait
  79  *
  80  * SYNOPSIS
  81  *
  82  *    void silc_condvar_wait(SilcCondVar cond, SilcMutex mutex);
  83  *
  84  * DESCRIPTION
  85  *
  86  *    Waits for conditional variable `cond' to be signalled.  This function
  87  *    will block the calling thread until the conditional variable is
  88  *    signalled.  The `mutex' must be locked before calling this function.
  89  *    The `mutex' will be unlocked inside this function.  After this
  90  *    function returns the `mutex' is in locked state again.
  91  *
  92  * EXAMPLE
  93  *
  94  *    silc_mutex_lock(lock);
  95  *    while (c->a == NULL)
  96  *      silc_condvar_wait(cond, lock);
  97  *    ...
  98  *    silc_mutex_unlock(lock);
  99  *
 100  ***/
 101 void silc_condvar_wait(SilcCondVar cond, SilcMutex mutex);
 102
 103 /****s* silcutil/SilcCondVarAPI/silc_condvar_timedwait
 104  *
 105  * SYNOPSIS
 106  *
 107  *    void silc_condvar_timedwait(SilcCondVar cond, SilcMutex mutex,
 108  *                                struct timespec *timeout);
 109  *
 110  * DESCRIPTION
 111  *
 112  *    Waits for conditional variable `cond' to be signalled or for the
 113  *    `timeout' to expire.  The timeout is in milliseconds.  If it is 0
 114  *    no timeout exist.  Returns FALSE if timeout expired, TRUE when
 115  *    signalled.  This function will block the calling thread until the
 116  *    conditional variable is signalled.  The `mutex' must be locked before
 117  *    calling this function.  The `mutex' will be unlocked inside this
 118  *    function.  After this function returns the `mutex' is in locked
 119  *    state again.
 120  *
 121  ***/
 122 SilcBool silc_condvar_timedwait(SilcCondVar cond, SilcMutex mutex,
 123                                 int timeout);
 124
 125 /****s* silcutil/SilcCondVarAPI/silc_condvar_signal
 126  *
 127  * SYNOPSIS
 128  *
 129  *    void silc_condvar_signal(SilcCondVar cond);
 130  *
 131  * DESCRIPTION
 132  *
 133  *    Signals a waiting thread and wakes it up.  If there are no waiters
 134  *    this function has no effect.  In case of multiple waiters only one
 135  *    is signalled.  To signal all of them use silc_condvar_broadcast.
 136  *
 137  * NOTES
 138  *
 139  *    Before calling this function the mutex used with the silc_condvar_wait
 140  *    must be acquired.
 141  *
 142  * EXAMPLE
 143  *
 144  *    silc_mutex_lock(lock);
 145  *    c->a = context;
 146  *    silc_condvar_signal(cond);
 147  *    silc_mutex_unlock(lock);
 148  *
 149  ***/
 150 void silc_condvar_signal(SilcCondVar cond);
 151
 152 /****s* silcutil/SilcCondVarAPI/silc_condvar_broadcast
 153  *
 154  * SYNOPSIS
 155  *
 156  *    void silc_condvar_broadcast(SilcCondVar cond);
 157  *
 158  * DESCRIPTION
 159  *
 160  *    Signals and wakes up all waiters.  If there are no waiters this
 161  *    function has no effect.
 162  *
 163  * NOTES
 164  *
 165  *    Before calling this function the mutex used with the silc_condvar_wait
 166  *    must be acquired.
 167  *
 168  ***/
 169 void silc_condvar_broadcast(SilcCondVar cond);
 170
 171 #endif /* SILCCONDVAR_H */