lib/silcutil/silcmutex.h

   1 /*
   2
   3   silcmutex.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 2001 - 2008 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/Mutex Interface
  21  *
  22  * DESCRIPTION
  23  *
  24  * Interface for mutual exclusion locks and read/write locks.  This is
  25  * platform independent interface for applications that need concurrency
  26  * control.
  27  *
  28  ***/
  29
  30 #ifndef SILCMUTEX_H
  31 #define SILCMUTEX_H
  32
  33 /****s* silcutil/SilcMutex
  34  *
  35  * NAME
  36  *
  37  *    typedef struct SilcMutexStruct *SilcMutex;
  38  *
  39  * DESCRIPTION
  40  *
  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.
  44  *
  45  ***/
  46 typedef struct SilcMutexStruct *SilcMutex;
  47
  48 /****s* silcutil/SilcRwLock
  49  *
  50  * NAME
  51  *
  52  *    typedef struct SilcRwLockStruct *SilcRwLock;
  53  *
  54  * DESCRIPTION
  55  *
  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.
  59  *
  60  ***/
  61 typedef struct SilcRwLockStruct *SilcRwLock;
  62
  63 /****f* silcutil/silc_mutex_alloc
  64  *
  65  * SYNOPSIS
  66  *
  67  *    SilcBool silc_mutex_alloc(SilcMutex *mutex);
  68  *
  69  * DESCRIPTION
  70  *
  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.
  76  *
  77  ***/
  78 SilcBool silc_mutex_alloc(SilcMutex *mutex);
  79
  80 /****f* silcutil/silc_mutex_free
  81  *
  82  * SYNOPSIS
  83  *
  84  *    void silc_mutex_free(SilcMutex mutex);
  85  *
  86  * DESCRIPTION
  87  *
  88  *    Free SILC Mutex object and frees all allocated memory.  If `mutex'
  89  *    is NULL this function has no effect.
  90  *
  91  ***/
  92 void silc_mutex_free(SilcMutex mutex);
  93
  94 /****f* silcutil/silc_mutex_lock
  95  *
  96  * SYNOPSIS
  97  *
  98  *    void silc_mutex_lock(SilcMutex mutex);
  99  *
 100  * DESCRIPTION
 101  *
 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
 105  *    has no effect.
 106  *
 107  * NOTES
 108  *
 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
 111  *    occur.
 112  *
 113  ***/
 114 void silc_mutex_lock(SilcMutex mutex);
 115
 116 /****f* silcutil/silc_mutex_unlock
 117  *
 118  * SYNOPSIS
 119  *
 120  *    void silc_mutex_unlock(SilcMutex mutex);
 121  *
 122  * DESCRIPTION
 123  *
 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
 126  *    has no effect.
 127  *
 128  * NOTES
 129  *
 130  *    The caller must not call the silc_mutex_unlock for an unlocked
 131  *    mutex or mutex not locked by the current thread.
 132  *
 133  ***/
 134 void silc_mutex_unlock(SilcMutex mutex);
 135
 136 /****f* silcutil/silc_mutex_trylock
 137  *
 138  * SYNOPSIS
 139  *
 140  *    SilcBool silc_mutex_trylock(SilcMutex mutex);
 141  *
 142  * DESCRIPTION
 143  *
 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
 147  *    time.
 148  *
 149  ***/
 150 SilcBool silc_mutex_trylock(SilcMutex mutex);
 151
 152 /****f* silcutil/silc_mutex_assert_locked
 153  *
 154  * SYNOPSIS
 155  *
 156  *    void silc_mutex_assert_locked(SilcMutex mutex);
 157  *
 158  * DESCRIPTION
 159  *
 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).
 163  *
 164  ***/
 165 void silc_mutex_assert_locked(SilcMutex mutex);
 166
 167 /****f* silcutil/silc_rwlock_alloc
 168  *
 169  * SYNOPSIS
 170  *
 171  *    SilcBool silc_rwlock_alloc(SilcRwLock *rwlock);
 172  *
 173  * DESCRIPTION
 174  *
 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
 178  *    FALSE on error.
 179  *
 180  ***/
 181 SilcBool silc_rwlock_alloc(SilcRwLock *rwlock);
 182
 183 /****f* silcutil/silc_rwlock_free
 184  *
 185  * SYNOPSIS
 186  *
 187  *    void silc_rwlock_free(SilcRwLock rwlock);
 188  *
 189  * DESCRIPTION
 190  *
 191  *    Free SILC Rwlock object and frees all allocated memory.  If `rwlock'
 192  *    is NULL this function has no effect.
 193  *
 194  ***/
 195 void silc_rwlock_free(SilcRwLock rwlock);
 196
 197 /****f* silcutil/silc_rwlock_rdlock
 198  *
 199  * SYNOPSIS
 200  *
 201  *    void silc_rwlock_rdlock(SilcRwLock rwlock);
 202  *
 203  * DESCRIPTION
 204  *
 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.
 211  *
 212  ***/
 213 void silc_rwlock_rdlock(SilcRwLock rwlock);
 214
 215 /****f* silcutil/silc_rwlock_wrlock
 216  *
 217  * SYNOPSIS
 218  *
 219  *    void silc_rwlock_wrlock(SilcRwLock rwlock);
 220  *
 221  * DESCRIPTION
 222  *
 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.
 229  *
 230  ***/
 231 void silc_rwlock_wrlock(SilcRwLock rwlock);
 232
 233 /****f* silcutil/silc_rwlock_unlock
 234  *
 235  * SYNOPSIS
 236  *
 237  *    void silc_rwlock_unlock(SilcRwLock rwlock);
 238  *
 239  * DESCRIPTION
 240  *
 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
 244  *    effect.
 245  *
 246  ***/
 247 void silc_rwlock_unlock(SilcRwLock rwlock);
 248
 249 #endif