5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 2001 Pekka Riikonen
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.
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.
21 /****h* silcutil/SilcThreadAPI
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.
37 /****s* silcutil/SilcThreadAPI/SilcThread
41 * typedef struct SilcThreadStruct *SilcThread;
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.
51 typedef void *SilcThread;
53 /****f* silcutil/SilcThreadAPI/SilcThreadStart
57 * typedef void *(*SilcThreadStart)(void *context);
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
69 typedef void *(*SilcThreadStart)(void *context);
71 /****f* silcutil/SilcThreadAPI/silc_thread_create
75 * SilcThread silc_thread_create(SilcThreadStart start_func, void *context);
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
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.
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.
97 SilcThread silc_thread_create(SilcThreadStart start_func, void *context,
100 /****f* silcutil/SilcThreadAPI/silc_thread_exit
104 * void silc_thread_exit(void *exit_value);
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.
115 void silc_thread_exit(void *exit_value);
117 /****f* silcutil/SilcThreadAPI/silc_thread_self
121 * SilcThread silc_thread_self(void);
125 * Returns a pointer to the current thread.
128 SilcThread silc_thread_self(void);
130 /****f* silcutil/SilcThreadAPI/silc_thread_wait
134 * bool silc_thread_wait(SilcThread thread, void **exit_value);
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
146 bool silc_thread_wait(SilcThread thread, void **exit_value);