Added silc_mutex_trylock

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

diff --git a/lib/silcutil/silcmutex.h b/lib/silcutil/silcmutex.h
index 070a2e9a3e0e774e5e0934cb084eb0680efb1ed4..2ff79f39c15e42cd39c04241c5aa8339c0436bec 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
  *
@@ -77,7 +77,7 @@ typedef struct SilcRwLockStruct *SilcRwLock;
  ***/
 SilcBool silc_mutex_alloc(SilcMutex *mutex);
 
-/****f* silcutil/SilcMutexAPI/silc_mutex_free
+/****f* silcutil/silc_mutex_free
  *
  * SYNOPSIS
  *
@@ -91,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
  *
@@ -113,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
  *
@@ -133,7 +133,23 @@ void silc_mutex_lock(SilcMutex mutex);
  ***/
 void silc_mutex_unlock(SilcMutex mutex);
 
-/****f* silcutil/SilcMutexAPI/silc_mutex_assert_locked
+/****f* silcutil/silc_mutex_trylock
+ *
+ * SYNOPSIS
+ *
+ *    SilcBool silc_mutex_trylock(SilcMutex mutex);
+ *
+ * DESCRIPTION
+ *
+ *    Attempts to lock the `mutex'.  Returns TRUE if the caller was able
+ *    to acquire the lock and FALSE if the mutex is already locked.  If the
+ *    mutex is already locked the caller cannot acquire the lock at this
+ *    time.
+ *
+ ***/
+SilcBool silc_mutex_trylock(SilcMutex mutex);
+
+/****f* silcutil/silc_mutex_assert_locked
  *
  * SYNOPSIS
  *
@@ -148,7 +164,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
  *
@@ -164,7 +180,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
  *
@@ -178,7 +194,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
  *
@@ -190,13 +206,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
  *
@@ -207,12 +223,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
  *