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 on error.
81 SilcBool silc_cond_alloc(SilcCond *cond);
83 /****s* silcutil/SilcCondAPI/silc_cond_free
87 * void silc_cond_free(SilcCond cond);
91 * Free condition variable context. If `cond' is NULL this function
95 void silc_cond_free(SilcCond cond);
97 /****s* silcutil/SilcCondAPI/silc_cond_wait
101 * void silc_cond_wait(SilcCond cond, SilcMutex mutex);
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.
113 * silc_mutex_lock(lock);
114 * while (c->a == NULL)
115 * silc_cond_wait(cond, lock);
117 * silc_mutex_unlock(lock);
120 void silc_cond_wait(SilcCond cond, SilcMutex mutex);
122 /****s* silcutil/SilcCondAPI/silc_cond_timedwait
126 * void silc_cond_timedwait(SilcCond cond, SilcMutex mutex, int timeout);
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
140 SilcBool silc_cond_timedwait(SilcCond cond, SilcMutex mutex, int timeout);
142 /****s* silcutil/SilcCondAPI/silc_cond_signal
146 * void silc_cond_signal(SilcCond cond);
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.
156 * Before calling this function the mutex used with the silc_cond_wait
161 * silc_mutex_lock(lock);
163 * silc_cond_signal(cond);
164 * silc_mutex_unlock(lock);
167 void silc_cond_signal(SilcCond cond);
169 /****s* silcutil/SilcCondAPI/silc_cond_broadcast
173 * void silc_cond_broadcast(SilcCond cond);
177 * Signals and wakes up all waiters. If there are no waiters this
178 * function has no effect.
182 * Before calling this function the mutex used with the silc_cond_wait
186 void silc_cond_broadcast(SilcCond cond);
188 #endif /* SILCCOND_H */