thread: Add a function to pop and call all registered cleanup handlers
[strongswan.git] / src / libstrongswan / threading / thread.h
1 /*
2 * Copyright (C) 2009 Tobias Brunner
3 * Hochschule fuer Technik Rapperswil
4 *
5 * This program is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License as published by the
7 * Free Software Foundation; either version 2 of the License, or (at your
8 * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>.
9 *
10 * This program is distributed in the hope that it will be useful, but
11 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
12 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
13 * for more details.
14 */
15
16 /**
17 * @defgroup thread thread
18 * @{ @ingroup threading
19 */
20
21 #ifndef THREADING_THREAD_H_
22 #define THREADING_THREAD_H_
23
24 #include <utils/utils.h>
25
26 typedef struct thread_t thread_t;
27
28 /**
29 * Main function of a thread.
30 *
31 * @param arg argument provided to constructor
32 * @return value provided to threads joining the terminating thread
33 */
34 typedef void *(*thread_main_t)(void *arg);
35
36 /**
37 * Cleanup callback function for a thread.
38 *
39 * @param arg argument provided to thread_cleanup_push
40 */
41 typedef void (*thread_cleanup_t)(void *arg);
42
43 /**
44 * Thread wrapper implements simple, portable and advanced thread functions.
45 *
46 * @note All threads other than the main thread need either to be joined or
47 * detached by calling the corresponding method.
48 */
49 struct thread_t {
50
51 /**
52 * Cancel this thread.
53 */
54 void (*cancel)(thread_t *this);
55
56 /**
57 * Send a signal to this thread.
58 *
59 * @param sig the signal to be sent to this thread
60 */
61 void (*kill)(thread_t *this, int sig);
62
63 /**
64 * Detach this thread, this automatically destroys the thread object after
65 * the thread returned from its main function.
66 *
67 * @note Calling detach is like calling destroy on other objects.
68 */
69 void (*detach)(thread_t *this);
70
71 /**
72 * Join this thread, this automatically destroys the thread object
73 * afterwards.
74 *
75 * @note Calling join is like calling destroy on other objects.
76 *
77 * @return the value returned from the thread's main function or
78 * a call to exit.
79 */
80 void *(*join)(thread_t *this);
81 };
82
83 /**
84 * Create a new thread instance.
85 *
86 * @param main thread main function
87 * @param arg argument provided to the main function
88 * @return thread instance
89 */
90 thread_t *thread_create(thread_main_t main, void *arg);
91
92 /**
93 * Get a thread object for the current thread.
94 *
95 * @return thread instance
96 */
97 thread_t *thread_current();
98
99 /**
100 * Get the human-readable ID of the current thread.
101 *
102 * The IDs are assigned incrementally starting from 1.
103 *
104 * @return human-readable ID
105 */
106 u_int thread_current_id();
107
108 /**
109 * Push a function onto the current thread's cleanup handler stack.
110 * The callback function is called whenever the thread is cancelled, exits or
111 * thread_cleanup_pop is called with TRUE as execute argument.
112 *
113 * @param cleanup function called on thread exit
114 * @param arg argument provided to the callback
115 */
116 void thread_cleanup_push(thread_cleanup_t cleanup, void *arg);
117
118 /**
119 * Remove the top function from the current thread's cleanup handler stack
120 * and optionally execute it.
121 *
122 * @param execute TRUE to execute the function
123 */
124 void thread_cleanup_pop(bool execute);
125
126 /**
127 * Pop and execute all cleanup handlers in reverse order of registration.
128 *
129 * This function is for very special purposes only, where the caller exactly
130 * knows which cleanup handlers have been pushed. For regular use, a caller
131 * should thread_cleanup_pop() exactly the number of handlers it pushed
132 * using thread_cleanup_push().
133 */
134 void thread_cleanup_popall();
135
136 /**
137 * Enable or disable the cancelability of the current thread. The current
138 * value is returned.
139 *
140 * @param enable TRUE to enable cancelability
141 * @return the current state of the cancelability
142 */
143 bool thread_cancelability(bool enable);
144
145 /**
146 * Force creation of a cancellation point in the calling thread.
147 *
148 * This temporarily enables thread cancelability, tests for a pending
149 * cancellation request and then disables cancelability again if it was
150 * disabled before the call to thread_cancellation_point().
151 */
152 void thread_cancellation_point();
153
154 /**
155 * Exit the current thread.
156 *
157 * @param val value provided to threads joining the current thread
158 */
159 void thread_exit(void *val);
160
161 /**
162 * Called by the main thread to initialize the thread management.
163 */
164 void threads_init();
165
166 /**
167 * Called by the main thread to deinitialize the thread management.
168 */
169 void threads_deinit();
170
171 #endif /** THREADING_THREAD_H_ @} */