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