lib/silcutil/silcthread.h

   1 /*
   2
   3   silcmutex.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 2001 - 2005 Pekka Riikonen
   8
   9   This program is free software; you can redistribute it and/or modify
  10   it under the terms of the GNU General Public License as published by
  11   the Free Software Foundation; version 2 of the License.
  12
  13   This program is distributed in the hope that it will be useful,
  14   but WITHOUT ANY WARRANTY; without even the implied warranty of
  15   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16   GNU General Public License for more details.
  17
  18 */
  19
  20 /****h* silcutil/SILC Thread Interface
  21  *
  22  * DESCRIPTION
  23  *
  24  * Interface for SILC Thread implementation. This is platform independent
  25  * interface of threads for applications that need concurrent execution
  26  * with the application's main thread. The threads created with this
  27  * interface executes concurrently with the calling thread.
  28  *
  29  ***/
  30
  31 #ifndef SILCTHREAD_H
  32 #define SILCTHREAD_H
  33
  34 /* Prototypes */
  35
  36 /****s* silcutil/SilcThreadAPI/SilcThread
  37  *
  38  * NAME
  39  *
  40  *    typedef struct SilcThreadStruct *SilcThread;
  41  *
  42  * DESCRIPTION
  43  *
  44  *    This context is the actual SILC Thread and is returned by
  45  *    the silc_thread_create functions, and given as arguments to
  46  *    some of the silc_thread_* functions. This context and its
  47  *    resources are released automatically when the thread exits.
  48  *
  49  ***/
  50 typedef void *SilcThread;
  51
  52 /****f* silcutil/SilcThreadAPI/SilcThreadStart
  53  *
  54  * SYNOPSIS
  55  *
  56  *    typedef void *(*SilcThreadStart)(void *context);
  57  *
  58  * DESCRIPTION
  59  *
  60  *    A callback function that is called when the thread is created
  61  *    by the silc_thread_create function.  This returns the return value
  62  *    of the thread. If another thread is waiting this thread's
  63  *    destruction with silc_thread_wait the returned value is passed
  64  *    to that thread. The thread is destroyed when this function
  65  *    returns.
  66  *
  67  ***/
  68 typedef void *(*SilcThreadStart)(void *context);
  69
  70 /****f* silcutil/SilcThreadAPI/silc_thread_create
  71  *
  72  * SYNOPSIS
  73  *
  74  *    SilcThread silc_thread_create(SilcThreadStart start_func,
  75  *                                  void *context, SilcBool waitable);
  76  * DESCRIPTION
  77  *
  78  *    Creates a new thread. The `start_func' with `context' will be
  79  *    called if the thread was created. This function returns a pointer
  80  *    to the thread or NULL if the thread could not be created.  All
  81  *    resources of the returned pointer is freed automatically when the
  82  *    thread exits.
  83  *
  84  *    If the `waitable' is set to TRUE then another thread can wait
  85  *    this thread's destruction with silc_thread_wait. If it is set to
  86  *    FALSE the thread is not waitable.
  87  *
  88  * NOTES
  89  *
  90  *    If the `waitable' is TRUE the thread's resources are not freed
  91  *    when it exits until another thread has issued silc_thread_wait.
  92  *    If the `waitable' is TRUE then another thread must always issue
  93  *    silc_thread_wait to avoid memory leaks.
  94  *
  95  *    On Symbian Cleanup Stack is created and new Active Scheduler is
  96  *    installed automatically for the created thread.  The thread also
  97  *    shares heap with the calling thread.
  98  *
  99  ***/
 100 SilcThread silc_thread_create(SilcThreadStart start_func, void *context,
 101                               SilcBool waitable);
 102
 103 /****f* silcutil/SilcThreadAPI/silc_thread_exit
 104  *
 105  * SYNOPSIS
 106  *
 107  *    void silc_thread_exit(void *exit_value);
 108  *
 109  * DESCRIPTION
 110  *
 111  *    Exits the current thread. This can be called to explicitly exit
 112  *    the thread with `exit_value'. Another way to exit (destroy) the
 113  *    current thread is to return from the SilcThreadStart function
 114  *    with exit value. The exit value is passed to another thread if it
 115  *    is waiting it with silc_thread_wait function.
 116  *
 117  ***/
 118 void silc_thread_exit(void *exit_value);
 119
 120 /****f* silcutil/SilcThreadAPI/silc_thread_self
 121  *
 122  * SYNOPSIS
 123  *
 124  *    SilcThread silc_thread_self(void);
 125  *
 126  * DESCRIPTION
 127  *
 128  *    Returns a pointer to the current thread.
 129  *
 130  ***/
 131 SilcThread silc_thread_self(void);
 132
 133 /****f* silcutil/SilcThreadAPI/silc_thread_wait
 134  *
 135  * SYNOPSIS
 136  *
 137  *    SilcBool silc_thread_wait(SilcThread thread, void **exit_value);
 138  *
 139  * DESCRIPTION
 140  *
 141  *    Waits until the thread indicated by `thread' finishes. This blocks
 142  *    the execution of the current thread. The thread is finished if it
 143  *    calls silc_thread_exit or is destroyed naturally. When the thread
 144  *    exits its exit value is saved to `exit_value' and TRUE is returned.
 145  *    If the `thread' is not waitable this will return immediately with
 146  *    FALSE value.
 147  *
 148  ***/
 149 SilcBool silc_thread_wait(SilcThread thread, void **exit_value);
 150
 151 /****f* silcutil/SilcThreadAPI/silc_thread_yield
 152  *
 153  * SYNOPSIS
 154  *
 155  *    void silc_thread_yield(void);
 156  *
 157  * DESCRIPTION
 158  *
 159  *    Yield the processor.  The calling thread will yield the processor and
 160  *    give execution time for other threads, until its turn comes up again.
 161  *
 162  ***/
 163 void silc_thread_yield(void);
 164
 165 #endif