SILC Runtime Toolkit 1.2 Beta 1

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

diff --git a/lib/silcutil/silccond.h b/lib/silcutil/silccond.h
index 25f7c92cb676570f63f84dcfdfe79e377880fbdd..3774be21db93254b018f3fe39cd7e2ce1f06905c 100644 (file)
--- a/lib/silcutil/silccond.h
+++ b/lib/silcutil/silccond.h
@@ -4,7 +4,7 @@
 
   Author: Pekka Riikonen <priikone@silcnet.org>
 
-  Copyright (C) 2006 Pekka Riikonen
+  Copyright (C) 2006 - 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,20 +17,39 @@
 
 */
 
-/****h* silcutil/SILC Conditional Variable Interface
+/****h* silcutil/Condition Variable Interface
  *
  * DESCRIPTION
  *
- * A conditional variable interface for multi-thread synchronization.
- * Conditional variables enable threads to suspend execution and yield
+ * A condition variable interface for multi-thread synchronization.
+ * Condition variables enable threads to suspend execution and yield
  * the processors until some predicate on some shared data is satisfied.
  *
+ * EXAMPLE
+ *
+ * Thread 1:
+ *
+ * // Wait for signal
+ * silc_mutex_lock(lock);
+ * while (c->a == NULL)
+ *   silc_cond_wait(cond, lock);
+ * ...
+ * silc_mutex_unlock(lock);
+ *
+ * Thread 2:
+ *
+ * // Signal
+ * silc_mutex_lock(lock);
+ * c->a = context;
+ * silc_cond_signal(cond);
+ * silc_mutex_unlock(lock);
+ *
  ***/
 
 #ifndef SILCCOND_H
 #define SILCCOND_H
 
-/****s* silcutil/SilcCondAPI/SilcCond
+/****s* silcutil/SilcCond
  *
  * NAME
  *
@@ -38,14 +57,14 @@
  *
  * DESCRIPTION
  *
- *    This context is the actual conditional variable and is allocated
+ *    This context is the actual condition variable and is allocated
  *    by silc_cond_alloc and given as argument to all silc_cond_*
  *    functions.  It is freed by the silc_cond_free function.
  *
  ***/
 typedef struct SilcCondStruct *SilcCond;
 
-/****s* silcutil/SilcCondAPI/silc_cond_alloc
+/****f* silcutil/silc_cond_alloc
  *
  * SYNOPSIS
  *
@@ -53,15 +72,16 @@ typedef struct SilcCondStruct *SilcCond;
  *
  * DESCRIPTION
  *
- *    Allocates SILC Conditional variable context.  The conditional must
+ *    Allocates SILC Condition variable context.  The condition must
  *    be allocated before it can be used.  It is freed by the
  *    silc_cond_free function.  This returns TRUE and allocated
- *    conditional in to the `cond' pointer and FALSE on error.
+ *    condition in to the `cond' pointer and FALSE if system is out of
+ *    memory.
  *
  ***/
 SilcBool silc_cond_alloc(SilcCond *cond);
 
-/****s* silcutil/SilcCondAPI/silc_cond_free
+/****f* silcutil/silc_cond_free
  *
  * SYNOPSIS
  *
@@ -69,13 +89,13 @@ SilcBool silc_cond_alloc(SilcCond *cond);
  *
  * DESCRIPTION
  *
- *    Free conditional variable context.  If `cond' is NULL this function
+ *    Free condition variable context.  If `cond' is NULL this function
  *    has no effect.
  *
  ***/
 void silc_cond_free(SilcCond cond);
 
-/****s* silcutil/SilcCondAPI/silc_cond_wait
+/****f* silcutil/silc_cond_wait
  *
  * SYNOPSIS
  *
@@ -83,8 +103,8 @@ void silc_cond_free(SilcCond cond);
  *
  * DESCRIPTION
  *
- *    Waits for conditional variable `cond' to be signalled.  This function
- *    will block the calling thread until the conditional variable is
+ *    Waits for condition variable `cond' to be signalled.  This function
+ *    will block the calling thread until the condition variable is
  *    signalled.  The `mutex' must be locked before calling this function.
  *    The `mutex' will be unlocked inside this function.  After this
  *    function returns the `mutex' is in locked state again.
@@ -100,7 +120,7 @@ void silc_cond_free(SilcCond cond);
  ***/
 void silc_cond_wait(SilcCond cond, SilcMutex mutex);
 
-/****s* silcutil/SilcCondAPI/silc_cond_timedwait
+/****f* silcutil/silc_cond_timedwait
  *
  * SYNOPSIS
  *
@@ -108,11 +128,11 @@ void silc_cond_wait(SilcCond cond, SilcMutex mutex);
  *
  * DESCRIPTION
  *
- *    Waits for conditional variable `cond' to be signalled or for the
+ *    Waits for condition variable `cond' to be signalled or for the
  *    `timeout' to expire.  The timeout is in milliseconds.  If it is 0
  *    no timeout exist.  Returns FALSE if timeout expired, TRUE when
  *    signalled.  This function will block the calling thread until the
- *    conditional variable is signalled.  The `mutex' must be locked before
+ *    condition variable is signalled.  The `mutex' must be locked before
  *    calling this function.  The `mutex' will be unlocked inside this
  *    function.  After this function returns the `mutex' is in locked
  *    state again.
@@ -120,7 +140,7 @@ void silc_cond_wait(SilcCond cond, SilcMutex mutex);
  ***/
 SilcBool silc_cond_timedwait(SilcCond cond, SilcMutex mutex, int timeout);
 
-/****s* silcutil/SilcCondAPI/silc_cond_signal
+/****f* silcutil/silc_cond_signal
  *
  * SYNOPSIS
  *
@@ -147,7 +167,7 @@ SilcBool silc_cond_timedwait(SilcCond cond, SilcMutex mutex, int timeout);
  ***/
 void silc_cond_signal(SilcCond cond);
 
-/****s* silcutil/SilcCondAPI/silc_cond_broadcast
+/****f* silcutil/silc_cond_broadcast
  *
  * SYNOPSIS
  *