newlib/libc/include/pthread.h

   1 /*
   2  *  Written by Joel Sherrill <joel.sherrill@OARcorp.com>.
   3  *
   4  *  COPYRIGHT (c) 1989-2013, 2015.
   5  *  On-Line Applications Research Corporation (OAR).
   6  *
   7  *  Permission to use, copy, modify, and distribute this software for any
   8  *  purpose without fee is hereby granted, provided that this entire notice
   9  *  is included in all copies of any software which is or includes a copy
  10  *  or modification of this software.
  11  *
  12  *  THIS SOFTWARE IS BEING PROVIDED "AS IS", WITHOUT ANY EXPRESS OR IMPLIED
  13  *  WARRANTY.  IN PARTICULAR,  THE AUTHOR MAKES NO REPRESENTATION
  14  *  OR WARRANTY OF ANY KIND CONCERNING THE MERCHANTABILITY OF THIS
  15  *  SOFTWARE OR ITS FITNESS FOR ANY PARTICULAR PURPOSE.
  16  */
  17
  18 #ifndef __PTHREAD_h
  19 #define __PTHREAD_h
  20
  21 #ifdef __cplusplus
  22 extern "C" {
  23 #endif
  24
  25 #include <unistd.h>
  26
  27 #if defined(_POSIX_THREADS)
  28
  29 #include <sys/types.h>
  30 #include <time.h>
  31 #include <sched.h>
  32 #include <sys/cdefs.h>
  33
  34 struct _pthread_cleanup_context {
  35   void (*_routine)(void *);
  36   void *_arg;
  37   int _canceltype;
  38   struct _pthread_cleanup_context *_previous;
  39 };
  40
  41 /* Register Fork Handlers */
  42 int     pthread_atfork (void (*prepare)(void), void (*parent)(void),
  43                    void (*child)(void));
  44
  45 /* Mutex Initialization Attributes, P1003.1c/Draft 10, p. 81 */
  46
  47 int     pthread_mutexattr_init (pthread_mutexattr_t *__attr);
  48 int     pthread_mutexattr_destroy (pthread_mutexattr_t *__attr);
  49 int     pthread_mutexattr_getpshared (const pthread_mutexattr_t *__attr,
  50                                       int  *__pshared);
  51 int     pthread_mutexattr_setpshared (pthread_mutexattr_t *__attr,
  52                                       int __pshared);
  53
  54 #if defined(_UNIX98_THREAD_MUTEX_ATTRIBUTES)
  55
  56 /* Single UNIX Specification 2 Mutex Attributes types */
  57
  58 int pthread_mutexattr_gettype (const pthread_mutexattr_t *__attr, int *__kind);
  59 int pthread_mutexattr_settype (pthread_mutexattr_t *__attr, int __kind);
  60
  61 #endif
  62
  63 /* Initializing and Destroying a Mutex, P1003.1c/Draft 10, p. 87 */
  64
  65 int     pthread_mutex_init (pthread_mutex_t *__mutex,
  66                             const pthread_mutexattr_t *__attr);
  67 int     pthread_mutex_destroy (pthread_mutex_t *__mutex);
  68
  69 /* This is used to statically initialize a pthread_mutex_t. Example:
  70
  71     pthread_mutex_t mutex = PTHREAD_MUTEX_INITIALIZER;
  72  */
  73
  74 #define PTHREAD_MUTEX_INITIALIZER _PTHREAD_MUTEX_INITIALIZER
  75
  76 /*  Locking and Unlocking a Mutex, P1003.1c/Draft 10, p. 93
  77     NOTE: P1003.4b/D8 adds pthread_mutex_timedlock(), p. 29 */
  78
  79 int     pthread_mutex_lock (pthread_mutex_t *__mutex);
  80 int     pthread_mutex_trylock (pthread_mutex_t *__mutex);
  81 int     pthread_mutex_unlock (pthread_mutex_t *__mutex);
  82
  83 #if defined(_POSIX_TIMEOUTS)
  84
  85 int     pthread_mutex_timedlock (pthread_mutex_t *__mutex,
  86                                  const struct timespec *__timeout);
  87
  88 #endif /* _POSIX_TIMEOUTS */
  89
  90 #if __GNU_VISIBLE
  91 /* The Issue 8 standard adds pthread_mutex_clocklock() */
  92 int pthread_mutex_clocklock(pthread_mutex_t *__restrict, clockid_t,
  93                                    const struct timespec *__restrict);
  94 #endif /* __GNU_VISIBLE */
  95
  96 /* Condition Variable Initialization Attributes, P1003.1c/Draft 10, p. 96 */
  97
  98 int     pthread_condattr_init (pthread_condattr_t *__attr);
  99 int     pthread_condattr_destroy (pthread_condattr_t *__attr);
 100
 101 int     pthread_condattr_getclock (const pthread_condattr_t *__restrict __attr,
 102                                    clockid_t *__restrict __clock_id);
 103 int     pthread_condattr_setclock (pthread_condattr_t *__attr,
 104                                    clockid_t __clock_id);
 105
 106 int     pthread_condattr_getpshared (const pthread_condattr_t *__attr,
 107                                      int *__pshared);
 108 int     pthread_condattr_setpshared (pthread_condattr_t *__attr, int __pshared);
 109
 110 /* Initializing and Destroying a Condition Variable, P1003.1c/Draft 10, p. 87 */
 111
 112 int     pthread_cond_init (pthread_cond_t *__cond,
 113                            const pthread_condattr_t *__attr);
 114 int     pthread_cond_destroy (pthread_cond_t *__mutex);
 115
 116 /* This is used to statically initialize a pthread_cond_t. Example:
 117
 118     pthread_cond_t cond = PTHREAD_COND_INITIALIZER;
 119  */
 120
 121 #define PTHREAD_COND_INITIALIZER _PTHREAD_COND_INITIALIZER
 122
 123 /* Broadcasting and Signaling a Condition, P1003.1c/Draft 10, p. 101 */
 124
 125 int     pthread_cond_signal (pthread_cond_t *__cond);
 126 int     pthread_cond_broadcast (pthread_cond_t *__cond);
 127
 128 /* Waiting on a Condition, P1003.1c/Draft 10, p. 105 */
 129
 130 int     pthread_cond_wait (pthread_cond_t *__cond, pthread_mutex_t *__mutex);
 131
 132 int     pthread_cond_timedwait (pthread_cond_t *__cond,
 133                                 pthread_mutex_t *__mutex,
 134                                 const struct timespec *__abstime);
 135
 136 #if __GNU_VISIBLE
 137 /* The Issue 8 standard adds pthread_cond_clockwait() */
 138 int pthread_cond_clockwait(pthread_cond_t *__restrict,
 139                    pthread_mutex_t *__restrict, clockid_t,
 140                                    const struct timespec *__restrict);
 141 #endif /* __GNU_VISIBLE */
 142
 143 #if defined(_POSIX_THREAD_PRIORITY_SCHEDULING)
 144
 145 /* Thread Creation Scheduling Attributes, P1003.1c/Draft 10, p. 120 */
 146
 147 int     pthread_attr_setscope (pthread_attr_t *__attr, int __contentionscope);
 148 int     pthread_attr_getscope (const pthread_attr_t *__attr,
 149                                int *__contentionscope);
 150 int     pthread_attr_setinheritsched (pthread_attr_t *__attr,
 151                                       int __inheritsched);
 152 int     pthread_attr_getinheritsched (const pthread_attr_t *__attr,
 153                                       int *__inheritsched);
 154 int     pthread_attr_setschedpolicy (pthread_attr_t *__attr, int __policy);
 155 int     pthread_attr_getschedpolicy (const pthread_attr_t *__attr,
 156                                      int *__policy);
 157
 158 #endif /* defined(_POSIX_THREAD_PRIORITY_SCHEDULING) */
 159
 160 int     pthread_attr_setschedparam (pthread_attr_t *__attr,
 161                                     const struct sched_param *__param);
 162 int     pthread_attr_getschedparam (const pthread_attr_t *__attr,
 163                                     struct sched_param *__param);
 164
 165 #if defined(_POSIX_THREAD_PRIORITY_SCHEDULING)
 166
 167 /* Dynamic Thread Scheduling Parameters Access, P1003.1c/Draft 10, p. 124 */
 168
 169 int     pthread_getschedparam (pthread_t __pthread, int *__policy,
 170                                struct sched_param *__param);
 171 int     pthread_setschedparam (pthread_t __pthread, int __policy,
 172                                const struct sched_param *__param);
 173
 174 /* Set Scheduling Priority of a Thread */
 175 int     pthread_setschedprio (pthread_t thread, int prio);
 176
 177 #endif /* defined(_POSIX_THREAD_PRIORITY_SCHEDULING) */
 178
 179 #if __GNU_VISIBLE
 180 int     pthread_getname_np(pthread_t, char *, size_t) __nonnull((2));
 181
 182 int     pthread_setname_np(pthread_t, const char *) __nonnull((2));
 183 #endif
 184
 185 #if defined(_POSIX_THREAD_PRIO_INHERIT) || defined(_POSIX_THREAD_PRIO_PROTECT)
 186
 187 /* Mutex Initialization Scheduling Attributes, P1003.1c/Draft 10, p. 128 */
 188
 189 int     pthread_mutexattr_setprotocol (pthread_mutexattr_t *__attr,
 190                                        int __protocol);
 191 int     pthread_mutexattr_getprotocol (const pthread_mutexattr_t *__attr,
 192                                        int *__protocol);
 193 int     pthread_mutexattr_setprioceiling (pthread_mutexattr_t *__attr,
 194                                           int __prioceiling);
 195 int     pthread_mutexattr_getprioceiling (const pthread_mutexattr_t *__attr,
 196                                           int *__prioceiling);
 197
 198 #endif /* _POSIX_THREAD_PRIO_INHERIT || _POSIX_THREAD_PRIO_PROTECT */
 199
 200 #if defined(_POSIX_THREAD_PRIO_PROTECT)
 201
 202 /* Change the Priority Ceiling of a Mutex, P1003.1c/Draft 10, p. 131 */
 203
 204 int     pthread_mutex_setprioceiling (pthread_mutex_t *__mutex,
 205                                       int __prioceiling, int *__old_ceiling);
 206 int     pthread_mutex_getprioceiling (const pthread_mutex_t *__restrict __mutex,
 207                                       int *__prioceiling);
 208
 209 #endif /* _POSIX_THREAD_PRIO_PROTECT */
 210
 211 /* Thread Creation Attributes, P1003.1c/Draft 10, p, 140 */
 212
 213 int     pthread_attr_init (pthread_attr_t *__attr);
 214 int     pthread_attr_destroy (pthread_attr_t *__attr);
 215 int     pthread_attr_setstack (pthread_attr_t *attr,
 216         void *__stackaddr, size_t __stacksize);
 217 int     pthread_attr_getstack (const pthread_attr_t *attr,
 218         void **__stackaddr, size_t *__stacksize);
 219 int     pthread_attr_getstacksize (const pthread_attr_t *__attr,
 220                                    size_t *__stacksize);
 221 int     pthread_attr_setstacksize (pthread_attr_t *__attr, size_t __stacksize);
 222 int     pthread_attr_getstackaddr (const pthread_attr_t *__attr,
 223                                    void **__stackaddr);
 224 int     pthread_attr_setstackaddr (pthread_attr_t  *__attr, void *__stackaddr);
 225 int     pthread_attr_getdetachstate (const pthread_attr_t *__attr,
 226                                      int *__detachstate);
 227 int     pthread_attr_setdetachstate (pthread_attr_t *__attr, int __detachstate);
 228 int     pthread_attr_getguardsize (const pthread_attr_t *__attr,
 229                                    size_t *__guardsize);
 230 int     pthread_attr_setguardsize (pthread_attr_t *__attr, size_t __guardsize);
 231
 232 /* POSIX thread APIs beyond the POSIX standard but provided
 233  * in GNU/Linux. They may be provided by other OSes for
 234  * compatibility.
 235  */
 236 #if __GNU_VISIBLE
 237 #if defined(__rtems__)
 238 int     pthread_attr_setaffinity_np (pthread_attr_t *__attr,
 239                                      size_t __cpusetsize,
 240                                      const cpu_set_t *__cpuset);
 241 int     pthread_attr_getaffinity_np (const pthread_attr_t *__attr,
 242                                      size_t __cpusetsize, cpu_set_t *__cpuset);
 243
 244 int     pthread_setaffinity_np (pthread_t __id, size_t __cpusetsize,
 245                                 const cpu_set_t *__cpuset);
 246 int     pthread_getaffinity_np (const pthread_t __id, size_t __cpusetsize,
 247                                 cpu_set_t *__cpuset);
 248
 249 int     pthread_getattr_np (pthread_t __id, pthread_attr_t *__attr);
 250 #endif /* defined(__rtems__) */
 251 #endif /* __GNU_VISIBLE */
 252
 253 /* Thread Creation, P1003.1c/Draft 10, p. 144 */
 254
 255 int     pthread_create (pthread_t *__pthread, const pthread_attr_t  *__attr,
 256                         void *(*__start_routine)(void *), void *__arg);
 257
 258 /* Wait for Thread Termination, P1003.1c/Draft 10, p. 147 */
 259
 260 int     pthread_join (pthread_t __pthread, void **__value_ptr);
 261
 262 /* Detaching a Thread, P1003.1c/Draft 10, p. 149 */
 263
 264 int     pthread_detach (pthread_t __pthread);
 265
 266 /* Thread Termination, p1003.1c/Draft 10, p. 150 */
 267
 268 void    pthread_exit (void *__value_ptr) __dead2;
 269
 270 /* Get Calling Thread's ID, p1003.1c/Draft 10, p. XXX */
 271
 272 pthread_t       pthread_self (void);
 273
 274 /* Compare Thread IDs, p1003.1c/Draft 10, p. 153 */
 275
 276 int     pthread_equal (pthread_t __t1, pthread_t __t2);
 277
 278 /* Retrieve ID of a Thread's CPU Time Clock */
 279 int     pthread_getcpuclockid (pthread_t thread, clockid_t *clock_id);
 280
 281 /* Get/Set Current Thread's Concurrency Level */
 282 int     pthread_setconcurrency (int new_level);
 283 int     pthread_getconcurrency (void);
 284
 285 #if __BSD_VISIBLE || __GNU_VISIBLE
 286 void    pthread_yield (void);
 287 #endif
 288
 289 /* Dynamic Package Initialization */
 290
 291 /* This is used to statically initialize a pthread_once_t. Example:
 292
 293     pthread_once_t once = PTHREAD_ONCE_INIT;
 294
 295     NOTE:  This is named inconsistently -- it should be INITIALIZER.  */
 296
 297 #define PTHREAD_ONCE_INIT _PTHREAD_ONCE_INIT
 298
 299 int     pthread_once (pthread_once_t *__once_control,
 300                       void (*__init_routine)(void));
 301
 302 /* Thread-Specific Data Key Create, P1003.1c/Draft 10, p. 163 */
 303
 304 int     pthread_key_create (pthread_key_t *__key,
 305                             void (*__destructor)(void *));
 306
 307 /* Thread-Specific Data Management, P1003.1c/Draft 10, p. 165 */
 308
 309 int     pthread_setspecific (pthread_key_t __key, const void *__value);
 310 void *  pthread_getspecific (pthread_key_t __key);
 311
 312 /* Thread-Specific Data Key Deletion, P1003.1c/Draft 10, p. 167 */
 313
 314 int     pthread_key_delete (pthread_key_t __key);
 315
 316 /* Execution of a Thread, P1003.1c/Draft 10, p. 181 */
 317
 318 #define PTHREAD_CANCEL_ENABLE  0
 319 #define PTHREAD_CANCEL_DISABLE 1
 320
 321 #define PTHREAD_CANCEL_DEFERRED 0
 322 #define PTHREAD_CANCEL_ASYNCHRONOUS 1
 323
 324 #define PTHREAD_CANCELED ((void *) -1)
 325
 326 int     pthread_cancel (pthread_t __pthread);
 327
 328 /* Setting Cancelability State, P1003.1c/Draft 10, p. 183 */
 329
 330 int     pthread_setcancelstate (int __state, int *__oldstate);
 331 int     pthread_setcanceltype (int __type, int *__oldtype);
 332 void    pthread_testcancel (void);
 333
 334 /* Establishing Cancellation Handlers, P1003.1c/Draft 10, p. 184 */
 335
 336 void    _pthread_cleanup_push (struct _pthread_cleanup_context *_context,
 337                                void (*_routine)(void *), void *_arg);
 338
 339 void    _pthread_cleanup_pop (struct _pthread_cleanup_context *_context,
 340                               int _execute);
 341
 342 /* It is intentional to open and close the scope in two different macros */
 343 #define pthread_cleanup_push(_routine, _arg) \
 344   do { \
 345     struct _pthread_cleanup_context _pthread_clup_ctx; \
 346     _pthread_cleanup_push(&_pthread_clup_ctx, (_routine), (_arg))
 347
 348 #define pthread_cleanup_pop(_execute) \
 349     _pthread_cleanup_pop(&_pthread_clup_ctx, (_execute)); \
 350   } while (0)
 351
 352 #if __GNU_VISIBLE
 353 void    _pthread_cleanup_push_defer (struct _pthread_cleanup_context *_context,
 354                                      void (*_routine)(void *), void *_arg);
 355
 356 void    _pthread_cleanup_pop_restore (struct _pthread_cleanup_context *_context,
 357                                       int _execute);
 358
 359 /* It is intentional to open and close the scope in two different macros */
 360 #define pthread_cleanup_push_defer_np(_routine, _arg) \
 361   do { \
 362     struct _pthread_cleanup_context _pthread_clup_ctx; \
 363     _pthread_cleanup_push_defer(&_pthread_clup_ctx, (_routine), (_arg))
 364
 365 #define pthread_cleanup_pop_restore_np(_execute) \
 366     _pthread_cleanup_pop_restore(&_pthread_clup_ctx, (_execute)); \
 367   } while (0)
 368 #endif /* __GNU_VISIBLE */
 369
 370 #if defined(_POSIX_THREAD_CPUTIME)
 371
 372 /* Accessing a Thread CPU-time Clock, P1003.4b/D8, p. 58 */
 373
 374 int     pthread_getcpuclockid (pthread_t __pthread_id, clockid_t *__clock_id);
 375
 376 #endif /* defined(_POSIX_THREAD_CPUTIME) */
 377
 378
 379 #endif /* defined(_POSIX_THREADS) */
 380
 381 #if defined(_POSIX_BARRIERS)
 382
 383 int     pthread_barrierattr_init (pthread_barrierattr_t *__attr);
 384 int     pthread_barrierattr_destroy (pthread_barrierattr_t *__attr);
 385 int     pthread_barrierattr_getpshared (const pthread_barrierattr_t *__attr,
 386                                         int *__pshared);
 387 int     pthread_barrierattr_setpshared (pthread_barrierattr_t *__attr,
 388                                         int __pshared);
 389
 390 #define PTHREAD_BARRIER_SERIAL_THREAD -1
 391
 392 int     pthread_barrier_init (pthread_barrier_t *__barrier,
 393                               const pthread_barrierattr_t *__attr,
 394                               unsigned __count);
 395 int     pthread_barrier_destroy (pthread_barrier_t *__barrier);
 396 int     pthread_barrier_wait (pthread_barrier_t *__barrier);
 397
 398 #endif /* defined(_POSIX_BARRIERS) */
 399
 400 #if defined(_POSIX_SPIN_LOCKS)
 401
 402 int     pthread_spin_init (pthread_spinlock_t *__spinlock, int __pshared);
 403 int     pthread_spin_destroy (pthread_spinlock_t *__spinlock);
 404 int     pthread_spin_lock (pthread_spinlock_t *__spinlock);
 405 int     pthread_spin_trylock (pthread_spinlock_t *__spinlock);
 406 int     pthread_spin_unlock (pthread_spinlock_t *__spinlock);
 407
 408 #endif /* defined(_POSIX_SPIN_LOCKS) */
 409
 410 #if defined(_POSIX_READER_WRITER_LOCKS)
 411
 412 /* This is used to statically initialize a pthread_rwlock_t. Example:
 413
 414     pthread_mutex_t mutex = PTHREAD_RWLOCK_INITIALIZER;
 415  */
 416
 417 #define PTHREAD_RWLOCK_INITIALIZER _PTHREAD_RWLOCK_INITIALIZER
 418
 419 int     pthread_rwlockattr_init (pthread_rwlockattr_t *__attr);
 420 int     pthread_rwlockattr_destroy (pthread_rwlockattr_t *__attr);
 421 int     pthread_rwlockattr_getpshared (const pthread_rwlockattr_t *__attr,
 422                                        int *__pshared);
 423 int     pthread_rwlockattr_setpshared (pthread_rwlockattr_t *__attr,
 424                                        int __pshared);
 425
 426 int     pthread_rwlock_init (pthread_rwlock_t *__rwlock,
 427                              const pthread_rwlockattr_t *__attr);
 428 int     pthread_rwlock_destroy (pthread_rwlock_t *__rwlock);
 429 int     pthread_rwlock_rdlock (pthread_rwlock_t *__rwlock);
 430 int     pthread_rwlock_tryrdlock (pthread_rwlock_t *__rwlock);
 431 int     pthread_rwlock_timedrdlock (pthread_rwlock_t *__rwlock,
 432                                     const struct timespec *__abstime);
 433 int     pthread_rwlock_unlock (pthread_rwlock_t *__rwlock);
 434 int     pthread_rwlock_wrlock (pthread_rwlock_t *__rwlock);
 435 int     pthread_rwlock_trywrlock (pthread_rwlock_t *__rwlock);
 436 int     pthread_rwlock_timedwrlock (pthread_rwlock_t *__rwlock,
 437                                     const struct timespec *__abstime);
 438
 439 #if __GNU_VISIBLE
 440 /* The Issue 8 standard adds pthread_rwlock_clockrdlock()
 441 *  and pthread_rwlock_clockwrlock()*/
 442 int pthread_rwlock_clockrdlock(pthread_rwlock_t *__restrict, clockid_t,
 443                                    const struct timespec *__restrict);
 444 int pthread_rwlock_clockwrlock(pthread_rwlock_t *__restrict, clockid_t,
 445                                    const struct timespec *__restrict);
 446 #endif /* __GNU_VISIBLE */
 447
 448 #endif /* defined(_POSIX_READER_WRITER_LOCKS) */
 449
 450
 451 #ifdef __cplusplus
 452 }
 453 #endif
 454
 455 #endif
 456 /* end of include file */