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 1fe8bb21001512b34086243c48ed8b89ca64c18b..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 - 2007 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,7 +17,7 @@
 
 */
 
-/****h* silcutil/SILC Condition Variable Interface
+/****h* silcutil/Condition Variable Interface
  *
  * DESCRIPTION
  *
@@ -25,12 +25,31 @@
  * 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
  *
@@ -45,7 +64,7 @@
  ***/
 typedef struct SilcCondStruct *SilcCond;
 
-/****s* silcutil/SilcCondAPI/silc_cond_alloc
+/****f* silcutil/silc_cond_alloc
  *
  * SYNOPSIS
  *
@@ -56,12 +75,13 @@ typedef struct SilcCondStruct *SilcCond;
  *    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
- *    condition 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
  *
@@ -75,7 +95,7 @@ SilcBool silc_cond_alloc(SilcCond *cond);
  ***/
 void silc_cond_free(SilcCond cond);
 
-/****s* silcutil/SilcCondAPI/silc_cond_wait
+/****f* silcutil/silc_cond_wait
  *
  * SYNOPSIS
  *
@@ -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
  *
@@ -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
  *