lib/silcutil/silcthread.h

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