5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 2006 - 2007 Pekka Riikonen
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.
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.
20 /****h* silcutil/SILC Condition Variable Interface
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.
33 * silc_mutex_lock(lock);
34 * while (c->a == NULL)
35 * silc_cond_wait(cond, lock);
37 * silc_mutex_unlock(lock);
42 * silc_mutex_lock(lock);
44 * silc_cond_signal(cond);
45 * silc_mutex_unlock(lock);
52 /****s* silcutil/SilcCondAPI/SilcCond
56 * typedef struct SilcCondStruct *SilcCond;
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.
65 typedef struct SilcCondStruct *SilcCond;
67 /****s* silcutil/SilcCondAPI/silc_cond_alloc
71 * SilcBool silc_cond_alloc(SilcCond *cond);
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
82 SilcBool silc_cond_alloc(SilcCond *cond);
84 /****s* silcutil/SilcCondAPI/silc_cond_free
88 * void silc_cond_free(SilcCond cond);
92 * Free condition variable context. If `cond' is NULL this function
96 void silc_cond_free(SilcCond cond);
98 /****s* silcutil/SilcCondAPI/silc_cond_wait
102 * void silc_cond_wait(SilcCond cond, SilcMutex mutex);
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.
114 * silc_mutex_lock(lock);
115 * while (c->a == NULL)
116 * silc_cond_wait(cond, lock);
118 * silc_mutex_unlock(lock);
121 void silc_cond_wait(SilcCond cond, SilcMutex mutex);
123 /****s* silcutil/SilcCondAPI/silc_cond_timedwait
127 * void silc_cond_timedwait(SilcCond cond, SilcMutex mutex, int timeout);
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
141 SilcBool silc_cond_timedwait(SilcCond cond, SilcMutex mutex, int timeout);
143 /****s* silcutil/SilcCondAPI/silc_cond_signal
147 * void silc_cond_signal(SilcCond cond);
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.
157 * Before calling this function the mutex used with the silc_cond_wait
162 * silc_mutex_lock(lock);
164 * silc_cond_signal(cond);
165 * silc_mutex_unlock(lock);
168 void silc_cond_signal(SilcCond cond);
170 /****s* silcutil/SilcCondAPI/silc_cond_broadcast
174 * void silc_cond_broadcast(SilcCond cond);
178 * Signals and wakes up all waiters. If there are no waiters this
179 * function has no effect.
183 * Before calling this function the mutex used with the silc_cond_wait
187 void silc_cond_broadcast(SilcCond cond);
189 #endif /* SILCCOND_H */