SILC Runtime Toolkit 1.2 Beta 1

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

diff --git a/lib/silcutil/silcthread.h b/lib/silcutil/silcthread.h
index 2a7888049341147d3bfdb85a7849cf35efcf8665..c16dbd95ad10061f604797f8c5ed8cd24077a28c 100644 (file)
--- a/lib/silcutil/silcthread.h
+++ b/lib/silcutil/silcthread.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 Thread Interface
+/****h* silcutil/Thread Interface
  *
  * DESCRIPTION
  *
@@ -30,6 +30,9 @@
  * in the threads.  The thread pool manages the threads creation and
  * destruction.
  *
+ * The interface also provides routines for accessing the Thread-local
+ * storage (Tls) on all supported platforms.
+ *
  ***/
 
 #ifndef SILCTHREAD_H
@@ -39,7 +42,7 @@
 
 /* Prototypes */
 
-/****s* silcutil/SilcThreadAPI/SilcThread
+/****s* silcutil/SilcThread
  *
  * NAME
  *
@@ -55,7 +58,7 @@
  ***/
 typedef void *SilcThread;
 
-/****f* silcutil/SilcThreadAPI/SilcThreadStart
+/****f* silcutil/SilcThreadStart
  *
  * SYNOPSIS
  *
@@ -73,7 +76,7 @@ typedef void *SilcThread;
  ***/
 typedef void *(*SilcThreadStart)(void *context);
 
-/****f* silcutil/SilcThreadAPI/silc_thread_create
+/****f* silcutil/silc_thread_create
  *
  * SYNOPSIS
  *
@@ -106,7 +109,7 @@ typedef void *(*SilcThreadStart)(void *context);
 SilcThread silc_thread_create(SilcThreadStart start_func, void *context,
                              SilcBool waitable);
 
-/****f* silcutil/SilcThreadAPI/silc_thread_exit
+/****f* silcutil/silc_thread_exit
  *
  * SYNOPSIS
  *
@@ -123,7 +126,7 @@ SilcThread silc_thread_create(SilcThreadStart start_func, void *context,
  ***/
 void silc_thread_exit(void *exit_value);
 
-/****f* silcutil/SilcThreadAPI/silc_thread_self
+/****f* silcutil/silc_thread_self
  *
  * SYNOPSIS
  *
@@ -136,7 +139,7 @@ void silc_thread_exit(void *exit_value);
  ***/
 SilcThread silc_thread_self(void);
 
-/****f* silcutil/SilcThreadAPI/silc_thread_wait
+/****f* silcutil/silc_thread_wait
  *
  * SYNOPSIS
  *
@@ -154,7 +157,7 @@ SilcThread silc_thread_self(void);
  ***/
 SilcBool silc_thread_wait(SilcThread thread, void **exit_value);
 
-/****f* silcutil/SilcThreadAPI/silc_thread_yield
+/****f* silcutil/silc_thread_yield
  *
  * SYNOPSIS
  *
@@ -168,7 +171,7 @@ SilcBool silc_thread_wait(SilcThread thread, void **exit_value);
  ***/
 void silc_thread_yield(void);
 
-/****s* silcutil/SilcThreadAPI/SilcThreadPool
+/****s* silcutil/SilcThreadPool
  *
  * NAME
  *
@@ -184,7 +187,7 @@ void silc_thread_yield(void);
  ***/
 typedef struct SilcThreadPoolStruct *SilcThreadPool;
 
-/****f* silcutil/SilcThreadAPI/SilcThreadPoolFunc
+/****f* silcutil/SilcThreadPoolFunc
  *
  * SYNOPSIS
  *
@@ -195,13 +198,13 @@ typedef struct SilcThreadPoolStruct *SilcThreadPool;
  *
  *    A callback function of this type is given as argument to the
  *    silc_thread_pool_run.  The `schedule' is the scheduler and the
- *    `context' is the `run_context' or `completion_context' given as
- *    argument to silc_thread_pool_run.
+ *    `context' is the `run_context' given as argument to
+ *    silc_thread_pool_run.
  *
  ***/
 typedef void (*SilcThreadPoolFunc)(SilcSchedule schedule, void *context);
 
