]>
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 | |
62193c4a | 131 | @ref{Time Types}. |
9d0a979e RJ |
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. | |
27bf5e95 | 628 | * Initial Thread Signal Mask:: Setting the initial mask of threads. |
5b9b177b FW |
629 | * Waiting with Explicit Clocks:: Functions for waiting with an |
630 | explicit clock specification. | |
01ffa600 | 631 | * Single-Threaded:: Detecting single-threaded execution. |
adf23d2c SP |
632 | @end menu |
633 | ||
634 | @node Default Thread Attributes | |
9d0a979e | 635 | @subsubsection Setting Process-wide defaults for thread attributes |
adf23d2c SP |
636 | |
637 | @Theglibc{} provides non-standard API functions to set and get the default | |
638 | attributes used in the creation of threads in a process. | |
639 | ||
640 | @deftypefun int pthread_getattr_default_np (pthread_attr_t *@var{attr}) | |
d08a7e4c | 641 | @standards{GNU, pthread.h} |
5da2c93d AO |
642 | @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} |
643 | @c Takes lock around read from default_pthread_attr. | |
adf23d2c SP |
644 | Get the default attribute values and set @var{attr} to match. This |
645 | function returns @math{0} on success and a non-zero error code on | |
646 | failure. | |
647 | @end deftypefun | |
648 | ||
e16d221c | 649 | @deftypefun int pthread_setattr_default_np (pthread_attr_t *@var{attr}) |
d08a7e4c | 650 | @standards{GNU, pthread.h} |
5da2c93d AO |
651 | @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{}}} |
652 | @c pthread_setattr_default_np @ascuheap @asulock @aculock @acsmem | |
653 | @c check_sched_policy_attr ok | |
654 | @c check_sched_priority_attr ok | |
655 | @c sched_get_priority_min dup ok | |
656 | @c sched_get_priority_max dup ok | |
5da2c93d AO |
657 | @c check_stacksize_attr ok |
658 | @c lll_lock @asulock @aculock | |
659 | @c free dup @ascuheap @acsmem | |
660 | @c realloc dup @ascuheap @acsmem | |
661 | @c memcpy dup ok | |
662 | @c lll_unlock @asulock @aculock | |
adf23d2c SP |
663 | Set the default attribute values to match the values in @var{attr}. The |
664 | function returns @math{0} on success and a non-zero error code on failure. | |
665 | The following error codes are defined for this function: | |
666 | ||
667 | @table @code | |
668 | @item EINVAL | |
669 | At least one of the values in @var{attr} does not qualify as valid for the | |
670 | attributes or the stack address is set in the attribute. | |
671 | @item ENOMEM | |
672 | The system does not have sufficient memory. | |
673 | @end table | |
674 | @end deftypefun | |
5da2c93d | 675 | |
27bf5e95 FW |
676 | @node Initial Thread Signal Mask |
677 | @subsubsection Controlling the Initial Signal Mask of a New Thread | |
678 | ||
679 | @Theglibc{} provides a way to specify the initial signal mask of a | |
680 | thread created using @code{pthread_create}, passing a thread attribute | |
681 | object configured for this purpose. | |
682 | ||
683 | @deftypefun int pthread_attr_setsigmask_np (pthread_attr_t *@var{attr}, const sigset_t *@var{sigmask}) | |
684 | @standards{GNU, pthread.h} | |
685 | @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} | |
686 | Change the initial signal mask specified by @var{attr}. If | |
687 | @var{sigmask} is not @code{NULL}, the initial signal mask for new | |
688 | threads created with @var{attr} is set to @code{*@var{sigmask}}. If | |
689 | @var{sigmask} is @code{NULL}, @var{attr} will no longer specify an | |
690 | explicit signal mask, so that the initial signal mask of the new | |
691 | thread is inherited from the thread that calls @code{pthread_create}. | |
692 | ||
693 | This function returns zero on success, and @code{ENOMEM} on memory | |
694 | allocation failure. | |
695 | @end deftypefun | |
696 | ||
697 | @deftypefun int pthread_attr_getsigmask_np (const pthread_attr_t *@var{attr}, sigset_t *@var{sigmask}) | |
698 | @standards{GNU, pthread.h} | |
699 | @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} | |
700 | Retrieve the signal mask stored in @var{attr} and copy it to | |
701 | @code{*@var{sigmask}}. If the signal mask has not been set, return | |
702 | the special constant @code{PTHREAD_ATTR_NO_SIGMASK_NP}, otherwise | |
703 | return zero. | |
704 | ||
705 | @c Move this to the documentation of pthread_getattr_np once it exists. | |
706 | Obtaining the signal mask only works if it has been previously stored | |
707 | by @code{pthread_attr_setsigmask_np}. For example, the | |
708 | @code{pthread_getattr_np} function does not obtain the current signal | |
709 | mask of the specified thread, and @code{pthread_attr_getsigmask_np} | |
710 | will subsequently report the signal mask as unset. | |
711 | @end deftypefun | |
712 | ||
713 | @deftypevr Macro int PTHREAD_ATTR_NO_SIGMASK_NP | |
714 | The special value returned by @code{pthread_attr_setsigmask_np} to | |
715 | indicate that no signal mask has been set for the attribute. | |
716 | @end deftypevr | |
717 | ||
718 | It is possible to create a new thread with a specific signal mask | |
719 | without using these functions. On the thread that calls | |
720 | @code{pthread_create}, the required steps for the general case are: | |
721 | ||
722 | @enumerate 1 | |
723 | @item | |
724 | Mask all signals, and save the old signal mask, using | |
725 | @code{pthread_sigmask}. This ensures that the new thread will be | |
726 | created with all signals masked, so that no signals can be delivered | |
727 | to the thread until the desired signal mask is set. | |
728 | ||
729 | @item | |
730 | Call @code{pthread_create} to create the new thread, passing the | |
731 | desired signal mask to the thread start routine (which could be a | |
732 | wrapper function for the actual thread start routine). It may be | |
733 | necessary to make a copy of the desired signal mask on the heap, so | |
734 | that the life-time of the copy extends to the point when the start | |
735 | routine needs to access the signal mask. | |
736 | ||
737 | @item | |
738 | Restore the thread's signal mask, to the set that was saved in the | |
739 | first step. | |
740 | @end enumerate | |
741 | ||
742 | The start routine for the created thread needs to locate the desired | |
743 | signal mask and use @code{pthread_sigmask} to apply it to the thread. | |
744 | If the signal mask was copied to a heap allocation, the copy should be | |
745 | freed. | |
746 | ||
5b9b177b FW |
747 | @node Waiting with Explicit Clocks |
748 | @subsubsection Functions for Waiting According to a Specific Clock | |
749 | ||
750 | @Theglibc{} provides several waiting functions that expect an explicit | |
751 | @code{clockid_t} argument. | |
752 | ||
6615f779 MC |
753 | @comment semaphore.h |
754 | @comment POSIX-proposed | |
755 | @deftypefun int sem_clockwait (sem_t *@var{sem}, clockid_t @var{clockid}, | |
756 | const struct timespec *@var{abstime}) | |
757 | Behaves like @code{sem_timedwait} except the time @var{abstime} is measured | |
758 | against the clock specified by @var{clockid} rather than | |
759 | @code{CLOCK_REALTIME}. Currently, @var{clockid} must be either | |
760 | @code{CLOCK_MONOTONIC} or @code{CLOCK_REALTIME}. | |
761 | @end deftypefun | |
762 | ||
afe4de7d MC |
763 | @comment pthread.h |
764 | @comment POSIX-proposed | |
765 | @deftypefun int pthread_cond_clockwait (pthread_cond_t *@var{cond}, pthread_mutex_t *@var{mutex}, | |
766 | clockid_t @var{clockid}, const struct timespec *@var{abstime}) | |
767 | @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} | |
768 | @c If exactly the same function with arguments is called from a signal | |
769 | @c handler that interrupts between the mutex unlock and sleep then it | |
770 | @c will unlock the mutex twice resulting in undefined behaviour. Keep | |
771 | @c in mind that the unlock and sleep are only atomic with respect to other | |
772 | @c threads (really a happens-after relationship for pthread_cond_broadcast | |
773 | @c and pthread_cond_signal). | |
774 | @c In the AC case we would cancel the thread and the mutex would remain | |
775 | @c locked and we can't recover from that. | |
776 | Behaves like @code{pthread_cond_timedwait} except the time @var{abstime} is | |
777 | measured against the clock specified by @var{clockid} rather than the clock | |
778 | specified or defaulted when @code{pthread_cond_init} was called. Currently, | |
779 | @var{clockid} must be either @code{CLOCK_MONOTONIC} or | |
780 | @code{CLOCK_REALTIME}. | |
781 | @end deftypefun | |
782 | ||
e996fa72 MC |
783 | @comment pthread.h |
784 | @comment POSIX-proposed | |
785 | @deftypefun int pthread_rwlock_clockrdlock (pthread_rwlock_t *@var{rwlock}, | |
786 | clockid_t @var{clockid}, | |
787 | const struct timespec *@var{abstime}) | |
788 | ||
789 | @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} | |
790 | Behaves like @code{pthread_rwlock_timedrdlock} except the time | |
791 | @var{abstime} is measured against the clock specified by @var{clockid} | |
792 | rather than @code{CLOCK_REALTIME}. Currently, @var{clockid} must be either | |
793 | @code{CLOCK_MONOTONIC} or @code{CLOCK_REALTIME}, otherwise @code{EINVAL} is | |
794 | returned. | |
795 | @end deftypefun | |
796 | ||
797 | @comment pthread.h | |
798 | @comment POSIX-proposed | |
799 | @deftypefun int pthread_rwlock_clockwrlock (pthread_rwlock_t *@var{rwlock}, | |
800 | clockid_t @var{clockid}, | |
801 | const struct timespec *@var{abstime}) | |
802 | ||
803 | @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} | |
804 | Behaves like @code{pthread_rwlock_timedwrlock} except the time | |
805 | @var{abstime} is measured against the clock specified by @var{clockid} | |
806 | rather than @code{CLOCK_REALTIME}. Currently, @var{clockid} must be either | |
807 | @code{CLOCK_MONOTONIC} or @code{CLOCK_REALTIME}, otherwise @code{EINVAL} is | |
808 | returned. | |
809 | @end deftypefun | |
810 | ||
893bbdd0 MC |
811 | @comment pthread.h |
812 | @comment GNU extension | |
813 | @deftypefun int pthread_tryjoin_np (pthread_t *@var{thread}, | |
814 | void **@var{thread_return}) | |
815 | @standards{GNU, pthread.h} | |
816 | @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} | |
817 | Behaves like @code{pthread_join} except that it will return @code{EBUSY} | |
818 | immediately if the thread specified by @var{thread} has not yet terminated. | |
819 | @end deftypefun | |
820 | ||
821 | @comment pthread.h | |
822 | @comment GNU extension | |
823 | @deftypefun int pthread_timedjoin_np (pthread_t *@var{thread}, | |
824 | void **@var{thread_return}, | |
825 | const struct timespec *@var{abstime}) | |
826 | @standards{GNU, pthread.h} | |
827 | @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} | |
828 | Behaves like @code{pthread_tryjoin_np} except that it will block until the | |
829 | absolute time @var{abstime} measured against @code{CLOCK_REALTIME} is | |
830 | reached if the thread has not terminated by that time and return | |
831 | @code{EBUSY}. If @var{abstime} is equal to @code{NULL} then the function | |
832 | will wait forever in the same way as @code{pthread_join}. | |
833 | @end deftypefun | |
834 | ||
69ca4b54 MC |
835 | @comment pthread.h |
836 | @comment GNU extension | |
837 | @deftypefun int pthread_clockjoin_np (pthread_t *@var{thread}, | |
838 | void **@var{thread_return}, | |
839 | clockid_t @var{clockid}, | |
840 | const struct timespec *@var{abstime}) | |
841 | @standards{GNU, pthread.h} | |
842 | @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} | |
3ef5e118 | 843 | Behaves like @code{pthread_timedjoin_np} except that the absolute time in |
69ca4b54 | 844 | @var{abstime} is measured against the clock specified by @var{clockid}. |
b4c34468 AZ |
845 | Currently, @var{clockid} must be either @code{CLOCK_MONOTONIC} or |
846 | @code{CLOCK_REALTIME}. | |
69ca4b54 MC |
847 | @end deftypefun |
848 | ||
01ffa600 FW |
849 | @node Single-Threaded |
850 | @subsubsection Detecting Single-Threaded Execution | |
851 | ||
852 | Multi-threaded programs require synchronization among threads. This | |
853 | synchronization can be costly even if there is just a single thread | |
854 | and no data is shared between multiple processors. @Theglibc{} offers | |
855 | an interface to detect whether the process is in single-threaded mode. | |
856 | Applications can use this information to avoid synchronization, for | |
857 | example by using regular instructions to load and store memory instead | |
858 | of atomic instructions, or using relaxed memory ordering instead of | |
859 | stronger memory ordering. | |
860 | ||
861 | @deftypevar char __libc_single_threaded | |
862 | @standards{GNU, sys/single_threaded.h} | |
863 | This variable is non-zero if the current process is definitely | |
864 | single-threaded. If it is zero, the process may be multi-threaded, | |
865 | or @theglibc{} cannot determine at this point of the program execution | |
866 | whether the process is single-threaded or not. | |
867 | ||
868 | Applications must never write to this variable. | |
869 | @end deftypevar | |
870 | ||
871 | Most applications should perform the same actions whether or not | |
872 | @code{__libc_single_threaded} is true, except with less | |
873 | synchronization. If this rule is followed, a process that | |
874 | subsequently becomes multi-threaded is already in a consistent state. | |
875 | For example, in order to increment a reference count, the following | |
876 | code can be used: | |
877 | ||
878 | @smallexample | |
879 | if (__libc_single_threaded) | |
880 | atomic_fetch_add (&reference_count, 1, memory_order_relaxed); | |
881 | else | |
882 | atomic_fetch_add (&reference_count, 1, memory_order_acq_rel); | |
883 | @end smallexample | |
884 | ||
885 | @c Note: No memory order on __libc_single_threaded. The | |
886 | @c implementation must ensure that exit of the critical | |
887 | @c (second-to-last) thread happens-before setting | |
888 | @c __libc_single_threaded to true. Otherwise, acquire MO might be | |
889 | @c needed for reading the variable in some scenarios, and that would | |
890 | @c completely defeat its purpose. | |
891 | ||
892 | This still requires some form of synchronization on the | |
893 | single-threaded branch, so it can be beneficial not to declare the | |
894 | reference count as @code{_Atomic}, and use the GCC @code{__atomic} | |
895 | built-ins. @xref{__atomic Builtins,, Built-in Functions for Memory | |
896 | Model Aware Atomic Operations, gcc, Using the GNU Compiler Collection | |
897 | (GCC)}. Then the code to increment a reference count looks like this: | |
898 | ||
899 | @smallexample | |
900 | if (__libc_single_threaded) | |
5bb2e530 | 901 | ++reference_count; |
01ffa600 FW |
902 | else |
903 | __atomic_fetch_add (&reference_count, 1, __ATOMIC_ACQ_REL); | |
904 | @end smallexample | |
905 | ||
906 | (Depending on the data associated with the reference count, it may be | |
907 | possible to use the weaker @code{__ATOMIC_RELAXED} memory ordering on | |
908 | the multi-threaded branch.) | |
909 | ||
910 | Several functions in @theglibc{} can change the value of the | |
911 | @code{__libc_single_threaded} variable. For example, creating new | |
912 | threads using the @code{pthread_create} or @code{thrd_create} function | |
913 | sets the variable to false. This can also happen indirectly, say via | |
914 | a call to @code{dlopen}. Therefore, applications need to make a copy | |
915 | of the value of @code{__libc_single_threaded} if after such a function | |
916 | call, behavior must match the value as it was before the call, like | |
917 | this: | |
918 | ||
919 | @smallexample | |
920 | bool single_threaded = __libc_single_threaded; | |
921 | if (single_threaded) | |
922 | prepare_single_threaded (); | |
923 | else | |
924 | prepare_multi_thread (); | |
925 | ||
926 | void *handle = dlopen (shared_library_name, RTLD_NOW); | |
927 | lookup_symbols (handle); | |
928 | ||
929 | if (single_threaded) | |
930 | cleanup_single_threaded (); | |
931 | else | |
932 | cleanup_multi_thread (); | |
933 | @end smallexample | |
934 | ||
935 | Since the value of @code{__libc_single_threaded} can change from true | |
936 | to false during the execution of the program, it is not useful for | |
937 | selecting optimized function implementations in IFUNC resolvers. | |
938 | ||
939 | Atomic operations can also be used on mappings shared among | |
940 | single-threaded processes. This means that a compiler must not use | |
941 | @code{__libc_single_threaded} to optimize atomic operations, unless it | |
942 | is able to prove that the memory is not shared. | |
943 | ||
944 | @strong{Implementation Note:} The @code{__libc_single_threaded} | |
945 | variable is not declared as @code{volatile} because it is expected | |
946 | that compilers optimize a sequence of single-threaded checks into one | |
947 | check, for example if several reference counts are updated. The | |
948 | current implementation in @theglibc{} does not set the | |
949 | @code{__libc_single_threaded} variable to a true value if a process | |
950 | turns single-threaded again. Future versions of @theglibc{} may do | |
951 | this, but only as the result of function calls which imply an acquire | |
952 | (compiler) barrier. (Some compilers assume that well-known functions | |
953 | such as @code{malloc} do not write to global variables, and setting | |
954 | @code{__libc_single_threaded} would introduce a data race and | |
955 | undefined behavior.) In any case, an application must not write to | |
956 | @code{__libc_single_threaded} even if it has joined the last | |
957 | application-created thread because future versions of @theglibc{} may | |
958 | create background threads after the first thread has been created, and | |
959 | the application has no way of knowning that these threads are present. | |
960 | ||
5da2c93d AO |
961 | @c FIXME these are undocumented: |
962 | @c pthread_atfork | |
963 | @c pthread_attr_destroy | |
964 | @c pthread_attr_getaffinity_np | |
965 | @c pthread_attr_getdetachstate | |
966 | @c pthread_attr_getguardsize | |
967 | @c pthread_attr_getinheritsched | |
968 | @c pthread_attr_getschedparam | |
969 | @c pthread_attr_getschedpolicy | |
970 | @c pthread_attr_getscope | |
971 | @c pthread_attr_getstack | |
972 | @c pthread_attr_getstackaddr | |
973 | @c pthread_attr_getstacksize | |
974 | @c pthread_attr_init | |
975 | @c pthread_attr_setaffinity_np | |
976 | @c pthread_attr_setdetachstate | |
977 | @c pthread_attr_setguardsize | |
978 | @c pthread_attr_setinheritsched | |
979 | @c pthread_attr_setschedparam | |
980 | @c pthread_attr_setschedpolicy | |
981 | @c pthread_attr_setscope | |
982 | @c pthread_attr_setstack | |
983 | @c pthread_attr_setstackaddr | |
984 | @c pthread_attr_setstacksize | |
985 | @c pthread_barrierattr_destroy | |
986 | @c pthread_barrierattr_getpshared | |
987 | @c pthread_barrierattr_init | |
988 | @c pthread_barrierattr_setpshared | |
989 | @c pthread_barrier_destroy | |
990 | @c pthread_barrier_init | |
991 | @c pthread_barrier_wait | |
992 | @c pthread_cancel | |
993 | @c pthread_cleanup_push | |
994 | @c pthread_cleanup_pop | |
995 | @c pthread_condattr_destroy | |
996 | @c pthread_condattr_getclock | |
997 | @c pthread_condattr_getpshared | |
998 | @c pthread_condattr_init | |
999 | @c pthread_condattr_setclock | |
1000 | @c pthread_condattr_setpshared | |
1001 | @c pthread_cond_broadcast | |
1002 | @c pthread_cond_destroy | |
1003 | @c pthread_cond_init | |
1004 | @c pthread_cond_signal | |
1005 | @c pthread_cond_timedwait | |
1006 | @c pthread_cond_wait | |
1007 | @c pthread_create | |
1008 | @c pthread_detach | |
1009 | @c pthread_equal | |
1010 | @c pthread_exit | |
1011 | @c pthread_getaffinity_np | |
1012 | @c pthread_getattr_np | |
1013 | @c pthread_getconcurrency | |
1014 | @c pthread_getcpuclockid | |
1015 | @c pthread_getname_np | |
1016 | @c pthread_getschedparam | |
1017 | @c pthread_join | |
1018 | @c pthread_kill | |
1019 | @c pthread_kill_other_threads_np | |
1020 | @c pthread_mutexattr_destroy | |
1021 | @c pthread_mutexattr_getkind_np | |
1022 | @c pthread_mutexattr_getprioceiling | |
1023 | @c pthread_mutexattr_getprotocol | |
1024 | @c pthread_mutexattr_getpshared | |
1025 | @c pthread_mutexattr_getrobust | |
1026 | @c pthread_mutexattr_getrobust_np | |
1027 | @c pthread_mutexattr_gettype | |
1028 | @c pthread_mutexattr_init | |
1029 | @c pthread_mutexattr_setkind_np | |
1030 | @c pthread_mutexattr_setprioceiling | |
1031 | @c pthread_mutexattr_setprotocol | |
1032 | @c pthread_mutexattr_setpshared | |
1033 | @c pthread_mutexattr_setrobust | |
1034 | @c pthread_mutexattr_setrobust_np | |
1035 | @c pthread_mutexattr_settype | |
1036 | @c pthread_mutex_consistent | |
1037 | @c pthread_mutex_consistent_np | |
1038 | @c pthread_mutex_destroy | |
1039 | @c pthread_mutex_getprioceiling | |
1040 | @c pthread_mutex_init | |
1041 | @c pthread_mutex_lock | |
1042 | @c pthread_mutex_setprioceiling | |
1043 | @c pthread_mutex_timedlock | |
1044 | @c pthread_mutex_trylock | |
1045 | @c pthread_mutex_unlock | |
1046 | @c pthread_once | |
1047 | @c pthread_rwlockattr_destroy | |
1048 | @c pthread_rwlockattr_getkind_np | |
1049 | @c pthread_rwlockattr_getpshared | |
1050 | @c pthread_rwlockattr_init | |
1051 | @c pthread_rwlockattr_setkind_np | |
1052 | @c pthread_rwlockattr_setpshared | |
1053 | @c pthread_rwlock_destroy | |
1054 | @c pthread_rwlock_init | |
1055 | @c pthread_rwlock_rdlock | |
1056 | @c pthread_rwlock_timedrdlock | |
1057 | @c pthread_rwlock_timedwrlock | |
1058 | @c pthread_rwlock_tryrdlock | |
1059 | @c pthread_rwlock_trywrlock | |
1060 | @c pthread_rwlock_unlock | |
1061 | @c pthread_rwlock_wrlock | |
1062 | @c pthread_self | |
1063 | @c pthread_setaffinity_np | |
1064 | @c pthread_setcancelstate | |
1065 | @c pthread_setcanceltype | |
1066 | @c pthread_setconcurrency | |
1067 | @c pthread_setname_np | |
1068 | @c pthread_setschedparam | |
1069 | @c pthread_setschedprio | |
1070 | @c pthread_sigmask | |
1071 | @c pthread_sigqueue | |
1072 | @c pthread_spin_destroy | |
1073 | @c pthread_spin_init | |
1074 | @c pthread_spin_lock | |
1075 | @c pthread_spin_trylock | |
1076 | @c pthread_spin_unlock | |
1077 | @c pthread_testcancel | |
5da2c93d | 1078 | @c pthread_yield |