summaryrefslogtreecommitdiff
path: root/src/lib/eina/eina_thread.h
blob: 93542f29a3e021553b3271dec0f85f9d18d6ad4b (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
/* EINA - EFL data type library
 * Copyright (C) 2012 Cedric Bail
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library;
 * if not, see <http://www.gnu.org/licenses/>.
 */

#ifndef EINA_THREAD_H_
#define EINA_THREAD_H_

#include "eina_config.h"
#include "eina_types.h"
#include "eina_error.h"

#include <stdint.h>

/**
 * @defgroup Eina_Thread_Group Thread
 * @ingroup Eina_Tools_Group
 *
 * Abstracts platform threads, providing a uniform API. It's modeled
 * after POSIX THREADS (pthreads), on Linux they are almost 1:1
 * mapping.
 *
 * @see @ref Eina_Lock_Group for mutex/locking abstraction.
 *
 * @since 1.8
 * @{
 */

/**
 * @typedef Eina_Thread
 * Type for a generic thread.
 */
typedef uintptr_t Eina_Thread;

/**
 * @typedef Eina_Thread_Cb
 * Type for the definition of a thread callback function
 */
typedef void *(*Eina_Thread_Cb)(void *data, Eina_Thread t);

/**
 * @typedef Eina_Thread_Priority
 * Type to enumerate different thread priorities
 */
typedef enum _Eina_Thread_Priority
{
  EINA_THREAD_URGENT,     /**< Higher than average process priority */
  EINA_THREAD_NORMAL,     /**< Standard process priority */
  EINA_THREAD_BACKGROUND, /**< Lower than average process priority */
  EINA_THREAD_IDLE        /**< Thread to be executed only when the processor is idle */
} Eina_Thread_Priority;

/**
 * @brief Returns identifier of the current thread.
 * @return identifier of current thread.
 * @since 1.8
 */
EAPI Eina_Thread eina_thread_self(void) EINA_WARN_UNUSED_RESULT;

/**
 * @brief Checks if two thread identifiers are the same.
 * @param[in] t1 first thread identifier to compare.
 * @param[in] t2 second thread identifier to compare.
 * @return #EINA_TRUE if they are equal, #EINA_FALSE otherwise.
 * @since 1.8
 */
EAPI Eina_Bool eina_thread_equal(Eina_Thread t1, Eina_Thread t2) EINA_WARN_UNUSED_RESULT;

/**
 * @brief Creates a new thread, setting its priority and affinity.
 *
 * @param[out] t where to return the thread identifier. Must @b not be @c NULL.
 * @param[in] prio thread priority to use, usually EINA_THREAD_BACKGROUND
 * @param[in] affinity thread affinity to use. To not set affinity use @c -1.
 * @param[in] func function to run in the thread. Must @b not be @c NULL.
 * @param[in] data context data to provide to @a func as first argument.
 * @return #EINA_TRUE if thread was created, #EINA_FALSE on errors.
 * @since 1.8
 */
EAPI Eina_Bool eina_thread_create(Eina_Thread *t,
                                  Eina_Thread_Priority prio, int affinity,
                                  Eina_Thread_Cb func, const void *data) EINA_ARG_NONNULL(1, 4) EINA_WARN_UNUSED_RESULT;

/**
 * @brief The return value of eina_thread_join() if it was canceled with
 * eina_thread_cancel().
 *
 * A thread must be explicitly flagged as cancellable with
 * eina_thread_cancellable_set(), by default it's not and this value
 * shouldn't be returned.
 *
 * @see eina_thread_join()
 *
 * @since 1.19
 */
EAPI extern const void *EINA_THREAD_JOIN_CANCELED;

/**
 * @brief Joins a currently running thread, waiting until it finishes.
 *
 * This function will block the current thread until @a t
 * finishes. The returned value is the one returned by @a t @c func()
 * and may be @c NULL on errors. See @ref Eina_Error_Group to identify
 * problems.
 *
 * @param[in] t thread identifier to wait.
 * @return value returned by @a t creation function @c func() or
 *         @c NULL on errors. Check error with @ref Eina_Error_Group.
 *         If the thread was canceled, it will return
 *         EINA_THREAD_JOIN_CANCELED.
 * @since 1.8
 */
EAPI void *eina_thread_join(Eina_Thread t);

/**
 * @brief Sets the name of a given thread for debugging purposes.
 *
 * This maps to the pthread_setname_np() GNU extension or similar
 * if available. The name may be limited in size (possibly 16
 * characters including the null byte terminator). This is useful
 * for debugging to name a thread so external tools can display a
 * meaningful name attached to the thread.
 *
 * @param[in] t thread to set the name of
 * @param[in] name a string to name the thread - this cannot be NULL
 * @return EINA_TRUE if it succeeds in setting the name or EINA_FALSE
 *         otherwise.
 * @since 1.16
 */
EAPI Eina_Bool eina_thread_name_set(Eina_Thread t, const char *name);

/**
 * @brief Attempts to cancel a running thread.
 *
 * This function sends a cancellation request to the thread, however
 * that request is only fulfilled if the thread is cancellable
 * (eina_thread_cancellable_set() with EINA_TRUE as first parameter)
 * and it will wait for a cancellation point, be
 * eina_thread_cancel_checkpoint() or some syscall as defined in
 * man:pthreads(7).
 *
 * A thread that was canceled will return EINA_THREAD_JOIN_CANCELED
 * when eina_thread_join() is called.
 *
 * @param[in] t Thread to cancel.
 *
 * @return EINA_FALSE if thread was not running, EINA_TRUE
 *         otherwise. Note that if a thread is not cancellable and it
 *         is running, this function will return EINA_TRUE!
 *
 * @since 1.19
 */
EAPI Eina_Bool eina_thread_cancel(Eina_Thread t);

/**
 * @brief Enables or disables if the current thread can be canceled.
 *
 * By default eina_thread_create() will return a thread with
 * cancellation disabled. One can enable the cancellation by using
 * EINA_TRUE in @a cancellable.
 *
 * Eina threads follow pthread_setcanceltype()
 * PTHREAD_CANCEL_DEFERRED, that is, the actual termination will wait
 * for a cancellation point, usually a syscall defined in
 * man:pthreads(7) or an explicit cancellation point defined with
 * eina_thread_cancel_checkpoint().
 *
 * In order to provide cleanup around critical blocks use
 * EINA_THREAD_CLEANUP_PUSH() and EINA_THREAD_CLEANUP_POP() macros
 * (which maps to pthread_cleanup_push() and pthread_cleanup_pop()),
 * or the helper function eina_thread_cancellable_run() which does the
 * pair for you.
 *
 * @param[in] cancellable If EINA_TRUE, this thread will be accept
 *        cancellation requests. If EINA_FALSE -- the default, it will
 *        ignore cancellation requests.
 * @param[in] was_cancellable If non-NULL, will return the previous state,
 *        shall you want to restore.
 *
 * @return EINA_TRUE if it succeeds in setting the cancellable state
 *        or EINA_FALSE otherwise.
 *
 * @see eina_thread_cancel_checkpoint()
 * @see EINA_THREAD_CLEANUP_PUSH()
 * @see EINA_THREAD_CLEANUP_POP()
 * @see eina_thread_cancellable_run()
 * @see eina_thread_cancel()
 *
 * @since 1.19
 */
EAPI Eina_Bool eina_thread_cancellable_set(Eina_Bool cancellable, Eina_Bool *was_cancellable);

/**
 * If the current thread is cancellable, this introduces a
 * cancellation check point. Otherwise it's a no-operation.
 *
 * Eina threads follow pthread_setcanceltype()
 * PTHREAD_CANCEL_DEFERRED, that is, the actual termination will wait
 * for a cancellation point, usually a syscall defined in
 * man:pthreads(7) or an explicit cancellation point defined with this
 * function.
 *
 * @see eina_thread_cancel_checkpoint()
 *
 * @since 1.19
 */
EAPI void eina_thread_cancel_checkpoint(void);

/**
 * @def EINA_THREAD_CLEANUP_PUSH(cleanup, data)
 *
 * @brief Pushes a cleanup function to be executed when the thread is
 * canceled.
 *
 * This macro will schedule a function cleanup(data) to be executed if
 * the thread is canceled with eina_thread_cancel() and the thread
 * was previously marked as cancellable with
 * eina_thread_cancellable_set().
 *
 * It @b must be paired with EINA_THREAD_CLEANUP_POP() in the same
 * code block as they will expand to do {} while ()!
 *
 * The cleanup function may also be executed if
 * EINA_THREAD_CLEANUP_POP(EINA_TRUE) is used.
 *
 * @note If the block within EINA_THREAD_CLEANUP_PUSH() and
 *       EINA_THREAD_CLEANUP_POP() returns, the cleanup callback will
 *       @b not be executed! To avoid problems prefer to use
 *       eina_thread_cancellable_run()!
 *
 * @param[in] cleanup The function to execute on cancellation.
 * @param[in] data The context to give to cleanup function.
 *
 * @see eina_thread_cancellable_run()
 *
 * @since 1.19
 */
#define EINA_THREAD_CLEANUP_PUSH(cleanup, data) \
  pthread_cleanup_push(cleanup, data)

/**
 * @def EINA_THREAD_CLEANUP_POP(exec_cleanup)
 *
 * @brief Pops a cleanup function to be executed when the thread is
 * canceled.
 *
 * This macro will remove a previously pushed cleanup function, thus
 * if the thread is canceled with eina_thread_cancel() and the thread
 * was previously marked as cancellable with
 * eina_thread_cancellable_set(), that cleanup won't be executed
 * anymore.
 *
 * It @b must be paired with EINA_THREAD_CLEANUP_PUSH() in the same
 * code block as they will expand to do {} while ()!
 *
 * @note If the block within EINA_THREAD_CLEANUP_PUSH() and
 *       EINA_THREAD_CLEANUP_POP() returns, the cleanup callback will
 *       @b not be executed even if exec_cleanup is EINA_TRUE! To
 *       avoid problems prefer to use eina_thread_cancellable_run()!
 *
 * @param[in] exec_cleanup if EINA_TRUE, the function registered with
 *        EINA_THREAD_CLEANUP_PUSH() will be executed.
 *
 * @see eina_thread_cancellable_run()
 *
 * @since 1.19
 */
#define EINA_THREAD_CLEANUP_POP(exec_cleanup) \
  pthread_cleanup_pop(exec_cleanup)

/**
 * @typedef Eina_Thread_Cancellable_Run_Cb
 * Type for the definition of a cancellable callback to run.
 *
 * @since 1.19
 */
typedef void *(*Eina_Thread_Cancellable_Run_Cb)(void *data);

/**
 * This function will setup cleanup callback, turn the thread
 * cancellable, execute the given callback, reset the cancellable
 * state to its old value, run the cleanup callback and then return
 * the callback return value.
 *
 * @note cleanup_cb is configured @b before the thread is made
 *       cancellable, thus it @b will be executed while @a cb may not
 *       in the case the thread was already canceled and that was
 *       pending.
 *
 * This helper does exactly the following code. Should you need a
 * slightly different behavior, use the base calls yourself.
 *
 * @code
 *    Eina_Bool old = EINA_FALSE;
 *    void *ret;
 *
 *    EINA_THREAD_CLEANUP_PUSH(cleanup_cb, data);
 *    eina_thread_cancellable_set(EINA_TRUE, &old); // is a cancellation point
 *    ret = cb(data); // may not run if was previously canceled
 *    EINA_THREAD_CLEANUP_POP(EINA_TRUE);
 *    eina_thread_cancellable_set(old, NULL);
 *    return ret;
 * @endcode
 *
 * @param[in] cb a cancellable callback to possibly run. The callback @b
 *        may not be executed if the thread had a pending cancellation
 *        request. During its execution the callback may be canceled
 *        at explicit cancellation points using
 *        eina_thread_cancel_checkpoint(), as well as some syscalls
 *        defined in man:pthreads(7).
 * @param[in] cleanup_cb a cleanup callback to be executed regardless of
 *        the thread being canceled or not. This function will be
 *        executed even if @a cb wasn't.
 * @param[in] data context to give to both @a cb and @a cleanup_cb.
 *
 * @return the return value of @a cb. If the thread was canceled,
 *         this function will not return.
 *
 * @since 1.19
 */
EAPI void *eina_thread_cancellable_run(Eina_Thread_Cancellable_Run_Cb cb, Eina_Free_Cb cleanup_cb, void *data);

/**
 * @}
 */

#endif