5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 2001 - 2008 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/Mutex Interface
24 * Interface for mutual exclusion locks and read/write locks. This is
25 * platform independent interface for applications that need concurrency
33 /****s* silcutil/SilcMutex
37 * typedef struct SilcMutexStruct *SilcMutex;
41 * This context is the actual SILC Mutex and is allocated
42 * by silc_mutex_alloc and given as argument to all silc_mutex_*
43 * functions. It is freed by the silc_mutex_free function.
46 typedef struct SilcMutexStruct *SilcMutex;
48 /****s* silcutil/SilcRwLock
52 * typedef struct SilcRwLockStruct *SilcRwLock;
56 * This context is the actual SILC read/write lock and is allocated
57 * by silc_rwlock_alloc and given as argument to all silc_rwlock_*
58 * functions. It is freed by the silc_rwlock_free function.
61 typedef struct SilcRwLockStruct *SilcRwLock;
63 /****f* silcutil/silc_mutex_alloc
67 * SilcBool silc_mutex_alloc(SilcMutex *mutex);
71 * Allocates SILC Mutex object. The mutex object must be allocated
72 * before it can be used. It is freed by the silc_mutex_free function.
73 * This returns TRUE and allocated mutex in to the `mutex' and FALSE
74 * on error. If threads support is not compiled in this returns FALSE,
75 * but should not be considered as an error.
78 SilcBool silc_mutex_alloc(SilcMutex *mutex);
80 /****f* silcutil/silc_mutex_free
84 * void silc_mutex_free(SilcMutex mutex);
88 * Free SILC Mutex object and frees all allocated memory. If `mutex'
89 * is NULL this function has no effect.
92 void silc_mutex_free(SilcMutex mutex);
94 /****f* silcutil/silc_mutex_lock
98 * void silc_mutex_lock(SilcMutex mutex);
102 * Locks the mutex. If the mutex is locked by another thread the
103 * current thread will block until the other thread has issued
104 * silc_mutex_unlock for the mutex. If `mutex' is NULL this function
109 * The caller must not call silc_mutex_lock for mutex that has been
110 * already locked in the current thread. In this case deadlock will
114 void silc_mutex_lock(SilcMutex mutex);
116 /****f* silcutil/silc_mutex_unlock
120 * void silc_mutex_unlock(SilcMutex mutex);
124 * Unlocks the mutex and thus releases it for another thread that
125 * may be waiting for the lock. If `mutex' is NULL this function
130 * The caller must not call the silc_mutex_unlock for an unlocked
131 * mutex or mutex not locked by the current thread.
134 void silc_mutex_unlock(SilcMutex mutex);
136 /****f* silcutil/silc_mutex_trylock
140 * SilcBool silc_mutex_trylock(SilcMutex mutex);
144 * Attempts to lock the `mutex'. Returns TRUE if the caller was able
145 * to acquire the lock and FALSE if the mutex is already locked. If the
146 * mutex is already locked the caller cannot acquire the lock at this
150 SilcBool silc_mutex_trylock(SilcMutex mutex);
152 /****f* silcutil/silc_mutex_assert_locked
156 * void silc_mutex_assert_locked(SilcMutex mutex);
160 * Asserts that the `mutex' is locked. It is fatal error if the mutex
161 * is not locked. If debugging is not compiled in this function has
162 * no effect (SILC_DEBUG define).
165 void silc_mutex_assert_locked(SilcMutex mutex);
167 /****f* silcutil/silc_rwlock_alloc
171 * SilcBool silc_rwlock_alloc(SilcRwLock *rwlock);
175 * Allocates SILC read/write lock. The read/write lock must be allocated
176 * before it can be used. It is freed by the silc_rwlock_free function.
177 * This returns TRUE and allocated read/write lock in to the `rwlock' and
181 SilcBool silc_rwlock_alloc(SilcRwLock *rwlock);
183 /****f* silcutil/silc_rwlock_free
187 * void silc_rwlock_free(SilcRwLock rwlock);
191 * Free SILC Rwlock object and frees all allocated memory. If `rwlock'
192 * is NULL this function has no effect.
195 void silc_rwlock_free(SilcRwLock rwlock);
197 /****f* silcutil/silc_rwlock_rdlock
201 * void silc_rwlock_rdlock(SilcRwLock rwlock);
205 * Acquires read lock of the read/write lock `rwlock'. If the `rwlock'
206 * is locked by a writer the current thread will block until the other
207 * thread has issued silc_rwlock_unlock for the `rwlock'. This function
208 * may be called multiple times to acquire the read lock. There must be
209 * same number of silc_rwlock_unlock calls. If `rwlock' is NULL this
210 * function has no effect.
213 void silc_rwlock_rdlock(SilcRwLock rwlock);
215 /****f* silcutil/silc_rwlock_wrlock
219 * void silc_rwlock_wrlock(SilcRwLock rwlock);
223 * Acquires write lock of the read/write lock `rwlock'. If the `rwlock'
224 * is locked by a writer or a reader the current thread will block until
225 * the other thread(s) have issued silc_rwlock_unlock for the `rwlock'.
226 * A thread may acquire the write lock only once. A deadlock may occur
227 * if thread attempts to acquire the write lock when it has already done
228 * so. If `rwlock' is NULL this function has no effect.
231 void silc_rwlock_wrlock(SilcRwLock rwlock);
233 /****f* silcutil/silc_rwlock_unlock
237 * void silc_rwlock_unlock(SilcRwLock rwlock);
241 * Releases the lock of the read/write lock `rwlock'. If `rwlock' was
242 * locked by a writer this will release the writer lock. Otherwise this
243 * releases the reader lock. If `rwlock' is NULL this function has no
247 void silc_rwlock_unlock(SilcRwLock rwlock);