sysdeps/pthread/threads.h

   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 */