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