1 /* 2 3 silccond.h 4 5 Author: Pekka Riikonen <priikone@silcnet.org> 6 7 Copyright (C) 2006 - 2007 Pekka Riikonen 8 9 The contents of this file are subject to one of the Licenses specified 10 in the COPYING file; You may not use this file except in compliance 11 with the License. 12 13 The software distributed under the License is distributed on an "AS IS" 14 basis, in the hope that it will be useful, but WITHOUT WARRANTY OF ANY 15 KIND, either expressed or implied. See the COPYING file for more 16 information. 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 ***/ 29 30 #ifndef SILCCOND_H 31 #define SILCCOND_H 32 33 /****s* silcutil/SilcCondAPI/SilcCond 34 * 35 * NAME 36 * 37 * typedef struct SilcCondStruct *SilcCond; 38 * 39 * DESCRIPTION 40 * 41 * This context is the actual condition variable and is allocated 42 * by silc_cond_alloc and given as argument to all silc_cond_* 43 * functions. It is freed by the silc_cond_free function. 44 * 45 ***/ 46 typedef struct SilcCondStruct *SilcCond; 47 48 /****s* silcutil/SilcCondAPI/silc_cond_alloc 49 * 50 * SYNOPSIS 51 * 52 * SilcBool silc_cond_alloc(SilcCond *cond); 53 * 54 * DESCRIPTION 55 * 56 * Allocates SILC Condition variable context. The condition must 57 * be allocated before it can be used. It is freed by the 58 * silc_cond_free function. This returns TRUE and allocated 59 * condition in to the `cond' pointer and FALSE on error. 60 * 61 ***/ 62 SilcBool silc_cond_alloc(SilcCond *cond); 63 64 /****s* silcutil/SilcCondAPI/silc_cond_free 65 * 66 * SYNOPSIS 67 * 68 * void silc_cond_free(SilcCond cond); 69 * 70 * DESCRIPTION 71 * 72 * Free condition variable context. If `cond' is NULL this function 73 * has no effect. 74 * 75 ***/ 76 void silc_cond_free(SilcCond cond); 77 78 /****s* silcutil/SilcCondAPI/silc_cond_wait 79 * 80 * SYNOPSIS 81 * 82 * void silc_cond_wait(SilcCond cond, SilcMutex mutex); 83 * 84 * DESCRIPTION 85 * 86 * Waits for condition variable `cond' to be signalled. This function 87 * will block the calling thread until the condition 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_cond_wait(cond, lock); 97 * ... 98 * silc_mutex_unlock(lock); 99 * 100 ***/ 101 void silc_cond_wait(SilcCond cond, SilcMutex mutex); 102 103 /****s* silcutil/SilcCondAPI/silc_cond_timedwait 104 * 105 * SYNOPSIS 106 * 107 * void silc_cond_timedwait(SilcCond cond, SilcMutex mutex, int timeout); 108 * 109 * DESCRIPTION 110 * 111 * Waits for condition variable `cond' to be signalled or for the 112 * `timeout' to expire. The timeout is in milliseconds. If it is 0 113 * no timeout exist. Returns FALSE if timeout expired, TRUE when 114 * signalled. This function will block the calling thread until the 115 * condition variable is signalled. The `mutex' must be locked before 116 * calling this function. The `mutex' will be unlocked inside this 117 * function. After this function returns the `mutex' is in locked 118 * state again. 119 * 120 ***/ 121 SilcBool silc_cond_timedwait(SilcCond cond, SilcMutex mutex, int timeout); 122 123 /****s* silcutil/SilcCondAPI/silc_cond_signal 124 * 125 * SYNOPSIS 126 * 127 * void silc_cond_signal(SilcCond cond); 128 * 129 * DESCRIPTION 130 * 131 * Signals a waiting thread and wakes it up. If there are no waiters 132 * this function has no effect. In case of multiple waiters only one 133 * is signalled. To signal all of them use silc_cond_broadcast. 134 * 135 * NOTES 136 * 137 * Before calling this function the mutex used with the silc_cond_wait 138 * must be acquired. 139 * 140 * EXAMPLE 141 * 142 * silc_mutex_lock(lock); 143 * c->a = context; 144 * silc_cond_signal(cond); 145 * silc_mutex_unlock(lock); 146 * 147 ***/ 148 void silc_cond_signal(SilcCond cond); 149 150 /****s* silcutil/SilcCondAPI/silc_cond_broadcast 151 * 152 * SYNOPSIS 153 * 154 * void silc_cond_broadcast(SilcCond cond); 155 * 156 * DESCRIPTION 157 * 158 * Signals and wakes up all waiters. If there are no waiters this 159 * function has no effect. 160 * 161 * NOTES 162 * 163 * Before calling this function the mutex used with the silc_cond_wait 164 * must be acquired. 165 * 166 ***/ 167 void silc_cond_broadcast(SilcCond cond); 168 169 #endif /* SILCCOND_H */ 170