-/****f* silcutil/SilcThreadAPI/silc_thread_pool_alloc
+/****f* silcutil/silc_thread_pool_alloc
  *
  * SYNOPSIS
  *
@@ -213,10 +216,11 @@ typedef void (*SilcThreadPoolFunc)(SilcSchedule schedule, void *context);
  * DESCRIPTION
  *
  *    Allocate thread pool with at least `min_threads' and at most
- *    `max_threads' many threads.  If `stack' is non-NULL all memory is
- *    allocated from the `stack'.  If `start_min_threads' is TRUE this will
+ *    `max_threads' many threads. If `start_min_threads' is TRUE this will
  *    start `min_threads' many threads immediately.  Returns the thread
- *    pool context or NULL on error.
+ *    pool context or NULL on error.  If `stack' is non-NULL memory is
+ *    allocated from `stack'.  When the thread pool is freed the memory
+ *    is returned to `stack'.
  *
  * EXAMPLE
  *
@@ -239,7 +243,7 @@ SilcThreadPool silc_thread_pool_alloc(SilcStack stack,
                                      SilcUInt32 max_threads,
                                      SilcBool start_min_threads);
 
-/****f* silcutil/SilcThreadAPI/silc_thread_pool_free
+/****f* silcutil/silc_thread_pool_free
  *
  * SYNOPSIS
  *
@@ -254,7 +258,7 @@ SilcThreadPool silc_thread_pool_alloc(SilcStack stack,
  ***/
 void silc_thread_pool_free(SilcThreadPool tp, SilcBool wait_unfinished);
 
-/****f* silcutil/SilcThreadAPI/silc_thread_pool_run
+/****f* silcutil/silc_thread_pool_run
  *
  * SYNOPSIS
  *
@@ -263,7 +267,7 @@ void silc_thread_pool_free(SilcThreadPool tp, SilcBool wait_unfinished);
  *                                  SilcSchedule schedule,
  *                                  SilcThreadPoolFunc run,
  *                                  void *run_context,
- *                                  SilcThreadPoolFunc completion,
+ *                                  SilcTaskCallback completion,
  *                                  void *completion_context);
  *
  * DESCRIPTION
@@ -287,10 +291,10 @@ SilcBool silc_thread_pool_run(SilcThreadPool tp,
                              SilcSchedule schedule,
                              SilcThreadPoolFunc run,
                              void *run_context,
-                             SilcThreadPoolFunc completion,
+                             SilcTaskCallback completion,
                              void *completion_context);
 
-/****f* silcutil/SilcThreadAPI/silc_thread_pool_set_max_threads
+/****f* silcutil/silc_thread_pool_set_max_threads
  *
  * SYNOPSIS
  *
@@ -306,20 +310,20 @@ SilcBool silc_thread_pool_run(SilcThreadPool tp,
 void silc_thread_pool_set_max_threads(SilcThreadPool tp,
                                      SilcUInt32 max_threads);
 
-/****f* silcutil/SilcThreadAPI/silc_thread_pool_num_max_threads
+/****f* silcutil/silc_thread_pool_get_max_threads
  *
  * SYNOPSIS
  *
- *    SilcUInt32 silc_thread_pool_num_max_threads(SilcThreadPool tp);
+ *    SilcUInt32 silc_thread_pool_get_max_threads(SilcThreadPool tp);
  *
  * DESCRIPTION
  *
  *    Returns the number of maximum threads to which the pool can grow.
  *
  ***/
-SilcUInt32 silc_thread_pool_num_max_threads(SilcThreadPool tp);
+SilcUInt32 silc_thread_pool_get_max_threads(SilcThreadPool tp);
 
-/****f* silcutil/SilcThreadAPI/silc_thread_pool_num_free_threads
+/****f* silcutil/silc_thread_pool_num_free_threads
  *
  * SYNOPSIS
  *
@@ -333,7 +337,7 @@ SilcUInt32 silc_thread_pool_num_max_threads(SilcThreadPool tp);
  ***/
 SilcUInt32 silc_thread_pool_num_free_threads(SilcThreadPool tp);
 
-/****f* silcutil/SilcThreadAPI/silc_thread_pool_purge
+/****f* silcutil/silc_thread_pool_purge
  *
  * SYNOPSIS
  *
@@ -348,4 +352,38 @@ SilcUInt32 silc_thread_pool_num_free_threads(SilcThreadPool tp);
  ***/
 void silc_thread_pool_purge(SilcThreadPool tp);
 
+/****f* silcutil/silc_thread_tls_set
+ *
+ * SYNOPSIS
+ *
+ *    void silc_thread_tls_set(void *context);
+ *
+ * DESCRIPTION
+ *
+ *    Sets `context' into the Thread-local storage.  Any previously set
+ *    value will be replaced.  This function may be called for the main
+ *    thread also.  This function may be called also if the program does
+ *    not support threads.
+ *
+ *    To retrieve the context from the Tls, call silc_thread_tls_get.
+ *
+ ***/
+void silc_thread_tls_set(void *context);
+
+/****f* silcutil/silc_thread_tls_get
+ *
+ * SYNOPSIS
+ *
+ *    void *silc_thread_tls_get(void);
+ *
+ * DESCRIPTION
+ *
+ *    Returns context from the Thread-local storage.  If context has no been
+ *    set for the current thread NULL will be returned.
+ *
+ ***/
+void *silc_thread_tls_get(void);
+
+#include "silcthread_i.h"
+
 #endif