]>
Commit | Line | Data |
---|---|---|
9d0a979e RJ |
1 | @node Threads |
2 | @c @node Threads, Internal Probes, Debugging Support, Top | |
3 | @c %MENU% Functions, constants, and data types for working with threads | |
4 | @chapter Threads | |
5 | @cindex threads | |
6 | ||
7 | This chapter describes functions used for managing threads. | |
8 | @Theglibc{} provides two threading implementations: ISO C threads and | |
9 | POSIX threads. | |
10 | ||
11 | @menu | |
12 | * ISO C Threads:: Threads based on the ISO C specification. | |
13 | * POSIX Threads:: Threads based on the POSIX specification. | |
14 | @end menu | |
15 | ||
16 | ||
17 | @node ISO C Threads | |
18 | @section ISO C Threads | |
19 | @cindex ISO C threads | |
20 | @cindex C threads | |
21 | @pindex threads.h | |
22 | ||
23 | This section describes the @glibcadj{} ISO C threads implementation. | |
24 | To have a deeper understanding of this API, it is strongly recommended | |
25 | to read ISO/IEC 9899:2011, section 7.26, in which ISO C threads were | |
26 | originally specified. All types and function prototypes are declared | |
27 | in the header file @file{threads.h}. | |
28 | ||
29 | @menu | |
30 | * ISO C Threads Return Values:: Symbolic constants that represent a | |
31 | function's return value. | |
32 | * ISO C Thread Management:: Support for basic threading. | |
33 | * Call Once:: Single-call functions and macros. | |
34 | * ISO C Mutexes:: A low-level mechanism for mutual exclusion. | |
35 | * ISO C Condition Variables:: High-level objects for thread synchronization. | |
36 | * ISO C Thread-local Storage:: Functions to support thread-local storage. | |
37 | @end menu | |
38 | ||
39 | ||
40 | @node ISO C Threads Return Values | |
41 | @subsection Return Values | |
42 | ||
43 | The ISO C thread specification provides the following enumeration | |
44 | constants for return values from functions in the API: | |
45 | ||
46 | @vtable @code | |
47 | @item thrd_timedout | |
48 | @standards{C11, threads.h} | |
49 | A specified time was reached without acquiring the requested resource, | |
50 | usually a mutex or condition variable. | |
51 | ||
52 | @item thrd_success | |
53 | @standards{C11, threads.h} | |
54 | The requested operation succeeded. | |
55 | ||
56 | @item thrd_busy | |
57 | @standards{C11, threads.h} | |
58 | The requested operation failed because a requested resource is already | |
59 | in use. | |
60 | ||
61 | @item thrd_error | |
62 | @standards{C11, threads.h} | |
63 | The requested operation failed. | |
64 | ||
65 | @item thrd_nomem | |
66 | @standards{C11, threads.h} | |
67 | The requested operation failed because it was unable to allocate | |
68 | enough memory. | |
69 | @end vtable | |
70 | ||
71 | ||
72 | @node ISO C Thread Management | |
73 | @subsection Creation and Control | |
74 | @cindex thread creation | |
75 | @cindex thread control | |
76 | @cindex thread management | |
77 | ||
78 | @Theglibc{} implements a set of functions that allow the user to easily | |
79 | create and use threads. Additional functionality is provided to control | |
80 | the behavior of threads. | |
81 | ||
82 | The following data types are defined for managing threads: | |
83 | ||
84 | @deftp {Data Type} thrd_t | |
85 | @standards{C11, threads.h} | |
86 | A unique object that identifies a thread. | |
87 | @end deftp | |
88 | ||
89 | @deftp {Data Type} thrd_start_t | |
90 | @standards{C11, threads.h} | |
91 | This data type is an @code{int (*) (void *)} typedef that is passed to | |
92 | @code{thrd_create} when creating a new thread. It should point to the | |
93 | first function that thread will run. | |
94 | @end deftp | |
95 | ||
96 | The following functions are used for working with threads: | |
97 | ||
98 | @deftypefun int thrd_create (thrd_t *@var{thr}, thrd_start_t @var{func}, void *@var{arg}) | |
99 | @standards{C11, threads.h} | |
100 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} | |
101 | @code{thrd_create} creates a new thread that will execute the function | |
102 | @var{func}. The object pointed to by @var{arg} will be used as the | |
103 | argument to @var{func}. If successful, @var{thr} is set to the new | |
104 | thread identifier. | |
105 | ||
106 | This function may return @code{thrd_success}, @code{thrd_nomem}, or | |
107 | @code{thrd_error}. | |
108 | @end deftypefun | |
109 | ||
110 | @deftypefun thrd_t thrd_current (void) | |
111 | @standards{C11, threads.h} | |
112 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} | |
113 | This function returns the identifier of the calling thread. | |
114 | @end deftypefun | |
115 | ||
116 | @deftypefun int thrd_equal (thrd_t @var{lhs}, thrd_t @var{rhs}) | |
117 | @standards{C11, threads.h} | |
118 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} | |
119 | @code{thrd_equal} checks whether @var{lhs} and @var{rhs} refer to the | |
120 | same thread. If @var{lhs} and @var{rhs} are different threads, this | |
121 | function returns @math{0}; otherwise, the return value is non-zero. | |
122 | @end deftypefun | |
123 | ||
124 | @deftypefun int thrd_sleep (const struct timespec *@var{time_point}, struct timespec *@var{remaining}) | |
125 | @standards{C11, threads.h} | |
126 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} | |
127 | @code{thrd_sleep} blocks the execution of the current thread for at | |
128 | least until the elapsed time pointed to by @var{time_point} has been | |
129 | reached. This function does not take an absolute time, but a duration | |
130 | that the thread is required to be blocked. @xref{Time Basics}, and | |
131 | @ref{Elapsed Time}. | |
132 | ||
133 | The thread may wake early if a signal that is not ignored is received. | |
134 | In such a case, if @code{remaining} is not NULL, the remaining time | |
135 | duration is stored in the object pointed to by | |
136 | @var{remaining}. | |
137 | ||
138 | @code{thrd_sleep} returns @math{0} if it blocked for at least the | |
139 | amount of time in @code{time_point}, @math{-1} if it was interrupted | |
140 | by a signal, or a negative number on failure. | |
141 | @end deftypefun | |
142 | ||
143 | @deftypefun void thrd_yield (void) | |
144 | @standards{C11, threads.h} | |
145 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} | |
146 | @code{thrd_yield} provides a hint to the implementation to reschedule | |
147 | the execution of the current thread, allowing other threads to run. | |
148 | @end deftypefun | |
149 | ||
150 | @deftypefun {_Noreturn void} thrd_exit (int @var{res}) | |
151 | @standards{C11, threads.h} | |
152 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} | |
153 | @code{thrd_exit} terminates execution of the calling thread and sets | |
154 | its result code to @var{res}. | |
155 | ||
156 | If this function is called from a single-threaded process, the call is | |
157 | equivalent to calling @code{exit} with @code{EXIT_SUCCESS} | |
158 | (@pxref{Normal Termination}). Also note that returning from a | |
159 | function that started a thread is equivalent to calling | |
160 | @code{thrd_exit}. | |
161 | @end deftypefun | |
162 | ||
163 | @deftypefun int thrd_detach (thrd_t @var{thr}) | |
164 | @standards{C11, threads.h} | |
165 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} | |
166 | @code{thrd_detach} detaches the thread identified by @code{thr} from | |
167 | the current control thread. The resources held by the detached thread | |
168 | will be freed automatically once the thread exits. The parent thread | |
169 | will never be notified by any @var{thr} signal. | |
170 | ||
171 | Calling @code{thrd_detach} on a thread that was previously detached or | |
172 | joined by another thread results in undefined behavior. | |
173 | ||
174 | This function returns either @code{thrd_success} or @code{thrd_error}. | |
175 | @end deftypefun | |
176 | ||
177 | @deftypefun int thrd_join (thrd_t @var{thr}, int *@var{res}) | |
178 | @standards{C11, threads.h} | |
179 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} | |
180 | @code{thrd_join} blocks the current thread until the thread identified | |
181 | by @code{thr} finishes execution. If @code{res} is not NULL, the | |
182 | result code of the thread is put into the location pointed to by | |
183 | @var{res}. The termination of the thread @dfn{synchronizes-with} the | |
184 | completion of this function, meaning both threads have arrived at a | |
185 | common point in their execution. | |
186 | ||
187 | Calling @code{thrd_join} on a thread that was previously detached or | |
188 | joined by another thread results in undefined behavior. | |
189 | ||
190 | This function returns either @code{thrd_success} or @code{thrd_error}. | |
191 | @end deftypefun | |
192 | ||
193 | ||
194 | @node Call Once | |
195 | @subsection Call Once | |
196 | @cindex call once | |
197 | @cindex single-call functions | |
198 | ||
199 | In order to guarantee single access to a function, @theglibc{} | |
200 | implements a @dfn{call once function} to ensure a function is only | |
201 | called once in the presence of multiple, potentially calling threads. | |
202 | ||
203 | @deftp {Data Type} once_flag | |
204 | @standards{C11, threads.h} | |
205 | A complete object type capable of holding a flag used by @code{call_once}. | |
206 | @end deftp | |
207 | ||
208 | @defvr Macro ONCE_FLAG_INIT | |
209 | @standards{C11, threads.h} | |
210 | This value is used to initialize an object of type @code{once_flag}. | |
211 | @end defvr | |
212 | ||
213 | @deftypefun void call_once (once_flag *@var{flag}, void (*@var{func}) (void)) | |
214 | @standards{C11, threads.h} | |
215 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} | |
216 | @code{call_once} calls function @var{func} exactly once, even if | |
217 | invoked from several threads. The completion of the function | |
218 | @var{func} synchronizes-with all previous or subsequent calls to | |
219 | @code{call_once} with the same @code{flag} variable. | |
220 | @end deftypefun | |
221 | ||
222 | ||
223 | @node ISO C Mutexes | |
224 | @subsection Mutexes | |
225 | @cindex mutex | |
226 | @cindex mutual exclusion | |
227 | ||
228 | To have better control of resources and how threads access them, | |
229 | @theglibc{} implements a @dfn{mutex} object, which can help avoid race | |
230 | conditions and other concurrency issues. The term ``mutex'' refers to | |
231 | mutual exclusion. | |
232 | ||
233 | The fundamental data type for a mutex is the @code{mtx_t}: | |
234 | ||
235 | @deftp {Data Type} mtx_t | |
236 | @standards{C11, threads.h} | |
237 | The @code{mtx_t} data type uniquely identifies a mutex object. | |
238 | @end deftp | |
239 | ||
240 | The ISO C standard defines several types of mutexes. They are | |
241 | represented by the following symbolic constants: | |
242 | ||
243 | @vtable @code | |
244 | @item mtx_plain | |
245 | @standards{C11, threads.h} | |
246 | A mutex that does not support timeout, or test and return. | |
247 | ||
248 | @item mtx_recursive | |
249 | @standards{C11, threads.h} | |
250 | A mutex that supports recursive locking, which means that the owning | |
251 | thread can lock it more than once without causing deadlock. | |
252 | ||
253 | @item mtx_timed | |
254 | @standards{C11, threads.h} | |
255 | A mutex that supports timeout. | |
256 | @end vtable | |
257 | ||
258 | The following functions are used for working with mutexes: | |
259 | ||
260 | @deftypefun int mtx_init (mtx_t *@var{mutex}, int @var{type}) | |
261 | @standards{C11, threads.h} | |
262 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} | |
263 | @code{mtx_init} creates a new mutex object with type @var{type}. The | |
264 | object pointed to by @var{mutex} is set to the identifier of the newly | |
265 | created mutex. | |
266 | ||
267 | Not all combinations of mutex types are valid for the @code{type} | |
268 | argument. Valid uses of mutex types for the @code{type} argument are: | |
269 | ||
270 | @table @code | |
271 | @item mtx_plain | |
272 | A non-recursive mutex that does not support timeout. | |
273 | ||
274 | @item mtx_timed | |
275 | A non-recursive mutex that does support timeout. | |
276 | ||
277 | @item mtx_plain | mtx_recursive | |
278 | A recursive mutex that does not support timeout. | |
279 | ||
280 | @item mtx_timed | mtx_recursive | |
281 | A recursive mutex that does support timeout. | |
282 | @end table | |
283 | ||
284 | This function returns either @code{thrd_success} or @code{thrd_error}. | |
285 | @end deftypefun | |
286 | ||
287 | @deftypefun int mtx_lock (mtx_t *@var{mutex}) | |
288 | @standards{C11, threads.h} | |
289 | @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} | |
290 | @code{mtx_lock} blocks the current thread until the mutex pointed to | |
291 | by @var{mutex} is locked. The behavior is undefined if the current | |
292 | thread has already locked the mutex and the mutex is not recursive. | |
293 | ||
294 | Prior calls to @code{mtx_unlock} on the same mutex synchronize-with | |
295 | this operation (if this operation succeeds), and all lock/unlock | |
296 | operations on any given mutex form a single total order (similar to | |
297 | the modification order of an atomic). | |
298 | ||
299 | This function returns either @code{thrd_success} or @code{thrd_error}. | |
300 | @end deftypefun | |
301 | ||
302 | @deftypefun int mtx_timedlock (mtx_t *restrict @var{mutex}, const struct timespec *restrict @var{time_point}) | |
303 | @standards{C11, threads.h} | |
304 | @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} | |
305 | @code{mtx_timedlock} blocks the current thread until the mutex pointed | |
306 | to by @var{mutex} is locked or until the calendar time pointed to by | |
307 | @var{time_point} has been reached. Since this function takes an | |
308 | absolute time, if a duration is required, the calendar time must be | |
309 | calculated manually. @xref{Time Basics}, and @ref{Calendar Time}. | |
310 | ||
311 | If the current thread has already locked the mutex and the mutex is | |
312 | not recursive, or if the mutex does not support timeout, the behavior | |
313 | of this function is undefined. | |
314 | ||
315 | Prior calls to @code{mtx_unlock} on the same mutex synchronize-with | |
316 | this operation (if this operation succeeds), and all lock/unlock | |
317 | operations on any given mutex form a single total order (similar to | |
318 | the modification order of an atomic). | |
319 | ||
320 | This function returns either @code{thrd_success} or @code{thrd_error}. | |
321 | @end deftypefun | |
322 | ||
323 | @deftypefun int mtx_trylock (mtx_t *@var{mutex}) | |
324 | @standards{C11, threads.h} | |
325 | @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} | |
326 | @code{mtx_trylock} tries to lock the mutex pointed to by @var{mutex} | |
327 | without blocking. It returns immediately if the mutex is already | |
328 | locked. | |
329 | ||
330 | Prior calls to @code{mtx_unlock} on the same mutex synchronize-with | |
331 | this operation (if this operation succeeds), and all lock/unlock | |
332 | operations on any given mutex form a single total order (similar to | |
333 | the modification order of an atomic). | |
334 | ||
335 | This function returns @code{thrd_success} if the lock was obtained, | |
336 | @code{thrd_busy} if the mutex is already locked, and @code{thrd_error} | |
337 | on failure. | |
338 | @end deftypefun | |
339 | ||
340 | @deftypefun int mtx_unlock (mtx_t *@var{mutex}) | |
341 | @standards{C11, threads.h} | |
342 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} | |
343 | @code{mtx_unlock} unlocks the mutex pointed to by @var{mutex}. The | |
344 | behavior is undefined if the mutex is not locked by the calling | |
345 | thread. | |
346 | ||
347 | This function synchronizes-with subsequent @code{mtx_lock}, | |
348 | @code{mtx_trylock}, and @code{mtx_timedlock} calls on the same mutex. | |
349 | All lock/unlock operations on any given mutex form a single total | |
350 | order (similar to the modification order of an atomic). | |
351 | ||
352 | This function returns either @code{thrd_success} or @code{thrd_error}. | |
353 | @end deftypefun | |
354 | ||
355 | @deftypefun void mtx_destroy (mtx_t *@var{mutex}) | |
356 | @standards{C11, threads.h} | |
357 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} | |
358 | @code{mtx_destroy} destroys the mutex pointed to by @var{mutex}. If | |
359 | there are any threads waiting on the mutex, the behavior is | |
360 | undefined. | |
361 | @end deftypefun | |
362 | ||
363 | ||
364 | @node ISO C Condition Variables | |
365 | @subsection Condition Variables | |
366 | @cindex condvar | |
367 | @cindex condition variables | |
368 | ||
369 | Mutexes are not the only synchronization mechanisms available. For | |
370 | some more complex tasks, @theglibc{} also implements @dfn{condition | |
371 | variables}, which allow the programmer to think at a higher level when | |
372 | solving complex synchronization problems. They are used to | |
373 | synchronize threads waiting on a certain condition to happen. | |
374 | ||
375 | The fundamental data type for condition variables is the @code{cnd_t}: | |
376 | ||
377 | @deftp {Data Type} cnd_t | |
378 | @standards{C11, threads.h} | |
379 | The @code{cnd_t} uniquely identifies a condition variable object. | |
380 | @end deftp | |
381 | ||
382 | The following functions are used for working with condition variables: | |
383 | ||
384 | @deftypefun int cnd_init (cnd_t *@var{cond}) | |
385 | @standards{C11, threads.h} | |
386 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} | |
387 | @code{cnd_init} initializes a new condition variable, identified by | |
388 | @var{cond}. | |
389 | ||
390 | This function may return @code{thrd_success}, @code{thrd_nomem}, or | |
391 | @code{thrd_error}. | |
392 | @end deftypefun | |
393 | ||
394 | @deftypefun int cnd_signal (cnd_t *@var{cond}) | |
395 | @standards{C11, threads.h} | |
396 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} | |
397 | @code{cnd_signal} unblocks one thread that is currently waiting on the | |
398 | condition variable pointed to by @var{cond}. If a thread is | |
399 | successfully unblocked, this function returns @code{thrd_success}. If | |
400 | no threads are blocked, this function does nothing and returns | |
401 | @code{thrd_success}. Otherwise, this function returns | |
402 | @code{thrd_error}. | |
403 | @end deftypefun | |
404 | ||
405 | @deftypefun int cnd_broadcast (cnd_t *@var{cond}) | |
406 | @standards{C11, threads.h} | |
407 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} | |
408 | @code{cnd_broadcast} unblocks all the threads that are currently | |
409 | waiting on the condition variable pointed to by @var{cond}. This | |
410 | function returns @code{thrd_success} on success. If no threads are | |
411 | blocked, this function does nothing and returns | |
412 | @code{thrd_success}. Otherwise, this function returns | |
413 | @code{thrd_error}. | |
414 | @end deftypefun | |
415 | ||
416 | @deftypefun int cnd_wait (cnd_t *@var{cond}, mtx_t *@var{mutex}) | |
417 | @standards{C11, threads.h} | |
418 | @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} | |
419 | @code{cnd_wait} atomically unlocks the mutex pointed to by @var{mutex} | |
420 | and blocks on the condition variable pointed to by @var{cond} until | |
421 | the thread is signaled by @code{cnd_signal} or @code{cnd_broadcast}. | |
422 | The mutex is locked again before the function returns. | |
423 | ||
424 | This function returns either @code{thrd_success} or @code{thrd_error}. | |
425 | @end deftypefun | |
426 | ||
427 | @deftypefun int cnd_timedwait (cnd_t *restrict @var{cond}, mtx_t *restrict @var{mutex}, const struct timespec *restrict @var{time_point}) | |
428 | @standards{C11, threads.h} | |
429 | @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} | |
430 | @code{cnd_timedwait} atomically unlocks the mutex pointed to by | |
431 | @var{mutex} and blocks on the condition variable pointed to by | |
432 | @var{cond} until the thread is signaled by @code{cnd_signal} or | |
433 | @code{cnd_broadcast}, or until the calendar time pointed to by | |
434 | @var{time_point} has been reached. The mutex is locked again before | |
435 | the function returns. | |
436 | ||
437 | As for @code{mtx_timedlock}, since this function takes an absolute | |
438 | time, if a duration is required, the calendar time must be calculated | |
439 | manually. @xref{Time Basics}, and @ref{Calendar Time}. | |
440 | ||
441 | This function may return @code{thrd_success}, @code{thrd_nomem}, or | |
442 | @code{thrd_error}. | |
443 | @end deftypefun | |
444 | ||
445 | @deftypefun void cnd_destroy (cnd_t *@var{cond}) | |
446 | @standards{C11, threads.h} | |
447 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} | |
448 | @code{cnd_destroy} destroys the condition variable pointed to by | |
449 | @var{cond}. If there are threads waiting on @var{cond}, the behavior | |
450 | is undefined. | |
451 | @end deftypefun | |
452 | ||
453 | ||
454 | @node ISO C Thread-local Storage | |
455 | @subsection Thread-local Storage | |
456 | @cindex thread-local storage | |
457 | ||
458 | @Theglibc{} implements functions to provide @dfn{thread-local | |
459 | storage}, a mechanism by which variables can be defined to have unique | |
460 | per-thread storage, lifetimes that match the thread lifetime, and | |
461 | destructors that cleanup the unique per-thread storage. | |
462 | ||
463 | Several data types and macros exist for working with thread-local | |
464 | storage: | |
465 | ||
466 | @deftp {Data Type} tss_t | |
467 | @standards{C11, threads.h} | |
468 | The @code{tss_t} data type identifies a thread-specific storage | |
469 | object. Even if shared, every thread will have its own instance of | |
470 | the variable, with different values. | |
471 | @end deftp | |
472 | ||
473 | @deftp {Data Type} tss_dtor_t | |
474 | @standards{C11, threads.h} | |
475 | The @code{tss_dtor_t} is a function pointer of type @code{void (*) | |
476 | (void *)}, to be used as a thread-specific storage destructor. The | |
477 | function will be called when the current thread calls @code{thrd_exit} | |
478 | (but never when calling @code{tss_delete} or @code{exit}). | |
479 | @end deftp | |
480 | ||
481 | @defvr Macro thread_local | |
482 | @standards{C11, threads.h} | |
483 | @code{thread_local} is used to mark a variable with thread storage | |
484 | duration, which means it is created when the thread starts and cleaned | |
485 | up when the thread ends. | |
486 | ||
487 | @emph{Note:} For C++, C++11 or later is required to use the | |
488 | @code{thread_local} keyword. | |
489 | @end defvr | |
490 | ||
491 | @defvr Macro TSS_DTOR_ITERATIONS | |
492 | @standards{C11, threads.h} | |
493 | @code{TSS_DTOR_ITERATIONS} is an integer constant expression | |
494 | representing the maximum number of iterations over all thread-local | |
495 | destructors at the time of thread termination. This value provides a | |
496 | bounded limit to the destruction of thread-local storage; e.g., | |
497 | consider a destructor that creates more thread-local storage. | |
498 | @end defvr | |
499 | ||
500 | The following functions are used to manage thread-local storage: | |
501 | ||
502 | @deftypefun int tss_create (tss_t *@var{tss_key}, tss_dtor_t @var{destructor}) | |
503 | @standards{C11, threads.h} | |
504 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} | |
505 | @code{tss_create} creates a new thread-specific storage key and stores | |
506 | it in the object pointed to by @var{tss_key}. Although the same key | |
507 | value may be used by different threads, the values bound to the key by | |
508 | @code{tss_set} are maintained on a per-thread basis and persist for | |
509 | the life of the calling thread. | |
510 | ||
511 | If @code{destructor} is not NULL, a destructor function will be set, | |
512 | and called when the thread finishes its execution by calling | |
513 | @code{thrd_exit}. | |
514 | ||
515 | This function returns @code{thrd_success} if @code{tss_key} is | |
516 | successfully set to a unique value for the thread; otherwise, | |
517 | @code{thrd_error} is returned and the value of @code{tss_key} is | |
518 | undefined. | |
519 | @end deftypefun | |
520 | ||
521 | @deftypefun int tss_set (tss_t @var{tss_key}, void *@var{val}) | |
522 | @standards{C11, threads.h} | |
523 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} | |
524 | @code{tss_set} sets the value of the thread-specific storage | |
525 | identified by @var{tss_key} for the current thread to @var{val}. | |
526 | Different threads may set different values to the same key. | |
527 | ||
528 | This function returns either @code{thrd_success} or @code{thrd_error}. | |
529 | @end deftypefun | |
530 | ||
531 | @deftypefun {void *} tss_get (tss_t @var{tss_key}) | |
532 | @standards{C11, threads.h} | |
533 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} | |
534 | @code{tss_get} returns the value identified by @var{tss_key} held in | |
535 | thread-specific storage for the current thread. Different threads may | |
536 | get different values identified by the same key. On failure, | |
537 | @code{tss_get} returns zero. | |
538 | @end deftypefun | |
539 | ||
540 | @deftypefun void tss_delete (tss_t @var{tss_key}) | |
541 | @standards{C11, threads.h} | |
542 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} | |
543 | @code{tss_delete} destroys the thread-specific storage identified by | |
544 | @var{tss_key}. | |
545 | @end deftypefun | |
546 | ||
547 | ||
0409959c | 548 | @node POSIX Threads |
9d0a979e | 549 | @section POSIX Threads |
bcda9880 | 550 | @cindex pthreads |
0409959c | 551 | |
9d0a979e | 552 | This section describes the @glibcadj{} POSIX Threads implementation. |
0409959c SP |
553 | |
554 | @menu | |
555 | * Thread-specific Data:: Support for creating and | |
556 | managing thread-specific data | |
adf23d2c SP |
557 | * Non-POSIX Extensions:: Additional functions to extend |
558 | POSIX Thread functionality | |
0409959c SP |
559 | @end menu |
560 | ||
561 | @node Thread-specific Data | |
9d0a979e | 562 | @subsection Thread-specific Data |
0409959c SP |
563 | |
564 | The @glibcadj{} implements functions to allow users to create and manage | |
565 | data specific to a thread. Such data may be destroyed at thread exit, | |
566 | if a destructor is provided. The following functions are defined: | |
567 | ||
909e12ad | 568 | @deftypefun int pthread_key_create (pthread_key_t *@var{key}, void (*@var{destructor})(void*)) |
d08a7e4c | 569 | @standards{POSIX, pthread.h} |
909e12ad AO |
570 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
571 | @c pthread_key_create ok | |
572 | @c KEY_UNUSED ok | |
573 | @c KEY_USABLE ok | |
0409959c SP |
574 | Create a thread-specific data key for the calling thread, referenced by |
575 | @var{key}. | |
576 | ||
577 | Objects declared with the C++11 @code{thread_local} keyword are destroyed | |
578 | before thread-specific data, so they should not be used in thread-specific | |
579 | data destructors or even as members of the thread-specific data, since the | |
580 | latter is passed as an argument to the destructor function. | |
909e12ad | 581 | @end deftypefun |
0409959c | 582 | |
909e12ad | 583 | @deftypefun int pthread_key_delete (pthread_key_t @var{key}) |
d08a7e4c | 584 | @standards{POSIX, pthread.h} |
909e12ad AO |
585 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
586 | @c pthread_key_delete ok | |
587 | @c This uses atomic compare and exchange to increment the seq number | |
588 | @c after testing it's not a KEY_UNUSED seq number. | |
589 | @c KEY_UNUSED dup ok | |
0409959c SP |
590 | Destroy the thread-specific data @var{key} in the calling thread. The |
591 | destructor for the thread-specific data is not called during destruction, nor | |
592 | is it called during thread exit. | |
909e12ad | 593 | @end deftypefun |
0409959c | 594 | |
909e12ad | 595 | @deftypefun void *pthread_getspecific (pthread_key_t @var{key}) |
d08a7e4c | 596 | @standards{POSIX, pthread.h} |
909e12ad AO |
597 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
598 | @c pthread_getspecific ok | |
0409959c SP |
599 | Return the thread-specific data associated with @var{key} in the calling |
600 | thread. | |
909e12ad | 601 | @end deftypefun |
0409959c | 602 | |
909e12ad | 603 | @deftypefun int pthread_setspecific (pthread_key_t @var{key}, const void *@var{value}) |
d08a7e4c | 604 | @standards{POSIX, pthread.h} |
909e12ad AO |
605 | @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acucorrupt{} @acsmem{}}} |
606 | @c pthread_setspecific @asucorrupt @ascuheap @acucorrupt @acsmem | |
607 | @c a level2 block may be allocated by a signal handler after | |
608 | @c another call already made a decision to allocate it, thus losing | |
609 | @c the allocated value. the seq number is updated before the | |
610 | @c value, which might cause an earlier-generation value to seem | |
611 | @c current if setspecific is cancelled or interrupted by a signal | |
612 | @c KEY_UNUSED ok | |
613 | @c calloc dup @ascuheap @acsmem | |
0409959c | 614 | Associate the thread-specific @var{value} with @var{key} in the calling thread. |
909e12ad | 615 | @end deftypefun |
0409959c | 616 | |
adf23d2c SP |
617 | |
618 | @node Non-POSIX Extensions | |
9d0a979e | 619 | @subsection Non-POSIX Extensions |
adf23d2c SP |
620 | |
621 | In addition to implementing the POSIX API for threads, @theglibc{} provides | |
622 | additional functions and interfaces to provide functionality not specified in | |
623 | the standard. | |
624 | ||
625 | @menu | |
626 | * Default Thread Attributes:: Setting default attributes for | |
627 | threads in a process. | |
628 | @end menu | |
629 | ||
630 | @node Default Thread Attributes | |
9d0a979e | 631 | @subsubsection Setting Process-wide defaults for thread attributes |
adf23d2c SP |
632 | |
633 | @Theglibc{} provides non-standard API functions to set and get the default | |
634 | attributes used in the creation of threads in a process. | |
635 | ||
636 | @deftypefun int pthread_getattr_default_np (pthread_attr_t *@var{attr}) | |
d08a7e4c | 637 | @standards{GNU, pthread.h} |
5da2c93d AO |
638 | @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} |
639 | @c Takes lock around read from default_pthread_attr. | |
adf23d2c SP |
640 | Get the default attribute values and set @var{attr} to match. This |
641 | function returns @math{0} on success and a non-zero error code on | |
642 | failure. | |
643 | @end deftypefun | |
644 | ||
e16d221c | 645 | @deftypefun int pthread_setattr_default_np (pthread_attr_t *@var{attr}) |
d08a7e4c | 646 | @standards{GNU, pthread.h} |
5da2c93d AO |
647 | @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{}}} |
648 | @c pthread_setattr_default_np @ascuheap @asulock @aculock @acsmem | |
649 | @c check_sched_policy_attr ok | |
650 | @c check_sched_priority_attr ok | |
651 | @c sched_get_priority_min dup ok | |
652 | @c sched_get_priority_max dup ok | |
5da2c93d AO |
653 | @c check_stacksize_attr ok |
654 | @c lll_lock @asulock @aculock | |
655 | @c free dup @ascuheap @acsmem | |
656 | @c realloc dup @ascuheap @acsmem | |
657 | @c memcpy dup ok | |
658 | @c lll_unlock @asulock @aculock | |
adf23d2c SP |
659 | Set the default attribute values to match the values in @var{attr}. The |
660 | function returns @math{0} on success and a non-zero error code on failure. | |
661 | The following error codes are defined for this function: | |
662 | ||
663 | @table @code | |
664 | @item EINVAL | |
665 | At least one of the values in @var{attr} does not qualify as valid for the | |
666 | attributes or the stack address is set in the attribute. | |
667 | @item ENOMEM | |
668 | The system does not have sufficient memory. | |
669 | @end table | |
670 | @end deftypefun | |
5da2c93d AO |
671 | |
672 | @c FIXME these are undocumented: | |
673 | @c pthread_atfork | |
674 | @c pthread_attr_destroy | |
675 | @c pthread_attr_getaffinity_np | |
676 | @c pthread_attr_getdetachstate | |
677 | @c pthread_attr_getguardsize | |
678 | @c pthread_attr_getinheritsched | |
679 | @c pthread_attr_getschedparam | |
680 | @c pthread_attr_getschedpolicy | |
681 | @c pthread_attr_getscope | |
682 | @c pthread_attr_getstack | |
683 | @c pthread_attr_getstackaddr | |
684 | @c pthread_attr_getstacksize | |
685 | @c pthread_attr_init | |
686 | @c pthread_attr_setaffinity_np | |
687 | @c pthread_attr_setdetachstate | |
688 | @c pthread_attr_setguardsize | |
689 | @c pthread_attr_setinheritsched | |
690 | @c pthread_attr_setschedparam | |
691 | @c pthread_attr_setschedpolicy | |
692 | @c pthread_attr_setscope | |
693 | @c pthread_attr_setstack | |
694 | @c pthread_attr_setstackaddr | |
695 | @c pthread_attr_setstacksize | |
696 | @c pthread_barrierattr_destroy | |
697 | @c pthread_barrierattr_getpshared | |
698 | @c pthread_barrierattr_init | |
699 | @c pthread_barrierattr_setpshared | |
700 | @c pthread_barrier_destroy | |
701 | @c pthread_barrier_init | |
702 | @c pthread_barrier_wait | |
703 | @c pthread_cancel | |
704 | @c pthread_cleanup_push | |
705 | @c pthread_cleanup_pop | |
706 | @c pthread_condattr_destroy | |
707 | @c pthread_condattr_getclock | |
708 | @c pthread_condattr_getpshared | |
709 | @c pthread_condattr_init | |
710 | @c pthread_condattr_setclock | |
711 | @c pthread_condattr_setpshared | |
712 | @c pthread_cond_broadcast | |
713 | @c pthread_cond_destroy | |
714 | @c pthread_cond_init | |
715 | @c pthread_cond_signal | |
716 | @c pthread_cond_timedwait | |
717 | @c pthread_cond_wait | |
718 | @c pthread_create | |
719 | @c pthread_detach | |
720 | @c pthread_equal | |
721 | @c pthread_exit | |
722 | @c pthread_getaffinity_np | |
723 | @c pthread_getattr_np | |
724 | @c pthread_getconcurrency | |
725 | @c pthread_getcpuclockid | |
726 | @c pthread_getname_np | |
727 | @c pthread_getschedparam | |
728 | @c pthread_join | |
729 | @c pthread_kill | |
730 | @c pthread_kill_other_threads_np | |
731 | @c pthread_mutexattr_destroy | |
732 | @c pthread_mutexattr_getkind_np | |
733 | @c pthread_mutexattr_getprioceiling | |
734 | @c pthread_mutexattr_getprotocol | |
735 | @c pthread_mutexattr_getpshared | |
736 | @c pthread_mutexattr_getrobust | |
737 | @c pthread_mutexattr_getrobust_np | |
738 | @c pthread_mutexattr_gettype | |
739 | @c pthread_mutexattr_init | |
740 | @c pthread_mutexattr_setkind_np | |
741 | @c pthread_mutexattr_setprioceiling | |
742 | @c pthread_mutexattr_setprotocol | |
743 | @c pthread_mutexattr_setpshared | |
744 | @c pthread_mutexattr_setrobust | |
745 | @c pthread_mutexattr_setrobust_np | |
746 | @c pthread_mutexattr_settype | |
747 | @c pthread_mutex_consistent | |
748 | @c pthread_mutex_consistent_np | |
749 | @c pthread_mutex_destroy | |
750 | @c pthread_mutex_getprioceiling | |
751 | @c pthread_mutex_init | |
752 | @c pthread_mutex_lock | |
753 | @c pthread_mutex_setprioceiling | |
754 | @c pthread_mutex_timedlock | |
755 | @c pthread_mutex_trylock | |
756 | @c pthread_mutex_unlock | |
757 | @c pthread_once | |
758 | @c pthread_rwlockattr_destroy | |
759 | @c pthread_rwlockattr_getkind_np | |
760 | @c pthread_rwlockattr_getpshared | |
761 | @c pthread_rwlockattr_init | |
762 | @c pthread_rwlockattr_setkind_np | |
763 | @c pthread_rwlockattr_setpshared | |
764 | @c pthread_rwlock_destroy | |
765 | @c pthread_rwlock_init | |
766 | @c pthread_rwlock_rdlock | |
767 | @c pthread_rwlock_timedrdlock | |
768 | @c pthread_rwlock_timedwrlock | |
769 | @c pthread_rwlock_tryrdlock | |
770 | @c pthread_rwlock_trywrlock | |
771 | @c pthread_rwlock_unlock | |
772 | @c pthread_rwlock_wrlock | |
773 | @c pthread_self | |
774 | @c pthread_setaffinity_np | |
775 | @c pthread_setcancelstate | |
776 | @c pthread_setcanceltype | |
777 | @c pthread_setconcurrency | |
778 | @c pthread_setname_np | |
779 | @c pthread_setschedparam | |
780 | @c pthread_setschedprio | |
781 | @c pthread_sigmask | |
782 | @c pthread_sigqueue | |
783 | @c pthread_spin_destroy | |
784 | @c pthread_spin_init | |
785 | @c pthread_spin_lock | |
786 | @c pthread_spin_trylock | |
787 | @c pthread_spin_unlock | |
788 | @c pthread_testcancel | |
789 | @c pthread_timedjoin_np | |
790 | @c pthread_tryjoin_np | |
791 | @c pthread_yield |