lib/silcutil/silcmutex.h

   1 /****h* silcutil/silcmutex.h
   2  *
   3  * NAME
   4  *
   5  * silcmutex.h
   6  *
   7  * COPYRIGHT
   8  *
   9  * Author: Pekka Riikonen <priikone@silcnet.org>
  10  *
  11  * Copyright (C) 2001 Pekka Riikonen
  12  *
  13  * This program is free software; you can redistribute it and/or modify
  14  * it under the terms of the GNU General Public License as published by
  15  * the Free Software Foundation; either version 2 of the License, or
  16  * (at your option) any later version.
  17  *
  18  * This program is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU General Public License for more details.
  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 /* Prototypes */
  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 /****f* silcutil/SilcMutexAPI/silc_mutex_alloc
  52  *
  53  * SYNOPSIS
  54  *
  55  *    SilcMutex silc_mutex_alloc(void);
  56  *
  57  * DESCRIPTION
  58  *
  59  *    Allocates SILC Mutex object.  The mutex object must be allocated
  60  *    before it can be used.  It is freed by the silc_mutex_free function.
  61  *
  62  ***/
  63 SilcMutex silc_mutex_alloc(void);
  64
  65 /****f* silcutil/SilcMutexAPI/silc_mutex_free
  66  *
  67  * SYNOPSIS
  68  *
  69  *    void silc_mutex_free(SilcMutex mutex);
  70  *
  71  * DESCRIPTION
  72  *
  73  *    Free SILC Mutex object and frees all allocated memory.
  74  *
  75  ***/
  76 void silc_mutex_free(SilcMutex mutex);
  77
  78 /****f* silcutil/SilcMutexAPI/silc_mutex_lock
  79  *
  80  * SYNOPSIS
  81  *
  82  *    void silc_mutex_lock(SilcMutex mutex);
  83  *
  84  * DESCRIPTION
  85  *
  86  *    Locks the mutex. If the mutex is locked by another thread the
  87  *    current thread will block until the other thread has issued
  88  *    silc_mutex_unlock for the mutex.
  89  *
  90  * NOTES
  91  *
  92  *    The caller must not call silc_mutex_lock for mutex that has been
  93  *    already locked in the current thread.  In this case deadlock will
  94  *    occur.
  95  *
  96  ***/
  97 void silc_mutex_lock(SilcMutex mutex);
  98
  99 /****f* silcutil/SilcMutexAPI/silc_mutex_unlock
 100  *
 101  * SYNOPSIS
 102  *
 103  *    void silc_mutex_unlock(SilcMutex mutex);
 104  *
 105  * DESCRIPTION
 106  *
 107  *    Unlocks the mutex and thus releases it for another threads that
 108  *    may be waiting for the lock.
 109  *
 110  * NOTES
 111  *
 112  *    The caller must not call the silc_mutex_unlock for an unlocked
 113  *    mutex or mutex not locked by the current thread.  It is fatal
 114  *    error if this occurs.
 115  *
 116  ***/
 117 void silc_mutex_unlock(SilcMutex mutex);
 118
 119 #endif