1 /* Copyright (C) 2002, 2003, 2004, 2005, 2006, 2007 2 Free Software Foundation, Inc. 3 This file is part of the GNU C Library. 4 5 The GNU C Library is free software; you can redistribute it and/or 6 modify it under the terms of the GNU Lesser General Public 7 License as published by the Free Software Foundation; either 8 version 2.1 of the License, or (at your option) any later version. 9 10 The GNU C Library is distributed in the hope that it will be useful, 11 but WITHOUT ANY WARRANTY; without even the implied warranty of 12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 13 Lesser General Public License for more details. 14 15 You should have received a copy of the GNU Lesser General Public 16 License along with the GNU C Library; if not, write to the Free 17 Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 18 02111-1307 USA. */ 19 20 #ifndef _PTHREAD_H 21 #define _PTHREAD_H 1 22 23 #include <features.h> 24 #include <endian.h> 25 #include <sched.h> 26 #include <time.h> 27 28 #define __need_sigset_t 29 #include <signal.h> 30 #include <bits/pthreadtypes.h> 31 #include <bits/setjmp.h> 32 #include <bits/wordsize.h> 33 34 35 /* Detach state. */ 36 enum 37 { 38 PTHREAD_CREATE_JOINABLE, 39 #define PTHREAD_CREATE_JOINABLE PTHREAD_CREATE_JOINABLE 40 PTHREAD_CREATE_DETACHED 41 #define PTHREAD_CREATE_DETACHED PTHREAD_CREATE_DETACHED 42 }; 43 44 45 /* Mutex types. */ 46 enum 47 { 48 PTHREAD_MUTEX_TIMED_NP, 49 PTHREAD_MUTEX_RECURSIVE_NP, 50 PTHREAD_MUTEX_ERRORCHECK_NP, 51 PTHREAD_MUTEX_ADAPTIVE_NP 52 #ifdef __USE_UNIX98 53 , 54 PTHREAD_MUTEX_NORMAL = PTHREAD_MUTEX_TIMED_NP, 55 PTHREAD_MUTEX_RECURSIVE = PTHREAD_MUTEX_RECURSIVE_NP, 56 PTHREAD_MUTEX_ERRORCHECK = PTHREAD_MUTEX_ERRORCHECK_NP, 57 PTHREAD_MUTEX_DEFAULT = PTHREAD_MUTEX_NORMAL 58 #endif 59 #ifdef __USE_GNU 60 /* For compatibility. */ 61 , PTHREAD_MUTEX_FAST_NP = PTHREAD_MUTEX_TIMED_NP 62 #endif 63 }; 64 65 66 #ifdef __USE_GNU 67 /* Robust mutex or not flags. */ 68 enum 69 { 70 PTHREAD_MUTEX_STALLED_NP, 71 PTHREAD_MUTEX_ROBUST_NP 72 }; 73 #endif 74 75 76 #ifdef __USE_UNIX98 77 /* Mutex protocols. */ 78 enum 79 { 80 PTHREAD_PRIO_NONE, 81 PTHREAD_PRIO_INHERIT, 82 PTHREAD_PRIO_PROTECT 83 }; 84 #endif 85 86 87 /* Mutex initializers. */ 88 #if __WORDSIZE == 64 89 # define PTHREAD_MUTEX_INITIALIZER \ 90 { { 0, 0, 0, 0, 0, 0, { 0, 0 } } } 91 # ifdef __USE_GNU 92 # define PTHREAD_RECURSIVE_MUTEX_INITIALIZER_NP \ 93 { { 0, 0, 0, 0, PTHREAD_MUTEX_RECURSIVE_NP, 0, { 0, 0 } } } 94 # define PTHREAD_ERRORCHECK_MUTEX_INITIALIZER_NP \ 95 { { 0, 0, 0, 0, PTHREAD_MUTEX_ERRORCHECK_NP, 0, { 0, 0 } } } 96 # define PTHREAD_ADAPTIVE_MUTEX_INITIALIZER_NP \ 97 { { 0, 0, 0, 0, PTHREAD_MUTEX_ADAPTIVE_NP, 0, { 0, 0 } } } 98 # endif 99 #else 100 # define PTHREAD_MUTEX_INITIALIZER \ 101 { { 0, 0, 0, 0, 0, { 0 } } } 102 # ifdef __USE_GNU 103 # define PTHREAD_RECURSIVE_MUTEX_INITIALIZER_NP \ 104 { { 0, 0, 0, PTHREAD_MUTEX_RECURSIVE_NP, 0, { 0 } } } 105 # define PTHREAD_ERRORCHECK_MUTEX_INITIALIZER_NP \ 106 { { 0, 0, 0, PTHREAD_MUTEX_ERRORCHECK_NP, 0, { 0 } } } 107 # define PTHREAD_ADAPTIVE_MUTEX_INITIALIZER_NP \ 108 { { 0, 0, 0, PTHREAD_MUTEX_ADAPTIVE_NP, 0, { 0 } } } 109 # endif 110 #endif 111 112 113 /* Read-write lock types. */ 114 #if defined __USE_UNIX98 || defined __USE_XOPEN2K 115 enum 116 { 117 PTHREAD_RWLOCK_PREFER_READER_NP, 118 PTHREAD_RWLOCK_PREFER_WRITER_NP, 119 PTHREAD_RWLOCK_PREFER_WRITER_NONRECURSIVE_NP, 120 PTHREAD_RWLOCK_DEFAULT_NP = PTHREAD_RWLOCK_PREFER_READER_NP 121 }; 122 123 /* Read-write lock initializers. */ 124 # define PTHREAD_RWLOCK_INITIALIZER \ 125 { { 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 } } 126 # ifdef __USE_GNU 127 # if __WORDSIZE == 64 128 # define PTHREAD_RWLOCK_WRITER_NONRECURSIVE_INITIALIZER_NP \ 129 { { 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, \ 130 PTHREAD_RWLOCK_PREFER_WRITER_NONRECURSIVE_NP } } 131 # else 132 # if __BYTE_ORDER == __LITTLE_ENDIAN 133 # define PTHREAD_RWLOCK_WRITER_NONRECURSIVE_INITIALIZER_NP \ 134 { { 0, 0, 0, 0, 0, 0, PTHREAD_RWLOCK_PREFER_WRITER_NONRECURSIVE_NP, \ 135 0, 0, 0, 0 } } 136 # else 137 # define PTHREAD_RWLOCK_WRITER_NONRECURSIVE_INITIALIZER_NP \ 138 { { 0, 0, 0, 0, 0, 0, 0, 0, 0, PTHREAD_RWLOCK_PREFER_WRITER_NONRECURSIVE_NP,\ 139 0 } } 140 # endif 141 # endif 142 # endif 143 #endif /* Unix98 or XOpen2K */ 144 145 146 /* Scheduler inheritance. */ 147 enum 148 { 149 PTHREAD_INHERIT_SCHED, 150 #define PTHREAD_INHERIT_SCHED PTHREAD_INHERIT_SCHED 151 PTHREAD_EXPLICIT_SCHED 152 #define PTHREAD_EXPLICIT_SCHED PTHREAD_EXPLICIT_SCHED 153 }; 154 155 156 /* Scope handling. */ 157 enum 158 { 159 PTHREAD_SCOPE_SYSTEM, 160 #define PTHREAD_SCOPE_SYSTEM PTHREAD_SCOPE_SYSTEM 161 PTHREAD_SCOPE_PROCESS 162 #define PTHREAD_SCOPE_PROCESS PTHREAD_SCOPE_PROCESS 163 }; 164 165 166 /* Process shared or private flag. */ 167 enum 168 { 169 PTHREAD_PROCESS_PRIVATE, 170 #define PTHREAD_PROCESS_PRIVATE PTHREAD_PROCESS_PRIVATE 171 PTHREAD_PROCESS_SHARED 172 #define PTHREAD_PROCESS_SHARED PTHREAD_PROCESS_SHARED 173 }; 174 175 176 177 /* Conditional variable handling. */ 178 #define PTHREAD_COND_INITIALIZER { { 0, 0, 0, 0, 0, (void *) 0, 0, 0 } } 179 180 181 /* Cleanup buffers */ 182 struct _pthread_cleanup_buffer 183 { 184 void (*__routine) (void *); /* Function to call. */ 185 void *__arg; /* Its argument. */ 186 int __canceltype; /* Saved cancellation type. */ 187 struct _pthread_cleanup_buffer *__prev; /* Chaining of cleanup functions. */ 188 }; 189 190 /* Cancellation */ 191 enum 192 { 193 PTHREAD_CANCEL_ENABLE, 194 #define PTHREAD_CANCEL_ENABLE PTHREAD_CANCEL_ENABLE 195 PTHREAD_CANCEL_DISABLE 196 #define PTHREAD_CANCEL_DISABLE PTHREAD_CANCEL_DISABLE 197 }; 198 enum 199 { 200 PTHREAD_CANCEL_DEFERRED, 201 #define PTHREAD_CANCEL_DEFERRED PTHREAD_CANCEL_DEFERRED 202 PTHREAD_CANCEL_ASYNCHRONOUS 203 #define PTHREAD_CANCEL_ASYNCHRONOUS PTHREAD_CANCEL_ASYNCHRONOUS 204 }; 205 #define PTHREAD_CANCELED ((void *) -1) 206 207 208 /* Single execution handling. */ 209 #define PTHREAD_ONCE_INIT 0 210 211 212 #ifdef __USE_XOPEN2K 213 /* Value returned by 'pthread_barrier_wait' for one of the threads after 214 the required number of threads have called this function. 215 -1 is distinct from 0 and all errno constants */ 216 # define PTHREAD_BARRIER_SERIAL_THREAD -1 217 #endif 218 219 220 __BEGIN_DECLS 221 222 /* Create a new thread, starting with execution of START-ROUTINE 223 getting passed ARG. Creation attributed come from ATTR. The new 224 handle is stored in *NEWTHREAD. */ 225 extern int pthread_create (pthread_t *__restrict __newthread, 226 __const pthread_attr_t *__restrict __attr, 227 void *(*__start_routine) (void *), 228 void *__restrict __arg) __THROW __nonnull ((1, 3)); 229 230 /* Terminate calling thread. 231 232 The registered cleanup handlers are called via exception handling 233 so we cannot mark this function with __THROW.*/ 234 extern void pthread_exit (void *__retval) __attribute__ ((__noreturn__)); 235 236 /* Make calling thread wait for termination of the thread TH. The 237 exit status of the thread is stored in *THREAD_RETURN, if THREAD_RETURN 238 is not NULL. 239 240 This function is a cancellation point and therefore not marked with 241 __THROW. */ 242 extern int pthread_join (pthread_t __th, void **__thread_return); 243 244 #ifdef __USE_GNU 245 /* Check whether thread TH has terminated. If yes return the status of 246 the thread in *THREAD_RETURN, if THREAD_RETURN is not NULL. */ 247 extern int pthread_tryjoin_np (pthread_t __th, void **__thread_return) __THROW; 248 249 /* Make calling thread wait for termination of the thread TH, but only 250 until TIMEOUT. The exit status of the thread is stored in 251 *THREAD_RETURN, if THREAD_RETURN is not NULL. 252 253 This function is a cancellation point and therefore not marked with 254 __THROW. */ 255 extern int pthread_timedjoin_np (pthread_t __th, void **__thread_return, 256 __const struct timespec *__abstime); 257 #endif 258 259 /* Indicate that the thread TH is never to be joined with PTHREAD_JOIN. 260 The resources of TH will therefore be freed immediately when it 261 terminates, instead of waiting for another thread to perform PTHREAD_JOIN 262 on it. */ 263 extern int pthread_detach (pthread_t __th) __THROW; 264 265 266 /* Obtain the identifier of the current thread. */ 267 extern pthread_t pthread_self (void) __THROW __attribute__ ((__const__)); 268 269 /* Compare two thread identifiers. */ 270 extern int pthread_equal (pthread_t __thread1, pthread_t __thread2) __THROW; 271 272 273 /* Thread attribute handling. */ 274 275 /* Initialize thread attribute *ATTR with default attributes 276 (detachstate is PTHREAD_JOINABLE, scheduling policy is SCHED_OTHER, 277 no user-provided stack). */ 278 extern int pthread_attr_init (pthread_attr_t *__attr) __THROW __nonnull ((1)); 279 280 /* Destroy thread attribute *ATTR. */ 281 extern int pthread_attr_destroy (pthread_attr_t *__attr) 282 __THROW __nonnull ((1)); 283 284 /* Get detach state attribute. */ 285 extern int pthread_attr_getdetachstate (__const pthread_attr_t *__attr, 286 int *__detachstate) 287 __THROW __nonnull ((1, 2)); 288 289 /* Set detach state attribute. */ 290 extern int pthread_attr_setdetachstate (pthread_attr_t *__attr, 291 int __detachstate) 292 __THROW __nonnull ((1)); 293 294 295 /* Get the size of the guard area created for stack overflow protection. */ 296 extern int pthread_attr_getguardsize (__const pthread_attr_t *__attr, 297 size_t *__guardsize) 298 __THROW __nonnull ((1, 2)); 299 300 /* Set the size of the guard area created for stack overflow protection. */ 301 extern int pthread_attr_setguardsize (pthread_attr_t *__attr, 302 size_t __guardsize) 303 __THROW __nonnull ((1)); 304 305 306 /* Return in *PARAM the scheduling parameters of *ATTR. */ 307 extern int pthread_attr_getschedparam (__const pthread_attr_t *__restrict 308 __attr, 309 struct sched_param *__restrict __param) 310 __THROW __nonnull ((1, 2)); 311 312 /* Set scheduling parameters (priority, etc) in *ATTR according to PARAM. */ 313 extern int pthread_attr_setschedparam (pthread_attr_t *__restrict __attr, 314 __const struct sched_param *__restrict 315 __param) __THROW __nonnull ((1, 2)); 316 317 /* Return in *POLICY the scheduling policy of *ATTR. */ 318 extern int pthread_attr_getschedpolicy (__const pthread_attr_t *__restrict 319 __attr, int *__restrict __policy) 320 __THROW __nonnull ((1, 2)); 321 322 /* Set scheduling policy in *ATTR according to POLICY. */ 323 extern int pthread_attr_setschedpolicy (pthread_attr_t *__attr, int __policy) 324 __THROW __nonnull ((1)); 325 326 /* Return in *INHERIT the scheduling inheritance mode of *ATTR. */ 327 extern int pthread_attr_getinheritsched (__const pthread_attr_t *__restrict 328 __attr, int *__restrict __inherit) 329 __THROW __nonnull ((1, 2)); 330 331 /* Set scheduling inheritance mode in *ATTR according to INHERIT. */ 332 extern int pthread_attr_setinheritsched (pthread_attr_t *__attr, 333 int __inherit) 334 __THROW __nonnull ((1)); 335 336 337 /* Return in *SCOPE the scheduling contention scope of *ATTR. */ 338 extern int pthread_attr_getscope (__const pthread_attr_t *__restrict __attr, 339 int *__restrict __scope) 340 __THROW __nonnull ((1, 2)); 341 342 /* Set scheduling contention scope in *ATTR according to SCOPE. */ 343 extern int pthread_attr_setscope (pthread_attr_t *__attr, int __scope) 344 __THROW __nonnull ((1)); 345 346 /* Return the previously set address for the stack. */ 347 extern int pthread_attr_getstackaddr (__const pthread_attr_t *__restrict 348 __attr, void **__restrict __stackaddr) 349 __THROW __nonnull ((1, 2)) __attribute_deprecated__; 350 351 /* Set the starting address of the stack of the thread to be created. 352 Depending on whether the stack grows up or down the value must either 353 be higher or lower than all the address in the memory block. The 354 minimal size of the block must be PTHREAD_STACK_MIN. */ 355 extern int pthread_attr_setstackaddr (pthread_attr_t *__attr, 356 void *__stackaddr) 357 __THROW __nonnull ((1)) __attribute_deprecated__; 358 359 /* Return the currently used minimal stack size. */ 360 extern int pthread_attr_getstacksize (__const pthread_attr_t *__restrict 361 __attr, size_t *__restrict __stacksize) 362 __THROW __nonnull ((1, 2)); 363 364 /* Add information about the minimum stack size needed for the thread 365 to be started. This size must never be less than PTHREAD_STACK_MIN 366 and must also not exceed the system limits. */ 367 extern int pthread_attr_setstacksize (pthread_attr_t *__attr, 368 size_t __stacksize) 369 __THROW __nonnull ((1)); 370 371 #ifdef __USE_XOPEN2K 372 /* Return the previously set address for the stack. */ 373 extern int pthread_attr_getstack (__const pthread_attr_t *__restrict __attr, 374 void **__restrict __stackaddr, 375 size_t *__restrict __stacksize) 376 __THROW __nonnull ((1, 2, 3)); 377 378 /* The following two interfaces are intended to replace the last two. They 379 require setting the address as well as the size since only setting the 380 address will make the implementation on some architectures impossible. */ 381 extern int pthread_attr_setstack (pthread_attr_t *__attr, void *__stackaddr, 382 size_t __stacksize) __THROW __nonnull ((1)); 383 #endif 384 385 #ifdef __USE_GNU 386 /* Thread created with attribute ATTR will be limited to run only on 387 the processors represented in CPUSET. */ 388 extern int pthread_attr_setaffinity_np (pthread_attr_t *__attr, 389 size_t __cpusetsize, 390 __const cpu_set_t *__cpuset) 391 __THROW __nonnull ((1, 3)); 392 393 /* Get bit set in CPUSET representing the processors threads created with 394 ATTR can run on. */ 395 extern int pthread_attr_getaffinity_np (__const pthread_attr_t *__attr, 396 size_t __cpusetsize, 397 cpu_set_t *__cpuset) 398 __THROW __nonnull ((1, 3)); 399 400 401 /* Initialize thread attribute *ATTR with attributes corresponding to the 402 already running thread TH. It shall be called on unitialized ATTR 403 and destroyed with pthread_attr_destroy when no longer needed. */ 404 extern int pthread_getattr_np (pthread_t __th, pthread_attr_t *__attr) 405 __THROW __nonnull ((2)); 406 #endif 407 408 409 /* Functions for scheduling control. */ 410 411 /* Set the scheduling parameters for TARGET_THREAD according to POLICY 412 and *PARAM. */ 413 extern int pthread_setschedparam (pthread_t __target_thread, int __policy, 414 __const struct sched_param *__param) 415 __THROW __nonnull ((3)); 416 417 /* Return in *POLICY and *PARAM the scheduling parameters for TARGET_THREAD. */ 418 extern int pthread_getschedparam (pthread_t __target_thread, 419 int *__restrict __policy, 420 struct sched_param *__restrict __param) 421 __THROW __nonnull ((2, 3)); 422 423 /* Set the scheduling priority for TARGET_THREAD. */ 424 extern int pthread_setschedprio (pthread_t __target_thread, int __prio) 425 __THROW; 426 427 428 #ifdef __USE_UNIX98 429 /* Determine level of concurrency. */ 430 extern int pthread_getconcurrency (void) __THROW; 431 432 /* Set new concurrency level to LEVEL. */ 433 extern int pthread_setconcurrency (int __level) __THROW; 434 #endif 435 436 #ifdef __USE_GNU 437 /* Yield the processor to another thread or process. 438 This function is similar to the POSIX `sched_yield' function but 439 might be differently implemented in the case of a m-on-n thread 440 implementation. */ 441 extern int pthread_yield (void) __THROW; 442 443 444 /* Limit specified thread TH to run only on the processors represented 445 in CPUSET. */ 446 extern int pthread_setaffinity_np (pthread_t __th, size_t __cpusetsize, 447 __const cpu_set_t *__cpuset) 448 __THROW __nonnull ((3)); 449 450 /* Get bit set in CPUSET representing the processors TH can run on. */ 451 extern int pthread_getaffinity_np (pthread_t __th, size_t __cpusetsize, 452 cpu_set_t *__cpuset) 453 __THROW __nonnull ((3)); 454 #endif 455 456 457 /* Functions for handling initialization. */ 458 459 /* Guarantee that the initialization function INIT_ROUTINE will be called 460 only once, even if pthread_once is executed several times with the 461 same ONCE_CONTROL argument. ONCE_CONTROL must point to a static or 462 extern variable initialized to PTHREAD_ONCE_INIT. 463 464 The initialization functions might throw exception which is why 465 this function is not marked with __THROW. */ 466 extern int pthread_once (pthread_once_t *__once_control, 467 void (*__init_routine) (void)) __nonnull ((1, 2)); 468 469 470 /* Functions for handling cancellation. 471 472 Note that these functions are explicitly not marked to not throw an 473 exception in C++ code. If cancellation is implemented by unwinding 474 this is necessary to have the compiler generate the unwind information. */ 475 476 /* Set cancelability state of current thread to STATE, returning old 477 state in *OLDSTATE if OLDSTATE is not NULL. */ 478 extern int pthread_setcancelstate (int __state, int *__oldstate); 479 480 /* Set cancellation state of current thread to TYPE, returning the old 481 type in *OLDTYPE if OLDTYPE is not NULL. */ 482 extern int pthread_setcanceltype (int __type, int *__oldtype); 483 484 /* Cancel THREAD immediately or at the next possibility. */ 485 extern int pthread_cancel (pthread_t __th); 486 487 /* Test for pending cancellation for the current thread and terminate 488 the thread as per pthread_exit(PTHREAD_CANCELED) if it has been 489 cancelled. */ 490 extern void pthread_testcancel (void); 491 492 493 /* Cancellation handling with integration into exception handling. */ 494 495 typedef struct 496 { 497 struct 498 { 499 __jmp_buf __cancel_jmp_buf; 500 int __mask_was_saved; 501 } __cancel_jmp_buf[1]; 502 void *__pad[4]; 503 } __pthread_unwind_buf_t __attribute__ ((__aligned__)); 504 505 /* No special attributes by default. */ 506 #ifndef __cleanup_fct_attribute 507 # define __cleanup_fct_attribute 508 #endif 509 510 511 /* Structure to hold the cleanup handler information. */ 512 struct __pthread_cleanup_frame 513 { 514 void (*__cancel_routine) (void *); 515 void *__cancel_arg; 516 int __do_it; 517 int __cancel_type; 518 }; 519 520 #if defined __GNUC__ && defined __EXCEPTIONS 521 # ifdef __cplusplus 522 /* Class to handle cancellation handler invocation. */ 523 class __pthread_cleanup_class 524 { 525 void (*__cancel_routine) (void *); 526 void *__cancel_arg; 527 int __do_it; 528 int __cancel_type; 529 530 public: 531 __pthread_cleanup_class (void (*__fct) (void *), void *__arg) 532 : __cancel_routine (__fct), __cancel_arg (__arg), __do_it (1) { } 533 ~__pthread_cleanup_class () { if (__do_it) __cancel_routine (__cancel_arg); } 534 void __setdoit (int __newval) { __do_it = __newval; } 535 void __defer () { pthread_setcanceltype (PTHREAD_CANCEL_DEFERRED, 536 &__cancel_type); } 537 void __restore () const { pthread_setcanceltype (__cancel_type, 0); } 538 }; 539 540 /* Install a cleanup handler: ROUTINE will be called with arguments ARG 541 when the thread is canceled or calls pthread_exit. ROUTINE will also 542 be called with arguments ARG when the matching pthread_cleanup_pop 543 is executed with non-zero EXECUTE argument. 544 545 pthread_cleanup_push and pthread_cleanup_pop are macros and must always 546 be used in matching pairs at the same nesting level of braces. */ 547 # define pthread_cleanup_push(routine, arg) \ 548 do { \ 549 __pthread_cleanup_class __clframe (routine, arg) 550 551 /* Remove a cleanup handler installed by the matching pthread_cleanup_push. 552 If EXECUTE is non-zero, the handler function is called. */ 553 # define pthread_cleanup_pop(execute) \ 554 __clframe.__setdoit (execute); \ 555 } while (0) 556 557 # ifdef __USE_GNU 558 /* Install a cleanup handler as pthread_cleanup_push does, but also 559 saves the current cancellation type and sets it to deferred 560 cancellation. */ 561 # define pthread_cleanup_push_defer_np(routine, arg) \ 562 do { \ 563 __pthread_cleanup_class __clframe (routine, arg); \ 564 __clframe.__defer () 565 566 /* Remove a cleanup handler as pthread_cleanup_pop does, but also 567 restores the cancellation type that was in effect when the matching 568 pthread_cleanup_push_defer was called. */ 569 # define pthread_cleanup_pop_restore_np(execute) \ 570 __clframe.__restore (); \ 571 __clframe.__setdoit (execute); \ 572 } while (0) 573 # endif 574 # else 575 /* Function called to call the cleanup handler. As an extern inline 576 function the compiler is free to decide inlining the change when 577 needed or fall back on the copy which must exist somewhere 578 else. */ 579 __extern_inline void 580 __pthread_cleanup_routine (struct __pthread_cleanup_frame *__frame) 581 { 582 if (__frame->__do_it) 583 __frame->__cancel_routine (__frame->__cancel_arg); 584 } 585 586 /* Install a cleanup handler: ROUTINE will be called with arguments ARG 587 when the thread is canceled or calls pthread_exit. ROUTINE will also 588 be called with arguments ARG when the matching pthread_cleanup_pop 589 is executed with non-zero EXECUTE argument. 590 591 pthread_cleanup_push and pthread_cleanup_pop are macros and must always 592 be used in matching pairs at the same nesting level of braces. */ 593 # define pthread_cleanup_push(routine, arg) \ 594 do { \ 595 struct __pthread_cleanup_frame __clframe \ 596 __attribute__ ((__cleanup__ (__pthread_cleanup_routine))) \ 597 = { .__cancel_routine = (routine), .__cancel_arg = (arg), \ 598 .__do_it = 1 }; 599 600 /* Remove a cleanup handler installed by the matching pthread_cleanup_push. 601 If EXECUTE is non-zero, the handler function is called. */ 602 # define pthread_cleanup_pop(execute) \ 603 __clframe.__do_it = (execute); \ 604 } while (0) 605 606 # ifdef __USE_GNU 607 /* Install a cleanup handler as pthread_cleanup_push does, but also 608 saves the current cancellation type and sets it to deferred 609 cancellation. */ 610 # define pthread_cleanup_push_defer_np(routine, arg) \ 611 do { \ 612 struct __pthread_cleanup_frame __clframe \ 613 __attribute__ ((__cleanup__ (__pthread_cleanup_routine))) \ 614 = { .__cancel_routine = (routine), .__cancel_arg = (arg), \ 615 .__do_it = 1 }; \ 616 (void) pthread_setcanceltype (PTHREAD_CANCEL_DEFERRED, \ 617 &__clframe.__cancel_type) 618 619 /* Remove a cleanup handler as pthread_cleanup_pop does, but also 620 restores the cancellation type that was in effect when the matching 621 pthread_cleanup_push_defer was called. */ 622 # define pthread_cleanup_pop_restore_np(execute) \ 623 (void) pthread_setcanceltype (__clframe.__cancel_type, NULL); \ 624 __clframe.__do_it = (execute); \ 625 } while (0) 626 # endif 627 # endif 628 #else 629 /* Install a cleanup handler: ROUTINE will be called with arguments ARG 630 when the thread is canceled or calls pthread_exit. ROUTINE will also 631 be called with arguments ARG when the matching pthread_cleanup_pop 632 is executed with non-zero EXECUTE argument. 633 634 pthread_cleanup_push and pthread_cleanup_pop are macros and must always 635 be used in matching pairs at the same nesting level of braces. */ 636 # define pthread_cleanup_push(routine, arg) \ 637 do { \ 638 __pthread_unwind_buf_t __cancel_buf; \ 639 void (*__cancel_routine) (void *) = (routine); \ 640 void *__cancel_arg = (arg); \ 641 int not_first_call = __sigsetjmp ((struct __jmp_buf_tag *) \ 642 __cancel_buf.__cancel_jmp_buf, 0); \ 643 if (__builtin_expect (not_first_call, 0)) \ 644 { \ 645 __cancel_routine (__cancel_arg); \ 646 __pthread_unwind_next (&__cancel_buf); \ 647 /* NOTREACHED */ \ 648 } \ 649 \ 650 __pthread_register_cancel (&__cancel_buf); \ 651 do { 652 extern void __pthread_register_cancel (__pthread_unwind_buf_t *__buf) 653 __cleanup_fct_attribute; 654 655 /* Remove a cleanup handler installed by the matching pthread_cleanup_push. 656 If EXECUTE is non-zero, the handler function is called. */ 657 # define pthread_cleanup_pop(execute) \ 658 } while (0); \ 659 __pthread_unregister_cancel (&__cancel_buf); \ 660 if (execute) \ 661 __cancel_routine (__cancel_arg); \ 662 } while (0) 663 extern void __pthread_unregister_cancel (__pthread_unwind_buf_t *__buf) 664 __cleanup_fct_attribute; 665 666 # ifdef __USE_GNU 667 /* Install a cleanup handler as pthread_cleanup_push does, but also 668 saves the current cancellation type and sets it to deferred 669 cancellation. */ 670 # define pthread_cleanup_push_defer_np(routine, arg) \ 671 do { \ 672 __pthread_unwind_buf_t __cancel_buf; \ 673 void (*__cancel_routine) (void *) = (routine); \ 674 void *__cancel_arg = (arg); \ 675 int not_first_call = __sigsetjmp ((struct __jmp_buf_tag *) \ 676 __cancel_buf.__cancel_jmp_buf, 0); \ 677 if (__builtin_expect (not_first_call, 0)) \ 678 { \ 679 __cancel_routine (__cancel_arg); \ 680 __pthread_unwind_next (&__cancel_buf); \ 681 /* NOTREACHED */ \ 682 } \ 683 \ 684 __pthread_register_cancel_defer (&__cancel_buf); \ 685 do { 686 extern void __pthread_register_cancel_defer (__pthread_unwind_buf_t *__buf) 687 __cleanup_fct_attribute; 688 689 /* Remove a cleanup handler as pthread_cleanup_pop does, but also 690 restores the cancellation type that was in effect when the matching 691 pthread_cleanup_push_defer was called. */ 692 # define pthread_cleanup_pop_restore_np(execute) \ 693 } while (0); \ 694 __pthread_unregister_cancel_restore (&__cancel_buf); \ 695 if (execute) \ 696 __cancel_routine (__cancel_arg); \ 697 } while (0) 698 extern void __pthread_unregister_cancel_restore (__pthread_unwind_buf_t *__buf) 699 __cleanup_fct_attribute; 700 # endif 701 702 /* Internal interface to initiate cleanup. */ 703 extern void __pthread_unwind_next (__pthread_unwind_buf_t *__buf) 704 __cleanup_fct_attribute __attribute__ ((__noreturn__)) 705 # ifndef SHARED 706 __attribute__ ((__weak__)) 707 # endif 708 ; 709 #endif 710 711 /* Function used in the macros. */ 712 struct __jmp_buf_tag; 713 extern int __sigsetjmp (struct __jmp_buf_tag *__env, int __savemask) __THROW; 714 715 716 /* Mutex handling. */ 717 718 /* Initialize a mutex. */ 719 extern int pthread_mutex_init (pthread_mutex_t *__mutex, 720 __const pthread_mutexattr_t *__mutexattr) 721 __THROW __nonnull ((1)); 722 723 /* Destroy a mutex. */ 724 extern int pthread_mutex_destroy (pthread_mutex_t *__mutex) 725 __THROW __nonnull ((1)); 726 727 /* Try locking a mutex. */ 728 extern int pthread_mutex_trylock (pthread_mutex_t *__mutex) 729 __THROW __nonnull ((1)); 730 731 /* Lock a mutex. */ 732 extern int pthread_mutex_lock (pthread_mutex_t *__mutex) 733 __THROW __nonnull ((1)); 734 735 #ifdef __USE_XOPEN2K 736 /* Wait until lock becomes available, or specified time passes. */ 737 extern int pthread_mutex_timedlock (pthread_mutex_t *__restrict __mutex, 738 __const struct timespec *__restrict 739 __abstime) __THROW __nonnull ((1, 2)); 740 #endif 741 742 /* Unlock a mutex. */ 743 extern int pthread_mutex_unlock (pthread_mutex_t *__mutex) 744 __THROW __nonnull ((1)); 745 746 747 #ifdef __USE_UNIX98 748 /* Get the priority ceiling of MUTEX. */ 749 extern int pthread_mutex_getprioceiling (__const pthread_mutex_t * 750 __restrict __mutex, 751 int *__restrict __prioceiling) 752 __THROW __nonnull ((1, 2)); 753 754 /* Set the priority ceiling of MUTEX to PRIOCEILING, return old 755 priority ceiling value in *OLD_CEILING. */ 756 extern int pthread_mutex_setprioceiling (pthread_mutex_t *__restrict __mutex, 757 int __prioceiling, 758 int *__restrict __old_ceiling) 759 __THROW __nonnull ((1, 3)); 760 #endif 761 762 763 #ifdef __USE_GNU 764 /* Declare the state protected by MUTEX as consistent. */ 765 extern int pthread_mutex_consistent_np (pthread_mutex_t *__mutex) 766 __THROW __nonnull ((1)); 767 #endif 768 769 770 /* Functions for handling mutex attributes. */ 771 772 /* Initialize mutex attribute object ATTR with default attributes 773 (kind is PTHREAD_MUTEX_TIMED_NP). */ 774 extern int pthread_mutexattr_init (pthread_mutexattr_t *__attr) 775 __THROW __nonnull ((1)); 776 777 /* Destroy mutex attribute object ATTR. */ 778 extern int pthread_mutexattr_destroy (pthread_mutexattr_t *__attr) 779 __THROW __nonnull ((1)); 780 781 /* Get the process-shared flag of the mutex attribute ATTR. */ 782 extern int pthread_mutexattr_getpshared (__const pthread_mutexattr_t * 783 __restrict __attr, 784 int *__restrict __pshared) 785 __THROW __nonnull ((1, 2)); 786 787 /* Set the process-shared flag of the mutex attribute ATTR. */ 788 extern int pthread_mutexattr_setpshared (pthread_mutexattr_t *__attr, 789 int __pshared) 790 __THROW __nonnull ((1)); 791 792 #ifdef __USE_UNIX98 793 /* Return in *KIND the mutex kind attribute in *ATTR. */ 794 extern int pthread_mutexattr_gettype (__const pthread_mutexattr_t *__restrict 795 __attr, int *__restrict __kind) 796 __THROW __nonnull ((1, 2)); 797 798 /* Set the mutex kind attribute in *ATTR to KIND (either PTHREAD_MUTEX_NORMAL, 799 PTHREAD_MUTEX_RECURSIVE, PTHREAD_MUTEX_ERRORCHECK, or 800 PTHREAD_MUTEX_DEFAULT). */ 801 extern int pthread_mutexattr_settype (pthread_mutexattr_t *__attr, int __kind) 802 __THROW __nonnull ((1)); 803 804 /* Return in *PROTOCOL the mutex protocol attribute in *ATTR. */ 805 extern int pthread_mutexattr_getprotocol (__const pthread_mutexattr_t * 806 __restrict __attr, 807 int *__restrict __protocol) 808 __THROW __nonnull ((1, 2)); 809 810 /* Set the mutex protocol attribute in *ATTR to PROTOCOL (either 811 PTHREAD_PRIO_NONE, PTHREAD_PRIO_INHERIT, or PTHREAD_PRIO_PROTECT). */ 812 extern int pthread_mutexattr_setprotocol (pthread_mutexattr_t *__attr, 813 int __protocol) 814 __THROW __nonnull ((1)); 815 816 /* Return in *PRIOCEILING the mutex prioceiling attribute in *ATTR. */ 817 extern int pthread_mutexattr_getprioceiling (__const pthread_mutexattr_t * 818 __restrict __attr, 819 int *__restrict __prioceiling) 820 __THROW __nonnull ((1, 2)); 821 822 /* Set the mutex prioceiling attribute in *ATTR to PRIOCEILING. */ 823 extern int pthread_mutexattr_setprioceiling (pthread_mutexattr_t *__attr, 824 int __prioceiling) 825 __THROW __nonnull ((1)); 826 #endif 827 828 #ifdef __USE_GNU 829 /* Get the robustness flag of the mutex attribute ATTR. */ 830 extern int pthread_mutexattr_getrobust_np (__const pthread_mutexattr_t *__attr, 831 int *__robustness) 832 __THROW __nonnull ((1, 2)); 833 834 /* Set the robustness flag of the mutex attribute ATTR. */ 835 extern int pthread_mutexattr_setrobust_np (pthread_mutexattr_t *__attr, 836 int __robustness) 837 __THROW __nonnull ((1)); 838 #endif 839 840 841 #if defined __USE_UNIX98 || defined __USE_XOPEN2K 842 /* Functions for handling read-write locks. */ 843 844 /* Initialize read-write lock RWLOCK using attributes ATTR, or use 845 the default values if later is NULL. */ 846 extern int pthread_rwlock_init (pthread_rwlock_t *__restrict __rwlock, 847 __const pthread_rwlockattr_t *__restrict 848 __attr) __THROW __nonnull ((1)); 849 850 /* Destroy read-write lock RWLOCK. */ 851 extern int pthread_rwlock_destroy (pthread_rwlock_t *__rwlock) 852 __THROW __nonnull ((1)); 853 854 /* Acquire read lock for RWLOCK. */ 855 extern int pthread_rwlock_rdlock (pthread_rwlock_t *__rwlock) 856 __THROW __nonnull ((1)); 857 858 /* Try to acquire read lock for RWLOCK. */ 859 extern int pthread_rwlock_tryrdlock (pthread_rwlock_t *__rwlock) 860 __THROW __nonnull ((1)); 861 862 # ifdef __USE_XOPEN2K 863 /* Try to acquire read lock for RWLOCK or return after specfied time. */ 864 extern int pthread_rwlock_timedrdlock (pthread_rwlock_t *__restrict __rwlock, 865 __const struct timespec *__restrict 866 __abstime) __THROW __nonnull ((1, 2)); 867 # endif 868 869 /* Acquire write lock for RWLOCK. */ 870 extern int pthread_rwlock_wrlock (pthread_rwlock_t *__rwlock) 871 __THROW __nonnull ((1)); 872 873 /* Try to acquire write lock for RWLOCK. */ 874 extern int pthread_rwlock_trywrlock (pthread_rwlock_t *__rwlock) 875 __THROW __nonnull ((1)); 876 877 # ifdef __USE_XOPEN2K 878 /* Try to acquire write lock for RWLOCK or return after specfied time. */ 879 extern int pthread_rwlock_timedwrlock (pthread_rwlock_t *__restrict __rwlock, 880 __const struct timespec *__restrict 881 __abstime) __THROW __nonnull ((1, 2)); 882 # endif 883 884 /* Unlock RWLOCK. */ 885 extern int pthread_rwlock_unlock (pthread_rwlock_t *__rwlock) 886 __THROW __nonnull ((1)); 887 888 889 /* Functions for handling read-write lock attributes. */ 890 891 /* Initialize attribute object ATTR with default values. */ 892 extern int pthread_rwlockattr_init (pthread_rwlockattr_t *__attr) 893 __THROW __nonnull ((1)); 894 895 /* Destroy attribute object ATTR. */ 896 extern int pthread_rwlockattr_destroy (pthread_rwlockattr_t *__attr) 897 __THROW __nonnull ((1)); 898 899 /* Return current setting of process-shared attribute of ATTR in PSHARED. */ 900 extern int pthread_rwlockattr_getpshared (__const pthread_rwlockattr_t * 901 __restrict __attr, 902 int *__restrict __pshared) 903 __THROW __nonnull ((1, 2)); 904 905 /* Set process-shared attribute of ATTR to PSHARED. */ 906 extern int pthread_rwlockattr_setpshared (pthread_rwlockattr_t *__attr, 907 int __pshared) 908 __THROW __nonnull ((1)); 909 910 /* Return current setting of reader/writer preference. */ 911 extern int pthread_rwlockattr_getkind_np (__const pthread_rwlockattr_t * 912 __restrict __attr, 913 int *__restrict __pref) 914 __THROW __nonnull ((1, 2)); 915 916 /* Set reader/write preference. */ 917 extern int pthread_rwlockattr_setkind_np (pthread_rwlockattr_t *__attr, 918 int __pref) __THROW __nonnull ((1)); 919 #endif 920 921 922 /* Functions for handling conditional variables. */ 923 924 /* Initialize condition variable COND using attributes ATTR, or use 925 the default values if later is NULL. */ 926 extern int pthread_cond_init (pthread_cond_t *__restrict __cond, 927 __const pthread_condattr_t *__restrict 928 __cond_attr) __THROW __nonnull ((1)); 929 930 /* Destroy condition variable COND. */ 931 extern int pthread_cond_destroy (pthread_cond_t *__cond) 932 __THROW __nonnull ((1)); 933 934 /* Wake up one thread waiting for condition variable COND. */ 935 extern int pthread_cond_signal (pthread_cond_t *__cond) 936 __THROW __nonnull ((1)); 937 938 /* Wake up all threads waiting for condition variables COND. */ 939 extern int pthread_cond_broadcast (pthread_cond_t *__cond) 940 __THROW __nonnull ((1)); 941 942 /* Wait for condition variable COND to be signaled or broadcast. 943 MUTEX is assumed to be locked before. 944 945 This function is a cancellation point and therefore not marked with 946 __THROW. */ 947 extern int pthread_cond_wait (pthread_cond_t *__restrict __cond, 948 pthread_mutex_t *__restrict __mutex) 949 __nonnull ((1, 2)); 950 951 /* Wait for condition variable COND to be signaled or broadcast until 952 ABSTIME. MUTEX is assumed to be locked before. ABSTIME is an 953 absolute time specification; zero is the beginning of the epoch 954 (00:00:00 GMT, January 1, 1970). 955 956 This function is a cancellation point and therefore not marked with 957 __THROW. */ 958 extern int pthread_cond_timedwait (pthread_cond_t *__restrict __cond, 959 pthread_mutex_t *__restrict __mutex, 960 __const struct timespec *__restrict 961 __abstime) __nonnull ((1, 2, 3)); 962 963 /* Functions for handling condition variable attributes. */ 964 965 /* Initialize condition variable attribute ATTR. */ 966 extern int pthread_condattr_init (pthread_condattr_t *__attr) 967 __THROW __nonnull ((1)); 968 969 /* Destroy condition variable attribute ATTR. */ 970 extern int pthread_condattr_destroy (pthread_condattr_t *__attr) 971 __THROW __nonnull ((1)); 972 973 /* Get the process-shared flag of the condition variable attribute ATTR. */ 974 extern int pthread_condattr_getpshared (__const pthread_condattr_t * 975 __restrict __attr, 976 int *__restrict __pshared) 977 __THROW __nonnull ((1, 2)); 978 979 /* Set the process-shared flag of the condition variable attribute ATTR. */ 980 extern int pthread_condattr_setpshared (pthread_condattr_t *__attr, 981 int __pshared) __THROW __nonnull ((1)); 982 983 #ifdef __USE_XOPEN2K 984 /* Get the clock selected for the conditon variable attribute ATTR. */ 985 extern int pthread_condattr_getclock (__const pthread_condattr_t * 986 __restrict __attr, 987 __clockid_t *__restrict __clock_id) 988 __THROW __nonnull ((1, 2)); 989 990 /* Set the clock selected for the conditon variable attribute ATTR. */ 991 extern int pthread_condattr_setclock (pthread_condattr_t *__attr, 992 __clockid_t __clock_id) 993 __THROW __nonnull ((1)); 994 #endif 995 996 997 #ifdef __USE_XOPEN2K 998 /* Functions to handle spinlocks. */ 999 1000 /* Initialize the spinlock LOCK. If PSHARED is nonzero the spinlock can 1001 be shared between different processes. */ 1002 extern int pthread_spin_init (pthread_spinlock_t *__lock, int __pshared) 1003 __THROW __nonnull ((1)); 1004 1005 /* Destroy the spinlock LOCK. */ 1006 extern int pthread_spin_destroy (pthread_spinlock_t *__lock) 1007 __THROW __nonnull ((1)); 1008 1009 /* Wait until spinlock LOCK is retrieved. */ 1010 extern int pthread_spin_lock (pthread_spinlock_t *__lock) 1011 __THROW __nonnull ((1)); 1012 1013 /* Try to lock spinlock LOCK. */ 1014 extern int pthread_spin_trylock (pthread_spinlock_t *__lock) 1015 __THROW __nonnull ((1)); 1016 1017 /* Release spinlock LOCK. */ 1018 extern int pthread_spin_unlock (pthread_spinlock_t *__lock) 1019 __THROW __nonnull ((1)); 1020 1021 1022 /* Functions to handle barriers. */ 1023 1024 /* Initialize BARRIER with the attributes in ATTR. The barrier is 1025 opened when COUNT waiters arrived. */ 1026 extern int pthread_barrier_init (pthread_barrier_t *__restrict __barrier, 1027 __const pthread_barrierattr_t *__restrict 1028 __attr, unsigned int __count) 1029 __THROW __nonnull ((1)); 1030 1031 /* Destroy a previously dynamically initialized barrier BARRIER. */ 1032 extern int pthread_barrier_destroy (pthread_barrier_t *__barrier) 1033 __THROW __nonnull ((1)); 1034 1035 /* Wait on barrier BARRIER. */ 1036 extern int pthread_barrier_wait (pthread_barrier_t *__barrier) 1037 __THROW __nonnull ((1)); 1038 1039 1040 /* Initialize barrier attribute ATTR. */ 1041 extern int pthread_barrierattr_init (pthread_barrierattr_t *__attr) 1042 __THROW __nonnull ((1)); 1043 1044 /* Destroy previously dynamically initialized barrier attribute ATTR. */ 1045 extern int pthread_barrierattr_destroy (pthread_barrierattr_t *__attr) 1046 __THROW __nonnull ((1)); 1047 1048 /* Get the process-shared flag of the barrier attribute ATTR. */ 1049 extern int pthread_barrierattr_getpshared (__const pthread_barrierattr_t * 1050 __restrict __attr, 1051 int *__restrict __pshared) 1052 __THROW __nonnull ((1, 2)); 1053 1054 /* Set the process-shared flag of the barrier attribute ATTR. */ 1055 extern int pthread_barrierattr_setpshared (pthread_barrierattr_t *__attr, 1056 int __pshared) 1057 __THROW __nonnull ((1)); 1058 #endif 1059 1060 1061 /* Functions for handling thread-specific data. */ 1062 1063 /* Create a key value identifying a location in the thread-specific 1064 data area. Each thread maintains a distinct thread-specific data 1065 area. DESTR_FUNCTION, if non-NULL, is called with the value 1066 associated to that key when the key is destroyed. 1067 DESTR_FUNCTION is not called if the value associated is NULL when 1068 the key is destroyed. */ 1069 extern int pthread_key_create (pthread_key_t *__key, 1070 void (*__destr_function) (void *)) 1071 __THROW __nonnull ((1)); 1072 1073 /* Destroy KEY. */ 1074 extern int pthread_key_delete (pthread_key_t __key) __THROW; 1075 1076 /* Return current value of the thread-specific data slot identified by KEY. */ 1077 extern void *pthread_getspecific (pthread_key_t __key) __THROW; 1078 1079 /* Store POINTER in the thread-specific data slot identified by KEY. */ 1080 extern int pthread_setspecific (pthread_key_t __key, 1081 __const void *__pointer) __THROW ; 1082 1083 1084 #ifdef __USE_XOPEN2K 1085 /* Get ID of CPU-time clock for thread THREAD_ID. */ 1086 extern int pthread_getcpuclockid (pthread_t __thread_id, 1087 __clockid_t *__clock_id) 1088 __THROW __nonnull ((2)); 1089 #endif 1090 1091 1092 /* Install handlers to be called when a new process is created with FORK. 1093 The PREPARE handler is called in the parent process just before performing 1094 FORK. The PARENT handler is called in the parent process just after FORK. 1095 The CHILD handler is called in the child process. Each of the three 1096 handlers can be NULL, meaning that no handler needs to be called at that 1097 point. 1098 PTHREAD_ATFORK can be called several times, in which case the PREPARE 1099 handlers are called in LIFO order (last added with PTHREAD_ATFORK, 1100 first called before FORK), and the PARENT and CHILD handlers are called 1101 in FIFO (first added, first called). */ 1102 1103 extern int pthread_atfork (void (*__prepare) (void), 1104 void (*__parent) (void), 1105 void (*__child) (void)) __THROW; 1106 1107 1108 #ifdef __USE_EXTERN_INLINES 1109 /* Optimizations. */ 1110 __extern_inline int 1111 __NTH (pthread_equal (pthread_t __thread1, pthread_t __thread2)) 1112 { 1113 return __thread1 == __thread2; 1114 } 1115 #endif 1116 1117 __END_DECLS 1118 1119 #endif /* pthread.h */ 1120
