lib/silcutil/silcmutex.h

   1 /*
   2
   3   silcmutex.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 2001 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; either version 2 of the License, or
  12   (at your option) any later version.
  13
  14   This program is distributed in the hope that it will be useful,
  15   but WITHOUT ANY WARRANTY; without even the implied warranty of
  16   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17   GNU General Public License for more details.
  18
  19 */
  20
  21 /****h* silcutil/SILC Mutex Interface
  22  *
  23  * DESCRIPTION
  24  *
  25  * Interface for the SILC Mutex locking implementation. This is platform
  26  * independent mutual exclusion interface for applications that need
  27  * concurrency control.
  28  *
  29  ***/
  30
  31 #ifndef SILCMUTEX_H
  32 #define SILCMUTEX_H
  33
  34 #if defined(SILC_THREADS)
  35
  36 /****s* silcutil/SilcMutexAPI/SilcMutex
  37  *
  38  * NAME
  39  *
  40  *    typedef struct SilcMutexStruct *SilcMutex;
  41  *
  42  * DESCRIPTION
  43  *
  44  *    This context is the actual SILC Mutex and is allocated
  45  *    by silc_mutex_alloc and given as argument to all silc_mutex_*
  46  *    functions.  It is freed by the silc_mutex_free function.
  47  *
  48  ***/
  49 typedef struct SilcMutexStruct *SilcMutex;
  50
  51 /****d* silcutil/SilcMutexAPI/SILC_MUTEX_DEFINE
  52  *
  53  * NAME
  54  *
  55  *    #define SILC_MUTEX_DEFINE(name) ...
  56  *
  57  * DESCRIPTION
  58  *
  59  *    This macro is used to define new mutex.  Use this macro in an
  60  *    environment that can be compiled with or without the SILC Mutex
  61  *    API. This is equivalent to defining SilcMutex `name'; directly.
  62  *
  63  * SOURCE
  64  */
  65 #define SILC_MUTEX_DEFINE(name) SilcMutex name
  66 /***/
  67
  68 /****f* silcutil/SilcMutexAPI/silc_mutex_alloc
  69  *
  70  * SYNOPSIS
  71  *
  72  *    bool silc_mutex_alloc(SilcMutex *mutex);
  73  *
  74  * DESCRIPTION
  75  *
  76  *    Allocates SILC Mutex object.  The mutex object must be allocated
  77  *    before it can be used.  It is freed by the silc_mutex_free function.
  78  *    This returns TRUE and allocated mutex in to the `mutex' and FALSE
  79  *    on error.
  80  *
  81  ***/
  82 bool silc_mutex_alloc(SilcMutex *mutex);
  83
  84 /****f* silcutil/SilcMutexAPI/silc_mutex_free
  85  *
  86  * SYNOPSIS
  87  *
  88  *    void silc_mutex_free(SilcMutex mutex);
  89  *
  90  * DESCRIPTION
  91  *
  92  *    Free SILC Mutex object and frees all allocated memory.
  93  *
  94  ***/
  95 void silc_mutex_free(SilcMutex mutex);
  96
  97 /****f* silcutil/SilcMutexAPI/silc_mutex_lock
  98  *
  99  * SYNOPSIS
 100  *
 101  *    void silc_mutex_lock(SilcMutex mutex);
 102  *
 103  * DESCRIPTION
 104  *
 105  *    Locks the mutex. If the mutex is locked by another thread the
 106  *    current thread will block until the other thread has issued
 107  *    silc_mutex_unlock for the mutex.
 108  *
 109  * NOTES
 110  *
 111  *    The caller must not call silc_mutex_lock for mutex that has been
 112  *    already locked in the current thread.  In this case deadlock will
 113  *    occur.
 114  *
 115  ***/
 116 void silc_mutex_lock(SilcMutex mutex);
 117
 118 /****f* silcutil/SilcMutexAPI/silc_mutex_unlock
 119  *
 120  * SYNOPSIS
 121  *
 122  *    void silc_mutex_unlock(SilcMutex mutex);
 123  *
 124  * DESCRIPTION
 125  *
 126  *    Unlocks the mutex and thus releases it for another thread that
 127  *    may be waiting for the lock.
 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 #else
 139
 140 #define SILC_MUTEX_DEFINE(name)
 141 #define silc_mutex_alloc(mutex) (void)0
 142 #define silc_mutex_free(mutex) (void)0
 143 #define silc_mutex_lock(mutex) (void)0
 144 #define silc_mutex_unlock(mutex) (void)0
 145
 146 #endif         /* SILC_THREADS */
 147
 148 #endif