1 /* Linuxthreads - a simple clone()-based implementation of Posix */
2 /* threads for Linux. */
3 /* Copyright (C) 1996 Xavier Leroy (Xavier.Leroy@inria.fr) */
5 /* This program is free software; you can redistribute it and/or */
6 /* modify it under the terms of the GNU Library General Public License */
7 /* as published by the Free Software Foundation; either version 2 */
8 /* of the License, or (at your option) any later version. */
10 /* This program 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 */
13 /* GNU Library General Public License for more details. */
25 #define __need_sigset_t
27 #define __need_timespec
30 /* Linux has no ENOTSUP error code. */
32 #define ENOTSUP EOPNOTSUPP
40 /* Thread identifiers */
41 typedef unsigned long int pthread_t;
43 /* Thread descriptors */
44 typedef struct _pthread_descr_struct *_pthread_descr;
46 /* Fast locks (not abstract because mutexes and conditions aren't abstract). */
47 struct _pthread_fastlock
49 long int status; /* "Free" or "taken" or head of waiting list */
50 int spinlock; /* For compare-and-swap emulation */
53 /* Mutexes (not abstract because of PTHREAD_MUTEX_INITIALIZER). */
54 /* (The layout is unnatural to maintain binary compatibility
55 with earlier releases of LinuxThreads.) */
59 int m_reserved; /* Reserved for future use */
60 int m_count; /* Depth of recursive locking */
61 _pthread_descr m_owner; /* Owner thread (if recursive or errcheck) */
62 int m_kind; /* Mutex kind: fast, recursive or errcheck */
63 struct _pthread_fastlock m_lock; /* Underlying fast lock */
66 #define PTHREAD_MUTEX_INITIALIZER \
67 {0, 0, 0, PTHREAD_MUTEX_FAST_NP, {0, 0}}
68 #define PTHREAD_RECURSIVE_MUTEX_INITIALIZER_NP \
69 {0, 0, 0, PTHREAD_MUTEX_RECURSIVE_NP, {0, 0}}
71 /* Conditions (not abstract because of PTHREAD_COND_INITIALIZER */
74 struct _pthread_fastlock c_lock; /* Protect against concurrent access */
75 _pthread_descr c_waiting; /* Threads waiting on this condition */
78 #define PTHREAD_COND_INITIALIZER {{0, 0}, 0}
81 /* Read-write locks. */
84 struct _pthread_fastlock rw_lock; /* Lock to guarantee mutual exclusion */
85 int rw_readers; /* Number of readers */
86 _pthread_descr rw_writer; /* Identity of writer, or NULL if none */
87 _pthread_descr rw_read_waiting; /* Threads waiting for reading */
88 _pthread_descr rw_write_waiting; /* Threads waiting for writing */
89 int rw_kind; /* Reader/Writer preference selection */
90 int rw_pshared; /* Shared between processes or not */
93 # define PTHREAD_RWLOCK_INITIALIZER \
94 { {0, 0}, 0, NULL, NULL, NULL, \
95 PTHREAD_RWLOCK_DEFAULT_NP, PTHREAD_PROCESS_PRIVATE }
102 PTHREAD_CREATE_JOINABLE,
103 PTHREAD_CREATE_DETACHED
108 PTHREAD_INHERIT_SCHED,
109 PTHREAD_EXPLICIT_SCHED
114 PTHREAD_SCOPE_SYSTEM,
115 PTHREAD_SCOPE_PROCESS
122 struct sched_param schedparam;
133 PTHREAD_MUTEX_FAST_NP,
134 PTHREAD_MUTEX_RECURSIVE_NP,
135 PTHREAD_MUTEX_ERRORCHECK_NP
138 PTHREAD_MUTEX_NORMAL = PTHREAD_MUTEX_FAST_NP,
139 PTHREAD_MUTEX_RECURSIVE = PTHREAD_MUTEX_RECURSIVE_NP,
140 PTHREAD_MUTEX_ERRORCHECK = PTHREAD_MUTEX_ERRORCHECK_NP,
141 PTHREAD_MUTEX_DEFAULT = PTHREAD_MUTEX_NORMAL
148 } pthread_mutexattr_t;
153 } pthread_condattr_t;
158 PTHREAD_PROCESS_PRIVATE,
159 PTHREAD_PROCESS_SHARED
164 PTHREAD_RWLOCK_PREFER_READER_NP,
165 PTHREAD_RWLOCK_PREFER_WRITER_NP,
166 PTHREAD_RWLOCK_DEFAULT_NP = PTHREAD_RWLOCK_PREFER_WRITER_NP
173 } pthread_rwlockattr_t;
176 /* Keys for thread-specific data */
178 typedef unsigned int pthread_key_t;
180 /* Once-only execution */
182 typedef int pthread_once_t;
184 #define PTHREAD_ONCE_INIT 0
186 /* Cleanup buffers */
188 struct _pthread_cleanup_buffer
190 void (*routine) __P ((void *)); /* Function to call. */
191 void *arg; /* Its argument. */
192 int canceltype; /* Saved cancellation type. */
193 struct _pthread_cleanup_buffer *prev; /* Chaining of cleanup functions. */
198 enum { PTHREAD_CANCEL_ENABLE, PTHREAD_CANCEL_DISABLE };
199 enum { PTHREAD_CANCEL_DEFERRED, PTHREAD_CANCEL_ASYNCHRONOUS };
200 #define PTHREAD_CANCELED ((void *) -1)
203 /* Function for handling threads. */
205 /* Create a thread with given attributes ATTR (or default attributes
206 if ATTR is NULL), and call function START_ROUTINE with given
208 extern int pthread_create __P ((pthread_t *__thread,
209 __const pthread_attr_t *__attr,
210 void *(*__start_routine) (void *),
213 /* Obtain the identifier of the current thread. */
214 extern pthread_t pthread_self __P ((void));
216 /* Compare two thread identifiers. */
217 extern int pthread_equal __P ((pthread_t __thread1, pthread_t __thread2));
219 /* Terminate calling thread. */
220 extern void pthread_exit __P ((void *__retval)) __attribute__ ((__noreturn__));
222 /* Make calling thread wait for termination of the thread TH. The
223 exit status of the thread is stored in *THREAD_RETURN, if THREAD_RETURN
225 extern int pthread_join __P ((pthread_t __th, void **__thread_return));
227 /* Indicate that the thread TH is never to be joined with PTHREAD_JOIN.
228 The resources of TH will therefore be freed immediately when it
229 terminates, instead of waiting for another thread to perform PTHREAD_JOIN
231 extern int pthread_detach __P ((pthread_t __th));
234 /* Functions for handling attributes. */
236 /* Initialize thread attribute *ATTR with default attributes
237 (detachstate is PTHREAD_JOINABLE, scheduling policy is SCHED_OTHER,
238 no user-provided stack). */
239 extern int pthread_attr_init __P ((pthread_attr_t *__attr));
241 /* Destroy thread attribute *ATTR. */
242 extern int pthread_attr_destroy __P ((pthread_attr_t *__attr));
244 /* Set the `detachstate' attribute in *ATTR according to DETACHSTATE. */
245 extern int pthread_attr_setdetachstate __P ((pthread_attr_t *__attr,
248 /* Return in *DETACHSTATE the `detachstate' attribute in *ATTR. */
249 extern int pthread_attr_getdetachstate __P ((__const pthread_attr_t *__attr,
250 int *__detachstate));
252 /* Set scheduling parameters (priority, etc) in *ATTR according to PARAM. */
253 extern int pthread_attr_setschedparam __P ((pthread_attr_t *__attr,
254 __const struct sched_param *__param));
256 /* Return in *PARAM the scheduling parameters of *ATTR. */
257 extern int pthread_attr_getschedparam __P ((__const pthread_attr_t *__attr,
258 struct sched_param *__param));
260 /* Set scheduling policy in *ATTR according to POLICY. */
261 extern int pthread_attr_setschedpolicy __P ((pthread_attr_t *__attr,
264 /* Return in *POLICY the scheduling policy of *ATTR. */
265 extern int pthread_attr_getschedpolicy __P ((__const pthread_attr_t *__attr,
268 /* Set scheduling inheritance mode in *ATTR according to INHERIT. */
269 extern int pthread_attr_setinheritsched __P ((pthread_attr_t *__attr,
272 /* Return in *INHERIT the scheduling inheritance mode of *ATTR. */
273 extern int pthread_attr_getinheritsched __P ((__const pthread_attr_t *__attr,
276 /* Set scheduling contention scope in *ATTR according to SCOPE. */
277 extern int pthread_attr_setscope __P ((pthread_attr_t *__attr, int __scope));
279 /* Return in *SCOPE the scheduling contention scope of *ATTR. */
280 extern int pthread_attr_getscope __P ((__const pthread_attr_t *__attr,
284 /* Set the size of the guard area at the bottom of the thread. */
285 extern int __pthread_attr_setguardsize __P ((pthread_attr_t *__attr,
286 size_t __guardsize));
287 extern int pthread_attr_setguardsize __P ((pthread_attr_t *__attr,
288 size_t __guardsize));
290 /* Get the size of the guard area at the bottom of the thread. */
291 extern int __pthread_attr_getguardsize __P ((__const pthread_attr_t *__attr,
292 size_t *__guardsize));
293 extern int pthread_attr_getguardsize __P ((__const pthread_attr_t *__attr,
294 size_t *__guardsize));
297 /* Set the starting address of the stack of the thread to be created.
298 Depending on whether the stack grows up or doen the value must either
299 be higher or lower than all the address in the memory block. The
300 minimal size of the block must be PTHREAD_STACK_SIZE. */
301 extern int __pthread_attr_setstackaddr __P ((pthread_attr_t *__attr,
303 extern int pthread_attr_setstackaddr __P ((pthread_attr_t *__attr,
306 /* Return the previously set address for the stack. */
307 extern int __pthread_attr_getstackaddr __P ((__const pthread_attr_t *__attr,
308 void **__stackaddr));
309 extern int pthread_attr_getstackaddr __P ((__const pthread_attr_t *__attr,
310 void **__stackaddr));
312 /* Add information about the minimum stack size needed for the thread
313 to be started. This size must never be less than PTHREAD_STACK_SIZE
314 and must also not exceed the system limits. */
315 extern int __pthread_attr_setstacksize __P ((pthread_attr_t *__attr,
316 size_t __stacksize));
317 extern int pthread_attr_setstacksize __P ((pthread_attr_t *__attr,
318 size_t __stacksize));
320 /* Return the currently used minimal stack size. */
321 extern int __pthread_attr_getstacksize __P ((__const pthread_attr_t *__attr,
322 size_t *__stacksize));
323 extern int pthread_attr_getstacksize __P ((__const pthread_attr_t *__attr,
324 size_t *__stacksize));
326 /* Functions for scheduling control. */
328 /* Set the scheduling parameters for TARGET_THREAD according to POLICY
330 extern int pthread_setschedparam __P ((pthread_t __target_thread, int __policy,
331 __const struct sched_param *__param));
333 /* Return in *POLICY and *PARAM the scheduling parameters for TARGET_THREAD. */
334 extern int pthread_getschedparam __P ((pthread_t __target_thread,
336 struct sched_param *__param));
339 /* Determine level of concurrency. */
340 extern int __pthread_getconcurrency __P ((void));
341 extern int pthread_getconcurrency __P ((void));
343 /* Set new concurrency level to LEVEL. */
344 extern int __pthread_setconcurrency __P ((int __level));
345 extern int pthread_setconcurrency __P ((int __level));
348 /* Functions for mutex handling. */
350 /* Initialize MUTEX using attributes in *MUTEX_ATTR, or use the
351 default values if later is NULL. */
352 extern int __pthread_mutex_init __P ((pthread_mutex_t *__mutex,
353 __const pthread_mutexattr_t *__mutex_attr));
354 extern int pthread_mutex_init __P ((pthread_mutex_t *__mutex,
355 __const pthread_mutexattr_t *__mutex_attr));
358 extern int __pthread_mutex_destroy __P ((pthread_mutex_t *__mutex));
359 extern int pthread_mutex_destroy __P ((pthread_mutex_t *__mutex));
361 /* Try to lock MUTEX. */
362 extern int __pthread_mutex_trylock __P ((pthread_mutex_t *__mutex));
363 extern int pthread_mutex_trylock __P ((pthread_mutex_t *__mutex));
365 /* Wait until lock for MUTEX becomes available and lock it. */
366 extern int __pthread_mutex_lock __P ((pthread_mutex_t *__mutex));
367 extern int pthread_mutex_lock __P ((pthread_mutex_t *__mutex));
370 extern int __pthread_mutex_unlock __P ((pthread_mutex_t *__mutex));
371 extern int pthread_mutex_unlock __P ((pthread_mutex_t *__mutex));
374 /* Functions for handling mutex attributes. */
376 /* Initialize mutex attribute object ATTR with default attributes
377 (kind is PTHREAD_MUTEX_FAST_NP). */
378 extern int __pthread_mutexattr_init __P ((pthread_mutexattr_t *__attr));
379 extern int pthread_mutexattr_init __P ((pthread_mutexattr_t *__attr));
381 /* Destroy mutex attribute object ATTR. */
382 extern int __pthread_mutexattr_destroy __P ((pthread_mutexattr_t *__attr));
383 extern int pthread_mutexattr_destroy __P ((pthread_mutexattr_t *__attr));
385 /* Set the mutex kind attribute in *ATTR to KIND (either PTHREAD_MUTEX_FAST_NP
386 or PTHREAD_MUTEX_RECURSIVE_NP). */
387 extern int __pthread_mutexattr_setkind_np __P ((pthread_mutexattr_t *__attr,
389 extern int pthread_mutexattr_setkind_np __P ((pthread_mutexattr_t *__attr,
391 /* Return in *KIND the mutex kind attribute in *ATTR. */
392 extern int pthread_mutexattr_getkind_np __P ((__const pthread_mutexattr_t *__attr,
396 /* Functions for handling conditional variables. */
398 /* Initialize condition variable COND using attributes ATTR, or use
399 the default values if later is NULL. */
400 extern int pthread_cond_init __P ((pthread_cond_t *__cond,
401 __const pthread_condattr_t *__cond_attr));
403 /* Destroy condition variable COND. */
404 extern int pthread_cond_destroy __P ((pthread_cond_t *__cond));
406 /* Wake up one thread waiting for condition variable COND. */
407 extern int pthread_cond_signal __P ((pthread_cond_t *__cond));
409 /* Wake up all threads waiting for condition variables COND. */
410 extern int pthread_cond_broadcast __P ((pthread_cond_t *__cond));
412 /* Wait for condition variable COND to be signaled or broadcast.
413 MUTEX is assumed to be locked before. */
414 extern int pthread_cond_wait __P ((pthread_cond_t *__cond,
415 pthread_mutex_t *__mutex));
417 /* Wait for condition variable COND to be signaled or broadcast until
418 ABSTIME. MUTEX is assumed to be locked before. ABSTIME is an
419 absolute time specification; zero is the beginning of the epoch
420 (00:00:00 GMT, January 1, 1970). */
421 extern int pthread_cond_timedwait __P ((pthread_cond_t *__cond,
422 pthread_mutex_t *__mutex,
423 __const struct timespec *__abstime));
425 /* Functions for handling condition variable attributes. */
427 /* Initialize condition variable attribute ATTR. */
428 extern int pthread_condattr_init __P ((pthread_condattr_t *__attr));
430 /* Destroy condition variable attribute ATTR. */
431 extern int pthread_condattr_destroy __P ((pthread_condattr_t *__attr));
435 /* Functions for handling read-write locks. */
437 /* Initialize read-write lock RWLOCK using attributes ATTR, or use
438 the default values if later is NULL. */
439 extern int pthread_rwlock_init __P ((pthread_rwlock_t *__rwlock,
440 __const pthread_rwlockattr_t *__attr));
442 /* Destroy read-write lock RWLOCK. */
443 extern int pthread_rwlock_destroy __P ((pthread_rwlock_t *__rwlock));
445 /* Acquire read lock for RWLOCK. */
446 extern int pthread_rwlock_rdlock __P ((pthread_rwlock_t *__rwlock));
448 /* Try to acquire read lock for RWLOCK. */
449 extern int pthread_rwlock_tryrdlock __P ((pthread_rwlock_t *__rwlock));
451 /* Acquire write lock for RWLOCK. */
452 extern int pthread_rwlock_wrlock __P ((pthread_rwlock_t *__rwlock));
454 /* Try to acquire writelock for RWLOCK. */
455 extern int pthread_rwlock_trywrlock __P ((pthread_rwlock_t *__rwlock));
458 extern int pthread_rwlock_unlock __P ((pthread_rwlock_t *__rwlock));
461 /* Functions for handling read-write lock attributes. */
463 /* Initialize attribute object ATTR with default values. */
464 extern int pthread_rwlockattr_init __P ((pthread_rwlockattr_t *__attr));
466 /* Destroy attribute object ATTR. */
467 extern int pthread_rwlockattr_destroy __P ((pthread_rwlockattr_t *__attr));
469 /* Return current setting of process-shared attribute of ATTR in PSHARED. */
470 extern int pthread_rwlockattr_getpshared __P ((__const
471 pthread_rwlockattr_t *__attr,
474 /* Set process-shared attribute of ATTR to PSHARED. */
475 extern int pthread_rwlockattr_setpshared __P ((pthread_rwlockattr_t *__attr,
478 /* Return current setting of reader/writer preference. */
479 extern int pthread_rwlockattr_getkind_np __P ((__const
480 pthread_rwlockattr_t *__attr,
483 /* Set reader/write preference. */
484 extern int pthread_rwlockattr_setkind_np __P ((pthread_rwlockattr_t *__attr,
489 /* Functions for handling thread-specific data */
491 /* Create a key value identifying a location in the thread-specific data
492 area. Each thread maintains a distinct thread-specific data area.
493 DESTR_FUNCTION, if non-NULL, is called with
494 the value associated to that key when the key is destroyed.
495 DESTR_FUNCTION is not called if the value associated is NULL
496 when the key is destroyed. */
497 extern int __pthread_key_create __P ((pthread_key_t *__key,
498 void (*__destr_function) (void *)));
499 extern int pthread_key_create __P ((pthread_key_t *__key,
500 void (*__destr_function) (void *)));
503 extern int pthread_key_delete __P ((pthread_key_t __key));
505 /* Store POINTER in the thread-specific data slot identified by KEY. */
506 extern int __pthread_setspecific __P ((pthread_key_t __key,
507 __const void *__pointer));
508 extern int pthread_setspecific __P ((pthread_key_t __key,
509 __const void *__pointer));
511 /* Return current value of the thread-specific data slot identified by KEY. */
512 extern void *__pthread_getspecific __P ((pthread_key_t __key));
513 extern void *pthread_getspecific __P ((pthread_key_t __key));
516 /* Functions for handling initialization */
518 /* Guarantee that the initialization function INIT_ROUTINE will be called
519 only once, even if pthread_once is executed several times with the
520 same ONCE_CONTROL argument. ONCE_CONTROL must point to a static or
521 extern variable initialized to PTHREAD_ONCE_INIT. */
522 extern int __pthread_once __P ((pthread_once_t *__once_control,
523 void (*__init_routine) (void)));
524 extern int pthread_once __P ((pthread_once_t *__once_control,
525 void (*__init_routine) (void)));
528 /* Functions for handling cancellation. */
530 /* Set cancelability state of current thread to STATE, returning old
531 state in *OLDSTATE if OLDSTATE is not NULL. */
532 extern int pthread_setcancelstate __P ((int __state, int *__oldstate));
534 /* Set cancellation state of current thread to TYPE, returning the old
535 type in *OLDTYPE if OLDTYPE is not NULL. */
536 extern int __pthread_setcanceltype __P ((int __type, int *__oldtype));
537 extern int pthread_setcanceltype __P ((int __type, int *__oldtype));
539 /* Cancel THREAD immediately or at the next possibility. */
540 extern int pthread_cancel __P ((pthread_t __thread));
542 /* Test for pending cancellation for the current thread and terminate
543 the thread as per pthread_exit(PTHREAD_CANCELED) if it has been
545 extern void pthread_testcancel __P ((void));
548 /* Install a cleanup handler: ROUTINE will be called with arguments ARG
549 when the thread is cancelled or calls pthread_exit. ROUTINE will also
550 be called with arguments ARG when the matching pthread_cleanup_pop
551 is executed with non-zero EXECUTE argument.
552 pthread_cleanup_push and pthread_cleanup_pop are macros and must always
553 be used in matching pairs at the same nesting level of braces. */
555 #define pthread_cleanup_push(routine,arg) \
556 { struct _pthread_cleanup_buffer _buffer; \
557 _pthread_cleanup_push (&_buffer, (routine), (arg));
559 extern void _pthread_cleanup_push __P ((struct _pthread_cleanup_buffer *__buffer,
560 void (*__routine) (void *),
563 /* Remove a cleanup handler installed by the matching pthread_cleanup_push.
564 If EXECUTE is non-zero, the handler function is called. */
566 #define pthread_cleanup_pop(execute) \
567 _pthread_cleanup_pop (&_buffer, (execute)); }
569 extern void _pthread_cleanup_pop __P ((struct _pthread_cleanup_buffer *__buffer,
572 /* Install a cleanup handler as pthread_cleanup_push does, but also
573 saves the current cancellation type and set it to deferred cancellation. */
575 #define pthread_cleanup_push_defer_np(routine,arg) \
576 { struct _pthread_cleanup_buffer _buffer; \
577 _pthread_cleanup_push_defer (&_buffer, (routine), (arg));
579 extern void _pthread_cleanup_push_defer __P ((struct _pthread_cleanup_buffer *__buffer,
580 void (*__routine) (void *),
583 /* Remove a cleanup handler as pthread_cleanup_pop does, but also
584 restores the cancellation type that was in effect when the matching
585 pthread_cleanup_push_defer was called. */
587 #define pthread_cleanup_pop_restore_np(execute) \
588 _pthread_cleanup_pop_restore (&_buffer, (execute)); }
590 extern void _pthread_cleanup_pop_restore __P ((struct _pthread_cleanup_buffer *__buffer,
593 /* Functions for handling signals. */
595 /* Modify the signal mask for the calling thread. The arguments have
596 the same meaning as for sigprocmask(2). */
598 extern int pthread_sigmask __P ((int __how, __const sigset_t *__newmask,
599 sigset_t *__oldmask));
601 /* Send signal SIGNO to the given thread. */
603 extern int pthread_kill __P ((pthread_t __thread, int __signo));
606 /* Functions for handling process creation and process execution. */
608 /* Install handlers to be called when a new process is created with FORK.
609 The PREPARE handler is called in the parent process just before performing
610 FORK. The PARENT handler is called in the parent process just after FORK.
611 The CHILD handler is called in the child process. Each of the three
612 handlers can be NULL, meaning that no handler needs to be called at that
614 PTHREAD_ATFORK can be called several times, in which case the PREPARE
615 handlers are called in LIFO order (last added with PTHREAD_ATFORK,
616 first called before FORK), and the PARENT and CHILD handlers are called
617 in FIFO (first added, first called). */
619 extern int __pthread_atfork __P ((void (*__prepare) (void),
620 void (*__parent) (void),
621 void (*__child) (void)));
622 extern int pthread_atfork __P ((void (*__prepare) (void),
623 void (*__parent) (void),
624 void (*__child) (void)));
626 /* Terminate all threads in the program except the calling process.
627 Should be called just before invoking one of the exec*() functions. */
629 extern void __pthread_kill_other_threads_np __P ((void));
630 extern void pthread_kill_other_threads_np __P ((void));
633 /* This function is called to initialize the pthread library. */
634 extern void __pthread_initialize __P ((void));
638 #endif /* pthread.h */