SILC Runtime Toolkit 1.2 Beta 1

[runtime.git] / lib / silcutil / silcmutex.h

diff --git a/lib/silcutil/silcmutex.h b/lib/silcutil/silcmutex.h
index 82a9da3922130fb76549f8424ed67fefc52896ed..878d37deb8fdf4f9365aa7f67f9ce25140028cdf 100644 (file)
--- a/lib/silcutil/silcmutex.h
+++ b/lib/silcutil/silcmutex.h
@@ -4,7 +4,7 @@
 
   Author: Pekka Riikonen <priikone@silcnet.org>
 
-  Copyright (C) 2001 - 2007 Pekka Riikonen
+  Copyright (C) 2001 - 2008 Pekka Riikonen
 
   This program is free software; you can redistribute it and/or modify
   it under the terms of the GNU General Public License as published by
@@ -17,7 +17,7 @@
 
 */
 
-/****h* silcutil/SILC Mutex Interface
+/****h* silcutil/Mutex Interface
  *
  * DESCRIPTION
  *
@@ -30,7 +30,7 @@
 #ifndef SILCMUTEX_H
 #define SILCMUTEX_H
 
-/****s* silcutil/SilcMutexAPI/SilcMutex
+/****s* silcutil/SilcMutex
  *
  * NAME
  *
@@ -45,7 +45,7 @@
  ***/
 typedef struct SilcMutexStruct *SilcMutex;
 
-/****s* silcutil/SilcMutexAPI/SilcRwLock
+/****s* silcutil/SilcRwLock
  *
  * NAME
  *
@@ -60,7 +60,7 @@ typedef struct SilcMutexStruct *SilcMutex;
  ***/
 typedef struct SilcRwLockStruct *SilcRwLock;
 
-/****f* silcutil/SilcMutexAPI/silc_mutex_alloc
+/****f* silcutil/silc_mutex_alloc
  *
  * SYNOPSIS
  *
@@ -71,12 +71,13 @@ typedef struct SilcRwLockStruct *SilcRwLock;
  *    Allocates SILC Mutex object.  The mutex object must be allocated
  *    before it can be used.  It is freed by the silc_mutex_free function.
  *    This returns TRUE and allocated mutex in to the `mutex' and FALSE
- *    on error.
+ *    on error.  If threads support is not compiled in this returns FALSE,
+ *    but should not be considered as an error.
  *
  ***/
 SilcBool silc_mutex_alloc(SilcMutex *mutex);
 
-/****f* silcutil/SilcMutexAPI/silc_mutex_free
+/****f* silcutil/silc_mutex_free
  *
  * SYNOPSIS
  *
@@ -90,7 +91,7 @@ SilcBool silc_mutex_alloc(SilcMutex *mutex);
  ***/
 void silc_mutex_free(SilcMutex mutex);
 
-/****f* silcutil/SilcMutexAPI/silc_mutex_lock
+/****f* silcutil/silc_mutex_lock
  *
  * SYNOPSIS
  *
@@ -112,7 +113,7 @@ void silc_mutex_free(SilcMutex mutex);
  ***/
 void silc_mutex_lock(SilcMutex mutex);
 
-/****f* silcutil/SilcMutexAPI/silc_mutex_unlock
+/****f* silcutil/silc_mutex_unlock
  *
  * SYNOPSIS
  *
@@ -132,7 +133,7 @@ void silc_mutex_lock(SilcMutex mutex);
  ***/
 void silc_mutex_unlock(SilcMutex mutex);
 
-/****f* silcutil/SilcMutexAPI/silc_mutex_assert_locked
+/****f* silcutil/silc_mutex_assert_locked
  *
  * SYNOPSIS
  *
@@ -147,7 +148,7 @@ void silc_mutex_unlock(SilcMutex mutex);
  ***/
 void silc_mutex_assert_locked(SilcMutex mutex);
 
-/****f* silcutil/SilcMutexAPI/silc_rwlock_alloc
+/****f* silcutil/silc_rwlock_alloc
  *
  * SYNOPSIS
  *
@@ -163,7 +164,7 @@ void silc_mutex_assert_locked(SilcMutex mutex);
  ***/
 SilcBool silc_rwlock_alloc(SilcRwLock *rwlock);
 
-/****f* silcutil/SilcRwLockAPI/silc_rwlock_free
+/****f* silcutil/silc_rwlock_free
  *
  * SYNOPSIS
  *
@@ -177,7 +178,7 @@ SilcBool silc_rwlock_alloc(SilcRwLock *rwlock);
  ***/
 void silc_rwlock_free(SilcRwLock rwlock);
 
-/****f* silcutil/SilcRwLockAPI/silc_rwlock_rdlock
+/****f* silcutil/silc_rwlock_rdlock
  *
  * SYNOPSIS
  *
@@ -189,13 +190,13 @@ void silc_rwlock_free(SilcRwLock rwlock);
  *    is locked by a writer the current thread will block until the other
  *    thread has issued silc_rwlock_unlock for the `rwlock'.  This function
  *    may be called multiple times to acquire the read lock.  There must be
- *    same amount of silc_rwlock_unlock calls.  If `rwlock' is NULL this
+ *    same number of silc_rwlock_unlock calls.  If `rwlock' is NULL this
  *    function has no effect.
  *
  ***/
 void silc_rwlock_rdlock(SilcRwLock rwlock);
 
-/****f* silcutil/SilcRwLockAPI/silc_rwlock_wrlock
+/****f* silcutil/silc_rwlock_wrlock
  *
  * SYNOPSIS
  *
@@ -206,12 +207,14 @@ void silc_rwlock_rdlock(SilcRwLock rwlock);
  *    Acquires write lock of the read/write lock `rwlock'.  If the `rwlock'
  *    is locked by a writer or a reader the current thread will block until
  *    the other thread(s) have issued silc_rwlock_unlock for the `rwlock'.
- *    If `rwlock' is NULL this function has no effect.
+ *    A thread may acquire the write lock only once.  A deadlock may occur
+ *    if thread attempts to acquire the write lock when it has already done
+ *    so.  If `rwlock' is NULL this function has no effect.
  *
  ***/
 void silc_rwlock_wrlock(SilcRwLock rwlock);
 
-/****f* silcutil/SilcRwLockAPI/silc_rwlock_unlock
+/****f* silcutil/silc_rwlock_unlock
  *
  * SYNOPSIS
  *