1@node Threads 2@c @node Threads, Dynamic Linker, Debugging Support, Top 3@c %MENU% Functions, constants, and data types for working with threads 4@chapter Threads 5@cindex threads 6 7This chapter describes functions used for managing threads. 8@Theglibc{} provides two threading implementations: ISO C threads and 9POSIX 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 23This section describes the @glibcadj{} ISO C threads implementation. 24To have a deeper understanding of this API, it is strongly recommended 25to read ISO/IEC 9899:2011, section 7.26, in which ISO C threads were 26originally specified. All types and function prototypes are declared 27in 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 43The ISO C thread specification provides the following enumeration 44constants for return values from functions in the API: 45 46@vtable @code 47@item thrd_timedout 48@standards{C11, threads.h} 49A specified time was reached without acquiring the requested resource, 50usually a mutex or condition variable. 51 52@item thrd_success 53@standards{C11, threads.h} 54The requested operation succeeded. 55 56@item thrd_busy 57@standards{C11, threads.h} 58The requested operation failed because a requested resource is already 59in use. 60 61@item thrd_error 62@standards{C11, threads.h} 63The requested operation failed. 64 65@item thrd_nomem 66@standards{C11, threads.h} 67The requested operation failed because it was unable to allocate 68enough 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 79create and use threads. Additional functionality is provided to control 80the behavior of threads. 81 82The following data types are defined for managing threads: 83 84@deftp {Data Type} thrd_t 85@standards{C11, threads.h} 86A unique object that identifies a thread. 87@end deftp 88 89@deftp {Data Type} thrd_start_t 90@standards{C11, threads.h} 91This 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 93first function that thread will run. 94@end deftp 95 96The 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 103argument to @var{func}. If successful, @var{thr} is set to the new 104thread identifier. 105 106This 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{}} 113This 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 120same thread. If @var{lhs} and @var{rhs} are different threads, this 121function 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 128least until the elapsed time pointed to by @var{time_point} has been 129reached. This function does not take an absolute time, but a duration 130that the thread is required to be blocked. @xref{Time Basics}, and 131@ref{Time Types}. 132 133The thread may wake early if a signal that is not ignored is received. 134In such a case, if @code{remaining} is not NULL, the remaining time 135duration 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 139amount of time in @code{time_point}, @math{-1} if it was interrupted 140by 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 147the 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 154its result code to @var{res}. 155 156If this function is called from a single-threaded process, the call is 157equivalent to calling @code{exit} with @code{EXIT_SUCCESS} 158(@pxref{Normal Termination}). Also note that returning from a 159function 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 167the current control thread. The resources held by the detached thread 168will be freed automatically once the thread exits. The parent thread 169will never be notified by any @var{thr} signal. 170 171Calling @code{thrd_detach} on a thread that was previously detached or 172joined by another thread results in undefined behavior. 173 174This 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 181by @code{thr} finishes execution. If @code{res} is not NULL, the 182result code of the thread is put into the location pointed to by 183@var{res}. The termination of the thread @dfn{synchronizes-with} the 184completion of this function, meaning both threads have arrived at a 185common point in their execution. 186 187Calling @code{thrd_join} on a thread that was previously detached or 188joined by another thread results in undefined behavior. 189 190This 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 199In order to guarantee single access to a function, @theglibc{} 200implements a @dfn{call once function} to ensure a function is only 201called once in the presence of multiple, potentially calling threads. 202 203@deftp {Data Type} once_flag 204@standards{C11, threads.h} 205A 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} 210This 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 217invoked 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 228To have better control of resources and how threads access them, 229@theglibc{} implements a @dfn{mutex} object, which can help avoid race 230conditions and other concurrency issues. The term ``mutex'' refers to 231mutual exclusion. 232 233The fundamental data type for a mutex is the @code{mtx_t}: 234 235@deftp {Data Type} mtx_t 236@standards{C11, threads.h} 237The @code{mtx_t} data type uniquely identifies a mutex object. 238@end deftp 239 240The ISO C standard defines several types of mutexes. They are 241represented by the following symbolic constants: 242 243@vtable @code 244@item mtx_plain 245@standards{C11, threads.h} 246A mutex that does not support timeout, or test and return. 247 248@item mtx_recursive 249@standards{C11, threads.h} 250A mutex that supports recursive locking, which means that the owning 251thread can lock it more than once without causing deadlock. 252 253@item mtx_timed 254@standards{C11, threads.h} 255A mutex that supports timeout. 256@end vtable 257 258The 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 264object pointed to by @var{mutex} is set to the identifier of the newly 265created mutex. 266 267Not all combinations of mutex types are valid for the @code{type} 268argument. Valid uses of mutex types for the @code{type} argument are: 269 270@table @code 271@item mtx_plain 272A non-recursive mutex that does not support timeout. 273 274@item mtx_timed 275A non-recursive mutex that does support timeout. 276 277@item mtx_plain | mtx_recursive 278A recursive mutex that does not support timeout. 279 280@item mtx_timed | mtx_recursive 281A recursive mutex that does support timeout. 282@end table 283 284This 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 291by @var{mutex} is locked. The behavior is undefined if the current 292thread has already locked the mutex and the mutex is not recursive. 293 294Prior calls to @code{mtx_unlock} on the same mutex synchronize-with 295this operation (if this operation succeeds), and all lock/unlock 296operations on any given mutex form a single total order (similar to 297the modification order of an atomic). 298 299This 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 306to 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 308absolute time, if a duration is required, the calendar time must be 309calculated manually. @xref{Time Basics}, and @ref{Calendar Time}. 310 311If the current thread has already locked the mutex and the mutex is 312not recursive, or if the mutex does not support timeout, the behavior 313of this function is undefined. 314 315Prior calls to @code{mtx_unlock} on the same mutex synchronize-with 316this operation (if this operation succeeds), and all lock/unlock 317operations on any given mutex form a single total order (similar to 318the modification order of an atomic). 319 320This 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} 327without blocking. It returns immediately if the mutex is already 328locked. 329 330Prior calls to @code{mtx_unlock} on the same mutex synchronize-with 331this operation (if this operation succeeds), and all lock/unlock 332operations on any given mutex form a single total order (similar to 333the modification order of an atomic). 334 335This function returns @code{thrd_success} if the lock was obtained, 336@code{thrd_busy} if the mutex is already locked, and @code{thrd_error} 337on 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 344behavior is undefined if the mutex is not locked by the calling 345thread. 346 347This function synchronizes-with subsequent @code{mtx_lock}, 348@code{mtx_trylock}, and @code{mtx_timedlock} calls on the same mutex. 349All lock/unlock operations on any given mutex form a single total 350order (similar to the modification order of an atomic). 351 352This 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 359there are any threads waiting on the mutex, the behavior is 360undefined. 361@end deftypefun 362 363 364@node ISO C Condition Variables 365@subsection Condition Variables 366@cindex condvar 367@cindex condition variables 368 369Mutexes are not the only synchronization mechanisms available. For 370some more complex tasks, @theglibc{} also implements @dfn{condition 371variables}, which allow the programmer to think at a higher level when 372solving complex synchronization problems. They are used to 373synchronize threads waiting on a certain condition to happen. 374 375The fundamental data type for condition variables is the @code{cnd_t}: 376 377@deftp {Data Type} cnd_t 378@standards{C11, threads.h} 379The @code{cnd_t} uniquely identifies a condition variable object. 380@end deftp 381 382The 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 390This 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 398condition variable pointed to by @var{cond}. If a thread is 399successfully unblocked, this function returns @code{thrd_success}. If 400no 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 409waiting on the condition variable pointed to by @var{cond}. This 410function returns @code{thrd_success} on success. If no threads are 411blocked, 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} 420and blocks on the condition variable pointed to by @var{cond} until 421the thread is signaled by @code{cnd_signal} or @code{cnd_broadcast}. 422The mutex is locked again before the function returns. 423 424This 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 435the function returns. 436 437As for @code{mtx_timedlock}, since this function takes an absolute 438time, if a duration is required, the calendar time must be calculated 439manually. @xref{Time Basics}, and @ref{Calendar Time}. 440 441This 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 450is 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 459storage}, a mechanism by which variables can be defined to have unique 460per-thread storage, lifetimes that match the thread lifetime, and 461destructors that cleanup the unique per-thread storage. 462 463Several data types and macros exist for working with thread-local 464storage: 465 466@deftp {Data Type} tss_t 467@standards{C11, threads.h} 468The @code{tss_t} data type identifies a thread-specific storage 469object. Even if shared, every thread will have its own instance of 470the variable, with different values. 471@end deftp 472 473@deftp {Data Type} tss_dtor_t 474@standards{C11, threads.h} 475The @code{tss_dtor_t} is a function pointer of type @code{void (*) 476(void *)}, to be used as a thread-specific storage destructor. The 477function 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 484duration, which means it is created when the thread starts and cleaned 485up 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 494representing the maximum number of iterations over all thread-local 495destructors at the time of thread termination. This value provides a 496bounded limit to the destruction of thread-local storage; e.g., 497consider a destructor that creates more thread-local storage. 498@end defvr 499 500The 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 506it in the object pointed to by @var{tss_key}. Although the same key 507value 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 509the life of the calling thread. 510 511If @code{destructor} is not NULL, a destructor function will be set, 512and called when the thread finishes its execution by calling 513@code{thrd_exit}. 514 515This function returns @code{thrd_success} if @code{tss_key} is 516successfully set to a unique value for the thread; otherwise, 517@code{thrd_error} is returned and the value of @code{tss_key} is 518undefined. 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 525identified by @var{tss_key} for the current thread to @var{val}. 526Different threads may set different values to the same key. 527 528This 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 535thread-specific storage for the current thread. Different threads may 536get 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 548@node POSIX Threads 549@section POSIX Threads 550@cindex pthreads 551 552This section describes the @glibcadj{} POSIX Threads implementation. 553 554@menu 555* Thread-specific Data:: Support for creating and 556 managing thread-specific data 557* Non-POSIX Extensions:: Additional functions to extend 558 POSIX Thread functionality 559@end menu 560 561@node Thread-specific Data 562@subsection Thread-specific Data 563 564The @glibcadj{} implements functions to allow users to create and manage 565data specific to a thread. Such data may be destroyed at thread exit, 566if a destructor is provided. The following functions are defined: 567 568@deftypefun int pthread_key_create (pthread_key_t *@var{key}, void (*@var{destructor})(void*)) 569@standards{POSIX, pthread.h} 570@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} 571@c pthread_key_create ok 572@c KEY_UNUSED ok 573@c KEY_USABLE ok 574Create a thread-specific data key for the calling thread, referenced by 575@var{key}. 576 577Objects declared with the C++11 @code{thread_local} keyword are destroyed 578before thread-specific data, so they should not be used in thread-specific 579data destructors or even as members of the thread-specific data, since the 580latter is passed as an argument to the destructor function. 581@end deftypefun 582 583@deftypefun int pthread_key_delete (pthread_key_t @var{key}) 584@standards{POSIX, pthread.h} 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 590Destroy the thread-specific data @var{key} in the calling thread. The 591destructor for the thread-specific data is not called during destruction, nor 592is it called during thread exit. 593@end deftypefun 594 595@deftypefun void *pthread_getspecific (pthread_key_t @var{key}) 596@standards{POSIX, pthread.h} 597@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} 598@c pthread_getspecific ok 599Return the thread-specific data associated with @var{key} in the calling 600thread. 601@end deftypefun 602 603@deftypefun int pthread_setspecific (pthread_key_t @var{key}, const void *@var{value}) 604@standards{POSIX, pthread.h} 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 614Associate the thread-specific @var{value} with @var{key} in the calling thread. 615@end deftypefun 616 617 618@node Non-POSIX Extensions 619@subsection Non-POSIX Extensions 620 621In addition to implementing the POSIX API for threads, @theglibc{} provides 622additional functions and interfaces to provide functionality not specified in 623the standard. 624 625@menu 626* Default Thread Attributes:: Setting default attributes for 627 threads in a process. 628* Initial Thread Signal Mask:: Setting the initial mask of threads. 629* Waiting with Explicit Clocks:: Functions for waiting with an 630 explicit clock specification. 631* Single-Threaded:: Detecting single-threaded execution. 632* Restartable Sequences:: Linux-specific restartable sequences 633 integration. 634@end menu 635 636@node Default Thread Attributes 637@subsubsection Setting Process-wide defaults for thread attributes 638 639@Theglibc{} provides non-standard API functions to set and get the default 640attributes used in the creation of threads in a process. 641 642@deftypefun int pthread_getattr_default_np (pthread_attr_t *@var{attr}) 643@standards{GNU, pthread.h} 644@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} 645@c Takes lock around read from default_pthread_attr. 646Get the default attribute values and set @var{attr} to match. This 647function returns @math{0} on success and a non-zero error code on 648failure. 649@end deftypefun 650 651@deftypefun int pthread_setattr_default_np (pthread_attr_t *@var{attr}) 652@standards{GNU, pthread.h} 653@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{}}} 654@c pthread_setattr_default_np @ascuheap @asulock @aculock @acsmem 655@c check_sched_policy_attr ok 656@c check_sched_priority_attr ok 657@c sched_get_priority_min dup ok 658@c sched_get_priority_max dup ok 659@c check_stacksize_attr ok 660@c lll_lock @asulock @aculock 661@c free dup @ascuheap @acsmem 662@c realloc dup @ascuheap @acsmem 663@c memcpy dup ok 664@c lll_unlock @asulock @aculock 665Set the default attribute values to match the values in @var{attr}. The 666function returns @math{0} on success and a non-zero error code on failure. 667The following error codes are defined for this function: 668 669@table @code 670@item EINVAL 671At least one of the values in @var{attr} does not qualify as valid for the 672attributes or the stack address is set in the attribute. 673@item ENOMEM 674The system does not have sufficient memory. 675@end table 676@end deftypefun 677 678@node Initial Thread Signal Mask 679@subsubsection Controlling the Initial Signal Mask of a New Thread 680 681@Theglibc{} provides a way to specify the initial signal mask of a 682thread created using @code{pthread_create}, passing a thread attribute 683object configured for this purpose. 684 685@deftypefun int pthread_attr_setsigmask_np (pthread_attr_t *@var{attr}, const sigset_t *@var{sigmask}) 686@standards{GNU, pthread.h} 687@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} 688Change the initial signal mask specified by @var{attr}. If 689@var{sigmask} is not @code{NULL}, the initial signal mask for new 690threads created with @var{attr} is set to @code{*@var{sigmask}}. If 691@var{sigmask} is @code{NULL}, @var{attr} will no longer specify an 692explicit signal mask, so that the initial signal mask of the new 693thread is inherited from the thread that calls @code{pthread_create}. 694 695This function returns zero on success, and @code{ENOMEM} on memory 696allocation failure. 697@end deftypefun 698 699@deftypefun int pthread_attr_getsigmask_np (const pthread_attr_t *@var{attr}, sigset_t *@var{sigmask}) 700@standards{GNU, pthread.h} 701@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} 702Retrieve the signal mask stored in @var{attr} and copy it to 703@code{*@var{sigmask}}. If the signal mask has not been set, return 704the special constant @code{PTHREAD_ATTR_NO_SIGMASK_NP}, otherwise 705return zero. 706 707@c Move this to the documentation of pthread_getattr_np once it exists. 708Obtaining the signal mask only works if it has been previously stored 709by @code{pthread_attr_setsigmask_np}. For example, the 710@code{pthread_getattr_np} function does not obtain the current signal 711mask of the specified thread, and @code{pthread_attr_getsigmask_np} 712will subsequently report the signal mask as unset. 713@end deftypefun 714 715@deftypevr Macro int PTHREAD_ATTR_NO_SIGMASK_NP 716The special value returned by @code{pthread_attr_setsigmask_np} to 717indicate that no signal mask has been set for the attribute. 718@end deftypevr 719 720It is possible to create a new thread with a specific signal mask 721without using these functions. On the thread that calls 722@code{pthread_create}, the required steps for the general case are: 723 724@enumerate 1 725@item 726Mask all signals, and save the old signal mask, using 727@code{pthread_sigmask}. This ensures that the new thread will be 728created with all signals masked, so that no signals can be delivered 729to the thread until the desired signal mask is set. 730 731@item 732Call @code{pthread_create} to create the new thread, passing the 733desired signal mask to the thread start routine (which could be a 734wrapper function for the actual thread start routine). It may be 735necessary to make a copy of the desired signal mask on the heap, so 736that the life-time of the copy extends to the point when the start 737routine needs to access the signal mask. 738 739@item 740Restore the thread's signal mask, to the set that was saved in the 741first step. 742@end enumerate 743 744The start routine for the created thread needs to locate the desired 745signal mask and use @code{pthread_sigmask} to apply it to the thread. 746If the signal mask was copied to a heap allocation, the copy should be 747freed. 748 749@node Waiting with Explicit Clocks 750@subsubsection Functions for Waiting According to a Specific Clock 751 752@Theglibc{} provides several waiting functions that expect an explicit 753@code{clockid_t} argument. 754 755@comment semaphore.h 756@comment POSIX-proposed 757@deftypefun int sem_clockwait (sem_t *@var{sem}, clockid_t @var{clockid}, 758 const struct timespec *@var{abstime}) 759Behaves like @code{sem_timedwait} except the time @var{abstime} is measured 760against the clock specified by @var{clockid} rather than 761@code{CLOCK_REALTIME}. Currently, @var{clockid} must be either 762@code{CLOCK_MONOTONIC} or @code{CLOCK_REALTIME}. 763@end deftypefun 764 765@comment pthread.h 766@comment POSIX-proposed 767@deftypefun int pthread_cond_clockwait (pthread_cond_t *@var{cond}, pthread_mutex_t *@var{mutex}, 768 clockid_t @var{clockid}, const struct timespec *@var{abstime}) 769@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} 770@c If exactly the same function with arguments is called from a signal 771@c handler that interrupts between the mutex unlock and sleep then it 772@c will unlock the mutex twice resulting in undefined behaviour. Keep 773@c in mind that the unlock and sleep are only atomic with respect to other 774@c threads (really a happens-after relationship for pthread_cond_broadcast 775@c and pthread_cond_signal). 776@c In the AC case we would cancel the thread and the mutex would remain 777@c locked and we can't recover from that. 778Behaves like @code{pthread_cond_timedwait} except the time @var{abstime} is 779measured against the clock specified by @var{clockid} rather than the clock 780specified or defaulted when @code{pthread_cond_init} was called. Currently, 781@var{clockid} must be either @code{CLOCK_MONOTONIC} or 782@code{CLOCK_REALTIME}. 783@end deftypefun 784 785@comment pthread.h 786@comment POSIX-proposed 787@deftypefun int pthread_rwlock_clockrdlock (pthread_rwlock_t *@var{rwlock}, 788 clockid_t @var{clockid}, 789 const struct timespec *@var{abstime}) 790 791@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} 792Behaves like @code{pthread_rwlock_timedrdlock} except the time 793@var{abstime} is measured against the clock specified by @var{clockid} 794rather than @code{CLOCK_REALTIME}. Currently, @var{clockid} must be either 795@code{CLOCK_MONOTONIC} or @code{CLOCK_REALTIME}, otherwise @code{EINVAL} is 796returned. 797@end deftypefun 798 799@comment pthread.h 800@comment POSIX-proposed 801@deftypefun int pthread_rwlock_clockwrlock (pthread_rwlock_t *@var{rwlock}, 802 clockid_t @var{clockid}, 803 const struct timespec *@var{abstime}) 804 805@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} 806Behaves like @code{pthread_rwlock_timedwrlock} except the time 807@var{abstime} is measured against the clock specified by @var{clockid} 808rather than @code{CLOCK_REALTIME}. Currently, @var{clockid} must be either 809@code{CLOCK_MONOTONIC} or @code{CLOCK_REALTIME}, otherwise @code{EINVAL} is 810returned. 811@end deftypefun 812 813@comment pthread.h 814@comment GNU extension 815@deftypefun int pthread_tryjoin_np (pthread_t *@var{thread}, 816 void **@var{thread_return}) 817@standards{GNU, pthread.h} 818@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} 819Behaves like @code{pthread_join} except that it will return @code{EBUSY} 820immediately if the thread specified by @var{thread} has not yet terminated. 821@end deftypefun 822 823@comment pthread.h 824@comment GNU extension 825@deftypefun int pthread_timedjoin_np (pthread_t *@var{thread}, 826 void **@var{thread_return}, 827 const struct timespec *@var{abstime}) 828@standards{GNU, pthread.h} 829@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} 830Behaves like @code{pthread_tryjoin_np} except that it will block until the 831absolute time @var{abstime} measured against @code{CLOCK_REALTIME} is 832reached if the thread has not terminated by that time and return 833@code{EBUSY}. If @var{abstime} is equal to @code{NULL} then the function 834will wait forever in the same way as @code{pthread_join}. 835@end deftypefun 836 837@comment pthread.h 838@comment GNU extension 839@deftypefun int pthread_clockjoin_np (pthread_t *@var{thread}, 840 void **@var{thread_return}, 841 clockid_t @var{clockid}, 842 const struct timespec *@var{abstime}) 843@standards{GNU, pthread.h} 844@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} 845Behaves like @code{pthread_timedjoin_np} except that the absolute time in 846@var{abstime} is measured against the clock specified by @var{clockid}. 847Currently, @var{clockid} must be either @code{CLOCK_MONOTONIC} or 848@code{CLOCK_REALTIME}. 849@end deftypefun 850 851@node Single-Threaded 852@subsubsection Detecting Single-Threaded Execution 853 854Multi-threaded programs require synchronization among threads. This 855synchronization can be costly even if there is just a single thread 856and no data is shared between multiple processors. @Theglibc{} offers 857an interface to detect whether the process is in single-threaded mode. 858Applications can use this information to avoid synchronization, for 859example by using regular instructions to load and store memory instead 860of atomic instructions, or using relaxed memory ordering instead of 861stronger memory ordering. 862 863@deftypevar char __libc_single_threaded 864@standards{GNU, sys/single_threaded.h} 865This variable is non-zero if the current process is definitely 866single-threaded. If it is zero, the process may be multi-threaded, 867or @theglibc{} cannot determine at this point of the program execution 868whether the process is single-threaded or not. 869 870Applications must never write to this variable. 871@end deftypevar 872 873Most applications should perform the same actions whether or not 874@code{__libc_single_threaded} is true, except with less 875synchronization. If this rule is followed, a process that 876subsequently becomes multi-threaded is already in a consistent state. 877For example, in order to increment a reference count, the following 878code can be used: 879 880@smallexample 881if (__libc_single_threaded) 882 atomic_fetch_add (&reference_count, 1, memory_order_relaxed); 883else 884 atomic_fetch_add (&reference_count, 1, memory_order_acq_rel); 885@end smallexample 886 887@c Note: No memory order on __libc_single_threaded. The 888@c implementation must ensure that exit of the critical 889@c (second-to-last) thread happens-before setting 890@c __libc_single_threaded to true. Otherwise, acquire MO might be 891@c needed for reading the variable in some scenarios, and that would 892@c completely defeat its purpose. 893 894This still requires some form of synchronization on the 895single-threaded branch, so it can be beneficial not to declare the 896reference count as @code{_Atomic}, and use the GCC @code{__atomic} 897built-ins. @xref{__atomic Builtins,, Built-in Functions for Memory 898Model Aware Atomic Operations, gcc, Using the GNU Compiler Collection 899(GCC)}. Then the code to increment a reference count looks like this: 900 901@smallexample 902if (__libc_single_threaded) 903 ++reference_count; 904else 905 __atomic_fetch_add (&reference_count, 1, __ATOMIC_ACQ_REL); 906@end smallexample 907 908(Depending on the data associated with the reference count, it may be 909possible to use the weaker @code{__ATOMIC_RELAXED} memory ordering on 910the multi-threaded branch.) 911 912Several functions in @theglibc{} can change the value of the 913@code{__libc_single_threaded} variable. For example, creating new 914threads using the @code{pthread_create} or @code{thrd_create} function 915sets the variable to false. This can also happen indirectly, say via 916a call to @code{dlopen}. Therefore, applications need to make a copy 917of the value of @code{__libc_single_threaded} if after such a function 918call, behavior must match the value as it was before the call, like 919this: 920 921@smallexample 922bool single_threaded = __libc_single_threaded; 923if (single_threaded) 924 prepare_single_threaded (); 925else 926 prepare_multi_thread (); 927 928void *handle = dlopen (shared_library_name, RTLD_NOW); 929lookup_symbols (handle); 930 931if (single_threaded) 932 cleanup_single_threaded (); 933else 934 cleanup_multi_thread (); 935@end smallexample 936 937Since the value of @code{__libc_single_threaded} can change from true 938to false during the execution of the program, it is not useful for 939selecting optimized function implementations in IFUNC resolvers. 940 941Atomic operations can also be used on mappings shared among 942single-threaded processes. This means that a compiler must not use 943@code{__libc_single_threaded} to optimize atomic operations, unless it 944is able to prove that the memory is not shared. 945 946@strong{Implementation Note:} The @code{__libc_single_threaded} 947variable is not declared as @code{volatile} because it is expected 948that compilers optimize a sequence of single-threaded checks into one 949check, for example if several reference counts are updated. The 950current implementation in @theglibc{} does not set the 951@code{__libc_single_threaded} variable to a true value if a process 952turns single-threaded again. Future versions of @theglibc{} may do 953this, but only as the result of function calls which imply an acquire 954(compiler) barrier. (Some compilers assume that well-known functions 955such as @code{malloc} do not write to global variables, and setting 956@code{__libc_single_threaded} would introduce a data race and 957undefined behavior.) In any case, an application must not write to 958@code{__libc_single_threaded} even if it has joined the last 959application-created thread because future versions of @theglibc{} may 960create background threads after the first thread has been created, and 961the application has no way of knowning that these threads are present. 962 963@node Restartable Sequences 964@subsubsection Restartable Sequences 965 966This section describes restartable sequences integration for 967@theglibc{}. This functionality is only available on Linux. 968 969@deftp {Data Type} {struct rseq} 970@standards{Linux, sys/rseq.h} 971The type of the restartable sequences area. Future versions 972of Linux may add additional fields to the end of this structure. 973 974 975Users need to obtain the address of the restartable sequences area using 976the thread pointer and the @code{__rseq_offset} variable, described 977below. 978 979One use of the restartable sequences area is to read the current CPU 980number from its @code{cpu_id} field, as an inline version of 981@code{sched_getcpu}. @Theglibc{} sets the @code{cpu_id} field to 982@code{RSEQ_CPU_ID_REGISTRATION_FAILED} if registration failed or was 983explicitly disabled. 984 985Furthermore, users can store the address of a @code{struct rseq_cs} 986object into the @code{rseq_cs} field of @code{struct rseq}, thus 987informing the kernel that the thread enters a restartable sequence 988critical section. This pointer and the code areas it itself points to 989must not be left pointing to memory areas which are freed or re-used. 990Several approaches can guarantee this. If the application or library 991can guarantee that the memory used to hold the @code{struct rseq_cs} and 992the code areas it refers to are never freed or re-used, no special 993action must be taken. Else, before that memory is re-used of freed, the 994application is responsible for setting the @code{rseq_cs} field to 995@code{NULL} in each thread's restartable sequence area to guarantee that 996it does not leak dangling references. Because the application does not 997typically have knowledge of libraries' use of restartable sequences, it 998is recommended that libraries using restartable sequences which may end 999up freeing or re-using their memory set the @code{rseq_cs} field to 1000@code{NULL} before returning from library functions which use 1001restartable sequences. 1002 1003The manual for the @code{rseq} system call can be found 1004at @uref{https://git.kernel.org/pub/scm/libs/librseq/librseq.git/tree/doc/man/rseq.2}. 1005@end deftp 1006 1007@deftypevar {ptrdiff_t} __rseq_offset 1008@standards{Linux, sys/rseq.h} 1009This variable contains the offset between the thread pointer (as defined 1010by @code{__builtin_thread_pointer} or the thread pointer register for 1011the architecture) and the restartable sequences area. This value is the 1012same for all threads in the process. If the restartable sequences area 1013is located at a lower address than the location to which the thread 1014pointer points, the value is negative. 1015@end deftypevar 1016 1017@deftypevar {unsigned int} __rseq_size 1018@standards{Linux, sys/rseq.h} 1019This variable is either zero (if restartable sequence registration 1020failed or has been disabled) or the size of the restartable sequence 1021registration. This can be different from the size of @code{struct rseq} 1022if the kernel has extended the size of the registration. If 1023registration is successful, @code{__rseq_size} is at least 32 (the 1024initial size of @code{struct rseq}). 1025@end deftypevar 1026 1027@deftypevar {unsigned int} __rseq_flags 1028@standards{Linux, sys/rseq.h} 1029The flags used during restartable sequence registration with the kernel. 1030Currently zero. 1031@end deftypevar 1032 1033@deftypevr Macro int RSEQ_SIG 1034@standards{Linux, sys/rseq.h} 1035Each supported architecture provides a @code{RSEQ_SIG} macro in 1036@file{sys/rseq.h} which contains a signature. That signature is 1037expected to be present in the code before each restartable sequences 1038abort handler. Failure to provide the expected signature may terminate 1039the process with a segmentation fault. 1040@end deftypevr 1041 1042@c FIXME these are undocumented: 1043@c pthread_atfork 1044@c pthread_attr_destroy 1045@c pthread_attr_getaffinity_np 1046@c pthread_attr_getdetachstate 1047@c pthread_attr_getguardsize 1048@c pthread_attr_getinheritsched 1049@c pthread_attr_getschedparam 1050@c pthread_attr_getschedpolicy 1051@c pthread_attr_getscope 1052@c pthread_attr_getstack 1053@c pthread_attr_getstackaddr 1054@c pthread_attr_getstacksize 1055@c pthread_attr_init 1056@c pthread_attr_setaffinity_np 1057@c pthread_attr_setdetachstate 1058@c pthread_attr_setguardsize 1059@c pthread_attr_setinheritsched 1060@c pthread_attr_setschedparam 1061@c pthread_attr_setschedpolicy 1062@c pthread_attr_setscope 1063@c pthread_attr_setstack 1064@c pthread_attr_setstackaddr 1065@c pthread_attr_setstacksize 1066@c pthread_barrierattr_destroy 1067@c pthread_barrierattr_getpshared 1068@c pthread_barrierattr_init 1069@c pthread_barrierattr_setpshared 1070@c pthread_barrier_destroy 1071@c pthread_barrier_init 1072@c pthread_barrier_wait 1073@c pthread_cancel 1074@c pthread_cleanup_push 1075@c pthread_cleanup_pop 1076@c pthread_condattr_destroy 1077@c pthread_condattr_getclock 1078@c pthread_condattr_getpshared 1079@c pthread_condattr_init 1080@c pthread_condattr_setclock 1081@c pthread_condattr_setpshared 1082@c pthread_cond_broadcast 1083@c pthread_cond_destroy 1084@c pthread_cond_init 1085@c pthread_cond_signal 1086@c pthread_cond_timedwait 1087@c pthread_cond_wait 1088@c pthread_create 1089@c pthread_detach 1090@c pthread_equal 1091@c pthread_exit 1092@c pthread_getaffinity_np 1093@c pthread_getattr_np 1094@c pthread_getconcurrency 1095@c pthread_getcpuclockid 1096@c pthread_getname_np 1097@c pthread_getschedparam 1098@c pthread_join 1099@c pthread_kill 1100@c pthread_kill_other_threads_np 1101@c pthread_mutexattr_destroy 1102@c pthread_mutexattr_getkind_np 1103@c pthread_mutexattr_getprioceiling 1104@c pthread_mutexattr_getprotocol 1105@c pthread_mutexattr_getpshared 1106@c pthread_mutexattr_getrobust 1107@c pthread_mutexattr_getrobust_np 1108@c pthread_mutexattr_gettype 1109@c pthread_mutexattr_init 1110@c pthread_mutexattr_setkind_np 1111@c pthread_mutexattr_setprioceiling 1112@c pthread_mutexattr_setprotocol 1113@c pthread_mutexattr_setpshared 1114@c pthread_mutexattr_setrobust 1115@c pthread_mutexattr_setrobust_np 1116@c pthread_mutexattr_settype 1117@c pthread_mutex_consistent 1118@c pthread_mutex_consistent_np 1119@c pthread_mutex_destroy 1120@c pthread_mutex_getprioceiling 1121@c pthread_mutex_init 1122@c pthread_mutex_lock 1123@c pthread_mutex_setprioceiling 1124@c pthread_mutex_timedlock 1125@c pthread_mutex_trylock 1126@c pthread_mutex_unlock 1127@c pthread_once 1128@c pthread_rwlockattr_destroy 1129@c pthread_rwlockattr_getkind_np 1130@c pthread_rwlockattr_getpshared 1131@c pthread_rwlockattr_init 1132@c pthread_rwlockattr_setkind_np 1133@c pthread_rwlockattr_setpshared 1134@c pthread_rwlock_destroy 1135@c pthread_rwlock_init 1136@c pthread_rwlock_rdlock 1137@c pthread_rwlock_timedrdlock 1138@c pthread_rwlock_timedwrlock 1139@c pthread_rwlock_tryrdlock 1140@c pthread_rwlock_trywrlock 1141@c pthread_rwlock_unlock 1142@c pthread_rwlock_wrlock 1143@c pthread_self 1144@c pthread_setaffinity_np 1145@c pthread_setcancelstate 1146@c pthread_setcanceltype 1147@c pthread_setconcurrency 1148@c pthread_setname_np 1149@c pthread_setschedparam 1150@c pthread_setschedprio 1151@c pthread_sigmask 1152@c pthread_sigqueue 1153@c pthread_spin_destroy 1154@c pthread_spin_init 1155@c pthread_spin_lock 1156@c pthread_spin_trylock 1157@c pthread_spin_unlock 1158@c pthread_testcancel 1159@c pthread_yield 1160