5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 2001 - 2005 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; version 2 of the License.
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.
20 /****h* silcutil/SILC Thread Interface
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.
36 /****s* silcutil/SilcThreadAPI/SilcThread
40 * typedef struct SilcThreadStruct *SilcThread;
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.
50 typedef void *SilcThread;
52 /****f* silcutil/SilcThreadAPI/SilcThreadStart
56 * typedef void *(*SilcThreadStart)(void *context);
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
68 typedef void *(*SilcThreadStart)(void *context);
70 /****f* silcutil/SilcThreadAPI/silc_thread_create
74 * SilcThread silc_thread_create(SilcThreadStart start_func,
75 * void *context, SilcBool waitable);
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
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.
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.
96 SilcThread silc_thread_create(SilcThreadStart start_func, void *context,
99 /****f* silcutil/SilcThreadAPI/silc_thread_exit
103 * void silc_thread_exit(void *exit_value);
107 * Exits the current thread. This can be called to explicitly exit
108 * the thread with `exit_value'. Another way to exit (destroy) the
109 * current thread is to return from the SilcThreadStart function
110 * with exit value. The exit value is passed to another thread if it
111 * is waiting it with silc_thread_wait function.
114 void silc_thread_exit(void *exit_value);
116 /****f* silcutil/SilcThreadAPI/silc_thread_self
120 * SilcThread silc_thread_self(void);
124 * Returns a pointer to the current thread.
127 SilcThread silc_thread_self(void);
129 /****f* silcutil/SilcThreadAPI/silc_thread_wait
133 * SilcBool silc_thread_wait(SilcThread thread, void **exit_value);
137 * Waits until the thread indicated by `thread' finishes. This blocks
138 * the execution of the current thread. The thread is finished if it
139 * calls silc_thread_exit or is destroyed naturally. When the thread
140 * exits its exit value is saved to `exit_value' and TRUE is returned.
141 * If the `thread' is not waitable this will return immediately with
145 SilcBool silc_thread_wait(SilcThread thread, void **exit_value);