lib/silcutil/silcmutex.h

   1 /*
   2
   3   silcmutex.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 2001 - 2005 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/SILC Mutex Interface
  21  *
  22  * DESCRIPTION
  23  *
  24  * Interface for the SILC Mutex locking implementation. This is platform
  25  * independent mutual exclusion interface for applications that need
  26  * concurrency control.
  27  *
  28  ***/
  29
  30 #ifndef SILCMUTEX_H
  31 #define SILCMUTEX_H
  32
  33 /****s* silcutil/SilcMutexAPI/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 /****d* silcutil/SilcMutexAPI/SILC_MUTEX_DEFINE
  49  *
  50  * NAME
  51  *
  52  *    #define SILC_MUTEX_DEFINE(name) ...
  53  *
  54  * DESCRIPTION
  55  *
  56  *    This macro is used to define new mutex.  Use this macro in an
  57  *    environment that can be compiled with or without the SILC Mutex
  58  *    API. This is equivalent to defining SilcMutex `name'; directly.
  59  *
  60  * SOURCE
  61  */
  62 #define SILC_MUTEX_DEFINE(name) SilcMutex name
  63 /***/
  64
  65 /****f* silcutil/SilcMutexAPI/silc_mutex_alloc
  66  *
  67  * SYNOPSIS
  68  *
  69  *    bool silc_mutex_alloc(SilcMutex *mutex);
  70  *
  71  * DESCRIPTION
  72  *
  73  *    Allocates SILC Mutex object.  The mutex object must be allocated
  74  *    before it can be used.  It is freed by the silc_mutex_free function.
  75  *    This returns TRUE and allocated mutex in to the `mutex' and FALSE
  76  *    on error.
  77  *
  78  ***/
  79 bool silc_mutex_alloc(SilcMutex *mutex);
  80
  81 /****f* silcutil/SilcMutexAPI/silc_mutex_free
  82  *
  83  * SYNOPSIS
  84  *
  85  *    void silc_mutex_free(SilcMutex mutex);
  86  *
  87  * DESCRIPTION
  88  *
  89  *    Free SILC Mutex object and frees all allocated memory.  If `mutex'
  90  *    is NULL this function has no effect.
  91  *
  92  ***/
  93 void silc_mutex_free(SilcMutex mutex);
  94
  95 /****f* silcutil/SilcMutexAPI/silc_mutex_lock
  96  *
  97  * SYNOPSIS
  98  *
  99  *    void silc_mutex_lock(SilcMutex mutex);
 100  *
 101  * DESCRIPTION
 102  *
 103  *    Locks the mutex. If the mutex is locked by another thread the
 104  *    current thread will block until the other thread has issued
 105  *    silc_mutex_unlock for the mutex.  If `mutex' is NULL this function
 106  *    has no effect.
 107  *
 108  * NOTES
 109  *
 110  *    The caller must not call silc_mutex_lock for mutex that has been
 111  *    already locked in the current thread.  In this case deadlock will
 112  *    occur.
 113  *
 114  ***/
 115 void silc_mutex_lock(SilcMutex mutex);
 116
 117 /****f* silcutil/SilcMutexAPI/silc_mutex_unlock
 118  *
 119  * SYNOPSIS
 120  *
 121  *    void silc_mutex_unlock(SilcMutex mutex);
 122  *
 123  * DESCRIPTION
 124  *
 125  *    Unlocks the mutex and thus releases it for another thread that
 126  *    may be waiting for the lock.  If `mutex' is NULL this function
 127  *    has no effect.
 128  *
 129  * NOTES
 130  *
 131  *    The caller must not call the silc_mutex_unlock for an unlocked
 132  *    mutex or mutex not locked by the current thread.  It is fatal
 133  *    error if this occurs.
 134  *
 135  ***/
 136 void silc_mutex_unlock(SilcMutex mutex);
 137
 138 #endif