1/* ISO C11 Standard: 7.26 - Thread support library <threads.h>.
2 Copyright (C) 2018-2020 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, see
17 <https://www.gnu.org/licenses/>. */
18
19#ifndef _THREADS_H
20#define _THREADS_H 1
21
22#include <features.h>
23#include <time.h>
24
25__BEGIN_DECLS
26
27#include <bits/pthreadtypes-arch.h>
28#include <bits/types/struct_timespec.h>
29
30#ifndef __cplusplus
31# define thread_local _Thread_local
32#endif
33
34#define TSS_DTOR_ITERATIONS 4
35typedef unsigned int tss_t;
36typedef void (*tss_dtor_t) (void*);
37
38typedef unsigned long int thrd_t;
39typedef int (*thrd_start_t) (void*);
40
41/* Exit and error codes. */
42enum
43{
44 thrd_success = 0,
45 thrd_busy = 1,
46 thrd_error = 2,
47 thrd_nomem = 3,
48 thrd_timedout = 4
49};
50
51/* Mutex types. */
52enum
53{
54 mtx_plain = 0,
55 mtx_recursive = 1,
56 mtx_timed = 2
57};
58
59typedef struct
60{
61 int __data __ONCE_ALIGNMENT;
62} once_flag;
63#define ONCE_FLAG_INIT { 0 }
64
65typedef union
66{
67 char __size[__SIZEOF_PTHREAD_MUTEX_T];
68 long int __align __LOCK_ALIGNMENT;
69} mtx_t;
70
71typedef union
72{
73 char __size[__SIZEOF_PTHREAD_COND_T];
74 __extension__ long long int __align __LOCK_ALIGNMENT;
75} cnd_t;
76
77/* Threads functions. */
78
79/* Create a new thread executing the function __FUNC. Arguments for __FUNC
80 are passed through __ARG. If succesful, __THR is set to new thread
81 identifier. */
82extern int thrd_create (thrd_t *__thr, thrd_start_t __func, void *__arg);
83
84/* Check if __LHS and __RHS point to the same thread. */
85extern int thrd_equal (thrd_t __lhs, thrd_t __rhs);
86
87/* Return current thread identifier. */
88extern thrd_t thrd_current (void);
89
90/* Block current thread execution for at least the time pointed by
91 __TIME_POINT. The current thread may resume if receives a signal. In
92 that case, if __REMAINING is not NULL, the remaining time is stored in
93 the object pointed by it. */
94extern int thrd_sleep (const struct timespec *__time_point,
95 struct timespec *__remaining);
96
97/* Terminate current thread execution, cleaning up any thread local
98 storage and freeing resources. Returns the value specified in __RES. */
99extern void thrd_exit (int __res) __attribute__ ((__noreturn__));
100
101/* Detach the thread identified by __THR from the current environment
102 (it does not allow join or wait for it). */
103extern int thrd_detach (thrd_t __thr);
104
105/* Block current thread until execution of __THR is complete. In case that
106 __RES is not NULL, will store the return value of __THR when exiting. */
107extern int thrd_join (thrd_t __thr, int *__res);
108
109/* Stop current thread execution and call the scheduler to decide which
110 thread should execute next. The current thread may be selected by the
111 scheduler to keep running. */
112extern void thrd_yield (void);
113
114#ifdef __USE_EXTERN_INLINES
115/* Optimizations. */
116__extern_inline int
117thrd_equal (thrd_t __thread1, thrd_t __thread2)
118{
119 return __thread1 == __thread2;
120}
121#endif
122
123
124/* Mutex functions. */
125
126/* Creates a new mutex object with type __TYPE. If successful the new
127 object is pointed by __MUTEX. */
128extern int mtx_init (mtx_t *__mutex, int __type);
129
130/* Block the current thread until the mutex pointed to by __MUTEX is
131 unlocked. In that case current thread will not be blocked. */
132extern int mtx_lock (mtx_t *__mutex);
133
134/* Block the current thread until the mutex pointed by __MUTEX is unlocked
135 or time pointed by __TIME_POINT is reached. In case the mutex is unlock,
136 the current thread will not be blocked. */
137extern int mtx_timedlock (mtx_t *__restrict __mutex,
138 const struct timespec *__restrict __time_point);
139
140/* Try to lock the mutex pointed by __MUTEX without blocking. If the mutex
141 is free the current threads takes control of it, otherwise it returns
142 immediately. */
143extern int mtx_trylock (mtx_t *__mutex);
144
145/* Unlock the mutex pointed by __MUTEX. It may potentially awake other
146 threads waiting on this mutex. */
147extern int mtx_unlock (mtx_t *__mutex);
148
149/* Destroy the mutex object pointed by __MUTEX. */
150extern void mtx_destroy (mtx_t *__mutex);
151
152
153/* Call function __FUNC exactly once, even if invoked from several threads.
154 All calls must be made with the same __FLAGS object. */
155extern void call_once (once_flag *__flag, void (*__func)(void));
156
157
158/* Condition variable functions. */
159
160/* Initialize new condition variable pointed by __COND. */
161extern int cnd_init (cnd_t *__cond);
162
163/* Unblock one thread that currently waits on condition variable pointed
164 by __COND. */
165extern int cnd_signal (cnd_t *__cond);
166
167/* Unblock all threads currently waiting on condition variable pointed by
168 __COND. */
169extern int cnd_broadcast (cnd_t *__cond);
170
171/* Block current thread on the condition variable pointed by __COND. */
172extern int cnd_wait (cnd_t *__cond, mtx_t *__mutex);
173
174/* Block current thread on the condition variable until condition variable
175 pointed by __COND is signaled or time pointed by __TIME_POINT is
176 reached. */
177extern int cnd_timedwait (cnd_t *__restrict __cond,
178 mtx_t *__restrict __mutex,
179 const struct timespec *__restrict __time_point);
180
181/* Destroy condition variable pointed by __cond and free all of its
182 resources. */
183extern void cnd_destroy (cnd_t *__COND);
184
185
186/* Thread specific storage functions. */
187
188/* Create new thread-specific storage key and stores it in the object pointed
189 by __TSS_ID. If __DESTRUCTOR is not NULL, the function will be called when
190 the thread terminates. */
191extern int tss_create (tss_t *__tss_id, tss_dtor_t __destructor);
192
193/* Return the value held in thread-specific storage for the current thread
194 identified by __TSS_ID. */
195extern void *tss_get (tss_t __tss_id);
196
197/* Sets the value of the thread-specific storage identified by __TSS_ID for
198 the current thread to __VAL. */
199extern int tss_set (tss_t __tss_id, void *__val);
200
201/* Destroys the thread-specific storage identified by __TSS_ID. The
202 destructor is not called until thrd_exit is called. */
203extern void tss_delete (tss_t __tss_id);
204
205__END_DECLS
206
207#endif /* _THREADS_H */
208