pthread.h

   1 /*
   2  * Copyright (c) 2012 The Native Client Authors. All rights reserved.
   3  * Use of this source code is governed by a BSD-style license that can be
   4  * found in the LICENSE file.
   5  */
   6
   7 /** @file
   8  * Defines the API in the
   9  * <a href="group___pthread.html">Pthread library</a>
  10  *
  11  * @addtogroup Pthread
  12  * @{
  13  */
  14
  15 #ifndef _PTHREAD_H
  16 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  17 #define _PTHREAD_H 1
  18 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
  19
  20 #include <stdint.h>
  21 #include <sched.h>
  22 #include <time.h>
  23 #include <sys/nacl_nice.h>
  24 #include <sys/queue.h>
  25 #include <sys/types.h>
  26
  27 /*
  28  * Signed 32-bit integer supporting CompareAndSwap and AtomicIncrement
  29  * (see implementations), as well as atomic loads and stores.
  30  * Instances must be naturally aligned.
  31  */
  32 typedef int AtomicInt32;
  33
  34 #ifdef __cplusplus
  35 extern "C" {
  36 #endif
  37
  38 struct timespec;
  39 struct __nc_basic_thread_data;
  40
  41 /** Mutex type attributes */
  42 enum {
  43   /** Fast mutex type; for use with pthread_mutexattr_settype() */
  44   PTHREAD_MUTEX_FAST_NP,
  45   /** Recursive mutex type; for use with pthread_mutexattr_settype() */
  46   PTHREAD_MUTEX_RECURSIVE_NP,
  47   /** Error-checking mutex type; for use with pthread_mutexattr_settype() */
  48   PTHREAD_MUTEX_ERRORCHECK_NP,
  49   PTHREAD_MUTEX_NORMAL = PTHREAD_MUTEX_FAST_NP,
  50   PTHREAD_MUTEX_RECURSIVE = PTHREAD_MUTEX_RECURSIVE_NP,
  51   PTHREAD_MUTEX_ERRORCHECK = PTHREAD_MUTEX_ERRORCHECK_NP,
  52
  53   PTHREAD_MUTEX_DEFAULT = PTHREAD_MUTEX_NORMAL
  54 };
  55
  56 /*
  57  * The layout of pthread_mutex_t and the static initializers are redefined
  58  * in newlib's sys/lock.h file (including this file from sys/lock.h will
  59  * cause include conflicts). When changing one of the definitions, make sure to
  60  * change the second one.
  61  */
  62 /**
  63  * A structure representing a thread mutex. It should be considered an
  64  * opaque record; the names of the fields can change anytime.
  65  */
  66 typedef struct {
  67   /** Initialization token **/
  68   int token;
  69
  70   /**
  71    * The kind of mutex:
  72    * PTHREAD_MUTEX_FAST_NP, PTHREAD_MUTEX_RECURSIVE_NP,
  73    * or PTHREAD_MUTEX_ERRORCHECK_NP
  74    */
  75   int mutex_type;
  76
  77   /** ID of the thread that owns the mutex */
  78   struct __nc_basic_thread_data *owner_thread_id;
  79
  80   /** Recursion depth counter for recursive mutexes */
  81   uint32_t recursion_counter;
  82
  83   /** Handle to the system-side mutex */
  84   int mutex_handle;
  85 } pthread_mutex_t;
  86
  87 /**
  88  * A structure representing mutex attributes. It should be considered an
  89  * opaque record and accessed only using pthread_mutexattr_settype().
  90  */
  91 typedef struct {
  92   /**
  93    * The kind of mutex:
  94    * PTHREAD_MUTEX_FAST_NP, PTHREAD_MUTEX_RECURSIVE_NP,
  95    * or PTHREAD_MUTEX_ERRORCHECK_NP
  96    */
  97   int kind;
  98 } pthread_mutexattr_t;
  99
 100 /**
 101  * A structure representing a condition variable. It should be considered an
 102  * opaque record; the names of the fields can change anytime.
 103  */
 104 typedef struct {
 105   /** Initialization token **/
 106   int token;
 107
 108   /**< Handle to the system-side condition variable */
 109   int handle;
 110 } pthread_cond_t;
 111
 112 /**
 113  * A structure representing condition variable attributes. Currently
 114  * Native Client condition variables have no attributes.
 115  */
 116 typedef struct {
 117   int dummy; /**< Reserved; condition variables don't have attributes */
 118 } pthread_condattr_t;
 119
 120 /** A value that represents an uninitialized handle. */
 121 #define NC_INVALID_HANDLE -1
 122
 123 /** Maximum valid thread ID value. */
 124 #define MAX_THREAD_ID (0xfffffffe)
 125
 126 /** Illegal thread ID value. */
 127 #define NACL_PTHREAD_ILLEGAL_THREAD_ID ((pthread_t) 0)
 128
 129 /** Statically initializes a pthread_mutex_t representing a recursive mutex. */
 130 #define PTHREAD_RECURSIVE_MUTEX_INITIALIZER_NP \
 131     {0, 1, NACL_PTHREAD_ILLEGAL_THREAD_ID, 0, NC_INVALID_HANDLE}
 132 /** Statically initializes a pthread_mutex_t representing a fast mutex. */
 133 #define PTHREAD_MUTEX_INITIALIZER \
 134     {0, 0, NACL_PTHREAD_ILLEGAL_THREAD_ID, 0, NC_INVALID_HANDLE}
 135 /**
 136  * Statically initializes a pthread_mutex_t representing an
 137  * error-checking mutex.
 138  */
 139 #define PTHREAD_ERRORCHECK_MUTEX_INITIALIZER_NP \
 140     {0, 2, NACL_PTHREAD_ILLEGAL_THREAD_ID, 0, NC_INVALID_HANDLE}
 141 /** Statically initializes a condition variable (pthread_cond_t). */
 142 #define PTHREAD_COND_INITIALIZER {0, NC_INVALID_HANDLE}
 143
 144
 145
 146 /* Functions for mutex handling.  */
 147
 148 /** @nqPosix
 149  * Initializes a mutex using attributes in mutex_attr, or using the
 150  * default values if the latter is NULL.
 151  *
 152  * @linkPthread
 153  *
 154  * @param mutex The address of the mutex structure to be initialized.
 155  * @param mutex_attr The address of the attributes structure.
 156  *
 157  * @return 0 upon success, 1 otherwise
 158  */
 159 extern int pthread_mutex_init(pthread_mutex_t *mutex,
 160                               const pthread_mutexattr_t *mutex_attr);
 161
 162 /** @nqPosix
 163 * Destroys a mutex.
 164 *
 165 * @linkPthread
 166 *
 167 * @param mutex The address of the mutex structure to be destroyed.
 168 *
 169 * @return 0 upon success, non-zero error code otherwise
 170 */
 171 extern int pthread_mutex_destroy(pthread_mutex_t *mutex);
 172
 173 /** @nqPosix
 174 * Tries to lock a mutex.
 175 *
 176 * @linkPthread
 177 *
 178 * @param mutex The address of the mutex structure to be locked.
 179 *
 180 * @return 0 upon success, EBUSY if the mutex is locked by another thread,
 181 * non-zero error code otherwise.
 182 */
 183 extern int pthread_mutex_trylock(pthread_mutex_t *mutex);
 184
 185 /** @nqPosix
 186 * Locks a mutex.
 187 *
 188 * @linkPthread
 189 *
 190 * @param mutex The address of the mutex structure to be locked.
 191 *
 192 * @return 0 upon success, non-zero error code otherwise.
 193 */
 194 extern int pthread_mutex_lock(pthread_mutex_t *mutex);
 195
 196 /* TODO(gregoryd) - depends on implementation */
 197 #if 0
 198 /* Wait until lock becomes available, or specified time passes. */
 199 /* TODO(gregoryd): consider implementing this function. */
 200 extern int pthread_mutex_timedlock(pthread_mutex_t *mutex,
 201                                    struct timespec *abstime);
 202 #endif
 203
 204 /** @nqPosix
 205 * Unlocks a mutex.
 206 *
 207 * @linkPthread
 208 *
 209 * @param mutex The address of the mutex structure to be unlocked.
 210 *
 211 * @return 0 upon success, non-zero error code otherwise.
 212 */
 213 extern int pthread_mutex_unlock(pthread_mutex_t *mutex);
 214
 215 /* Mutex attributes manipulation */
 216
 217 /** @nqPosix
 218 * Initializes mutex attributes.
 219 *
 220 * @linkPthread
 221 *
 222 * @param attr The address of the attributes structure to be initialized.
 223 *
 224 * @return 0.
 225 */
 226 extern int pthread_mutexattr_init(pthread_mutexattr_t *attr);
 227
 228 /** @nqPosix
 229 * Destroys mutex attributes structure.
 230 *
 231 * @linkPthread
 232 *
 233 * @param attr The address of the attributes structure to be destroyed.
 234 *
 235 * @return 0.
 236 */
 237 extern int pthread_mutexattr_destroy(pthread_mutexattr_t *attr);
 238
 239 /** @nqPosix
 240 * Sets the mutex type: fast, recursive or error-checking.
 241 *
 242 * @linkPthread
 243 *
 244 * @param attr The address of the attributes structure.
 245 * @param kind PTHREAD_MUTEX_FAST_NP, PTHREAD_MUTEX_RECURSIVE_NP or
 246 * PTHREAD_MUTEX_ERRORCHECK_NP.
 247 *
 248 * @return 0 on success, -1 for illegal values of kind.
 249 */
 250 extern int pthread_mutexattr_settype(pthread_mutexattr_t *attr,
 251                                      int kind);
 252
 253 /** @nqPosix
 254 * Gets the mutex type: fast, recursive or error-checking.
 255 *
 256 * @linkPthread
 257 *
 258 * @param attr The address of the attributes structure.
 259 * @param kind Pointer to the location where the mutex kind value is copied.
 260 *
 261 * @return 0.
 262 */
 263 extern int pthread_mutexattr_gettype(const pthread_mutexattr_t *attr,
 264                                      int *kind);
 265
 266 /* Functions for handling conditional variables.  */
 267
 268 /** @nqPosix
 269 * Initializes a condition variable.
 270 *
 271 * @linkPthread
 272 *
 273 * @param cond Pointer to the condition variable structure.
 274 * @param cond_attr Pointer to the attributes structure, should be NULL as
 275 * Native Client does not support any attributes for a condition variable at
 276 * this stage.
 277 *
 278 * @return 0 for success, 1 otherwise.
 279 */
 280 extern int pthread_cond_init(pthread_cond_t *cond,
 281                              const pthread_condattr_t *cond_attr);
 282
 283 /** @nqPosix
 284 * Destroys a condition variable.
 285 *
 286 * @linkPthread
 287 *
 288 * @param cond Pointer to the condition variable structure.
 289 *
 290 * @return 0 for success, non-zero error code otherwise.
 291 */
 292 extern int pthread_cond_destroy(pthread_cond_t *cond);
 293
 294 /** @nqPosix
 295 * Signals a condition variable, waking up one of the threads waiting on it.
 296 *
 297 * @linkPthread
 298 *
 299 * @param cond Pointer to the condition variable structure.
 300 *
 301 * @return 0 for success, non-zero error code otherwise.
 302 */
 303 extern int pthread_cond_signal(pthread_cond_t *cond);
 304
 305 /** @nqPosix
 306 * Wakes up all threads waiting on a condition variable.
 307 *
 308 * @linkPthread
 309 *
 310 * @param cond Pointer to the condition variable structure.
 311 *
 312 * @return 0 for success, non-zero error code otherwise.
 313 */
 314 extern int pthread_cond_broadcast(pthread_cond_t *cond);
 315
 316 /** @nqPosix
 317 * Waits for a condition variable to be signaled or broadcast.
 318 *
 319 * @linkPthread
 320 *
 321 * @param cond Pointer to the condition variable structure.
 322 * @param mutex Pointer to the mutex structure. The mutex is assumed to be locked
 323 * when this function is called.
 324 *
 325 * @return 0 for success, non-zero error code otherwise.
 326 */
 327 extern int pthread_cond_wait(pthread_cond_t *cond,
 328                              pthread_mutex_t *mutex);
 329
 330 /** @nqPosix
 331 * Waits for condition variable cond to be signaled or broadcast until
 332 * abstime.
 333 *
 334 * @linkPthread
 335 *
 336 * @param cond Pointer to the condition variable structure.
 337 * @param mutex Pointer to the mutex structure. The mutex is assumed to be locked
 338 * when this function is called.
 339 * @param abstime Absolute time specification; zero is the beginning of the epoch
 340 * (00:00:00 GMT, January 1, 1970).
 341 *
 342 * @return 0 for success, non-zero error code otherwise.
 343 */
 344 int pthread_cond_timedwait_abs(pthread_cond_t *cond,
 345                                pthread_mutex_t *mutex,
 346                                const struct timespec *abstime);
 347
 348  /** @nqPosix
 349 * Waits for condition variable cond to be signaled or broadcast; wait time is
 350 * limited by reltime.
 351 *
 352 * @linkPthread
 353 *
 354 * @param cond Pointer to the condition variable structure.
 355 * @param mutex Pointer to the mutex structure. The mutex is assumed to be locked
 356 * when this function is called.
 357 * @param reltime Time specification, relative to the current time.
 358 *
 359 * @return 0 for success, non-zero error code otherwise.
 360 */
 361 int pthread_cond_timedwait_rel(pthread_cond_t *cond,
 362                                pthread_mutex_t *mutex,
 363                                const struct timespec *reltime);
 364
 365 /**
 366  * Defined for POSIX compatibility; pthread_cond_timedwait() is actually
 367  * a macro calling pthread_cond_timedwait_abs().
 368  */
 369 #define pthread_cond_timedwait pthread_cond_timedwait_abs
 370
 371
 372 /* Threads */
 373 /** Thread entry function type. */
 374 typedef void *(*nc_thread_function)(void *p);
 375 /** Thread identifier type. */
 376 typedef struct __nc_basic_thread_data *pthread_t;
 377
 378 /** A structure representing thread attributes. */
 379 typedef struct {
 380   int joinable; /**< 1 if the thread is joinable, 0 otherwise */
 381   size_t stacksize; /**< The requested thread stack size in bytes. */
 382 } pthread_attr_t;
 383
 384
 385 /** Joinable thread type; for use with pthread_attr_setdetachstate(). */
 386 #define PTHREAD_CREATE_JOINABLE 1
 387 /** Detached thread type; for use with pthread_attr_setdetachstate(). */
 388 #define PTHREAD_CREATE_DETACHED 0
 389
 390 /** Minimum stack size; for use with pthread_attr_setstacksize(). */
 391 #define PTHREAD_STACK_MIN     (1024)
 392
 393 /* default stack size */
 394 #define PTHREAD_STACK_DEFAULT (512 * 1024)
 395
 396 /* Thread functions  */
 397
 398 /** @nqPosix
 399 * Creates a thread.
 400 *
 401 * @linkPthread
 402 *
 403 * @param[out] thread_id A pointer to the location where the identifier of the
 404 * newly created thread is stored on success.
 405 * @param attr Thread attributes structure.
 406 * @param start_routine Thread function.
 407 * @param arg A single argument that is passed to the thread function.
 408 *
 409 * @return 0 for success, non-zero error code otherwise.
 410 */
 411 extern int pthread_create(pthread_t *thread_id,
 412                           const pthread_attr_t *attr,
 413                           void *(*start_routine) (void *p),
 414                           void *arg);
 415
 416 /** @nqPosix
 417 * Obtains the identifier of the current thread.
 418 *
 419 * @linkPthread
 420 *
 421 * @return Thread ID of the current thread.
 422 */
 423 extern pthread_t pthread_self(void);
 424
 425 /** @nqPosix
 426 * Compares two thread identifiers.
 427 *
 428 * @linkPthread
 429 *
 430 * @param thread1 Thread ID of thread A.
 431 * @param thread2 Thread ID of thread B.
 432 *
 433 * @return 1 if both identifiers belong to the same thread, 0 otherwise.
 434 */
 435 extern int pthread_equal(pthread_t thread1, pthread_t thread2);
 436
 437 /** @nqPosix
 438 * Terminates the calling thread.
 439 *
 440 * @linkPthread
 441 *
 442 * @param retval Return value of the thread.
 443 *
 444 * @return The function never returns.
 445 */
 446 extern void pthread_exit(void *retval);
 447
 448 /** @nqPosix
 449 * Makes the calling thread wait for termination of another thread.
 450 *
 451 * @linkPthread
 452 *
 453 * @param th The identifier of the thread to wait for.
 454 * @param thread_return If not NULL, points to the location where the return
 455 * value of the terminated thread is stored upon completion.
 456 *
 457 * @return 0 on success, non-zero error code otherwise.
 458 */
 459 extern int pthread_join(pthread_t th, void **thread_return);
 460
 461 /** @nqPosix
 462 * Indicates that the specified thread is never to be joined with pthread_join().
 463 * The resources of that thread will therefore be freed immediately when it
 464 * terminates, instead of waiting for another thread to perform pthread_join()
 465 * on it.
 466 *
 467 * @linkPthread
 468 *
 469 * @param th Thread identifier.
 470 *
 471 * @return 0 on success, non-zero error code otherwise.
 472 */
 473 extern int pthread_detach(pthread_t th);
 474
 475 /** @nqPosix
 476 * Sends a signal to a thread.  (Currently only a stub implementation.)
 477 *
 478 * @linkPthread
 479 *
 480 * @param thread_id The identifier of the thread to receive the signal.
 481 * @param sig The signal value to send.
 482 *
 483 * @return 0 for success, non-zero error code otherwise.
 484 */
 485 extern int pthread_kill(pthread_t thread_id,
 486                         int sig);
 487
 488 /* Functions for handling thread attributes.  */
 489 /** @nqPosix
 490 * Initializes thread attributes structure attr with default attributes
 491 * (detachstate is PTHREAD_CREATE_JOINABLE).
 492 *
 493 * @linkPthread
 494 *
 495 * @param attr Pointer to thread attributes structure.
 496 *
 497 * @return 0 on success, non-zero error code otherwise.
 498 */
 499 extern int pthread_attr_init(pthread_attr_t *attr);
 500
 501 /** @nqPosix
 502 * Destroys a thread attributes structure.
 503 *
 504 * @linkPthread
 505 *
 506 * @param attr Pointer to thread attributes structure.
 507 *
 508 * @return 0 on success, non-zero error code otherwise.
 509 */
 510 extern int pthread_attr_destroy(pthread_attr_t *attr);
 511
 512 /** @nqPosix
 513 * Sets the detachstate attribute in thread attributes.
 514 *
 515 * @linkPthread
 516 *
 517 * @param attr Pointer to thread attributes structure.
 518 * @param detachstate Value to be set, determines whether the thread is joinable.
 519 *
 520 * @return 0 on success, non-zero error code otherwise.
 521 */
 522 extern int pthread_attr_setdetachstate(pthread_attr_t *attr,
 523                                        int detachstate);
 524
 525 /** @nqPosix
 526 * Gets the detachstate attribute from thread attributes.
 527 *
 528 * @linkPthread
 529 *
 530 * @param attr Pointer to thread attributes structure.
 531 * @param detachstate Location where the value of `detachstate` is stored upon
 532 * successful completion.
 533 *
 534 * @return 0 on success, non-zero error code otherwise.
 535 */
 536 extern int pthread_attr_getdetachstate(pthread_attr_t *attr,
 537                                        int *detachstate);
 538
 539 /** @nqPosix
 540 * Sets the stacksize attribute in thread attributes.  Has no effect if the
 541 * size is less than PTHREAD_STACK_MIN.
 542 *
 543 * @linkPthread
 544 *
 545 * @param attr Pointer to thread attributes structure.
 546 * @param stacksize Value to be set, determines the minimum stack size.
 547 *
 548 * @return 0 on success, non-zero error code otherwise.
 549 */
 550 extern int pthread_attr_setstacksize(pthread_attr_t *attr,
 551                                      size_t stacksize);
 552
 553 /** @nqPosix
 554 * Gets the stacksize attribute in thread attributes.
 555 *
 556 * @linkPthread
 557 *
 558 * @param attr Pointer to thread attributes structure.
 559 * @param stacksize Value to be set, determines the minimum stack size.
 560 *
 561 * @return 0 on success, non-zero error code otherwise.
 562 */
 563 extern int pthread_attr_getstacksize(pthread_attr_t *attr,
 564                                      size_t *stacksize);
 565
 566 /* Functions for handling thread-specific data.  */
 567
 568 /** Thread-specific key identifier type */
 569 typedef int pthread_key_t;
 570
 571 /** Number of available keys for thread-specific data. */
 572 #define PTHREAD_KEYS_MAX 512
 573
 574 /** @nqPosix
 575 * Creates a key value identifying a location in the thread-specific
 576 * data area.
 577 *
 578 * @linkPthread
 579 *
 580 * @param key Pointer to the location where the value of the key is stored upon
 581 * successful completion.
 582 * @param destr_function Pointer to a cleanup function that is called if the
 583 * thread terminates while the key is still allocated.
 584 *
 585 * @return 0 on success, non-zero error code otherwise.
 586 */
 587 extern int pthread_key_create(pthread_key_t *key,
 588                               void (*destr_function)(void *p));
 589
 590
 591 /** @nqPosix
 592 * Destroys a thread-specific data key.
 593 *
 594 * @linkPthread
 595 *
 596 * @param key Key value, previously obtained using pthread_key_create().
 597 *
 598 * @return 0 on success, non-zero error code otherwise.
 599 */
 600 extern int pthread_key_delete(pthread_key_t key);
 601
 602 /** @nqPosix
 603 * Stores a value in the thread-specific data slot identified by a key value.
 604 *
 605 * @linkPthread
 606 *
 607 * @param key Key value, previously obtained using pthread_key_create().
 608 * @param pointer The value to be stored.
 609 *
 610 * @return 0 on success, non-zero error code otherwise.
 611 */
 612 extern int pthread_setspecific(pthread_key_t key,
 613                                const void *pointer);
 614
 615 /** @nqPosix
 616 * Gets the value currently stored at the thread-specific data slot
 617 * identified by the key.
 618 *
 619 * @linkPthread
 620 *
 621 * @param key Key value, previously obtained using pthread_key_create().
 622 *
 623 * @return The value that was previously stored using pthread_setspecific is
 624 * returned on success, otherwise NULL.
 625 */
 626 extern void *pthread_getspecific(pthread_key_t key);
 627
 628 /**
 629  * A structure describing a control block
 630  * used with the pthread_once() function.
 631  * It should be considered an opaque record;
 632  * the names of the fields can change anytime.
 633  */
 634 typedef struct {
 635   /** A flag: 1 if the function was already called, 0 if it wasn't */
 636   AtomicInt32      done;
 637
 638   /** Synchronization lock for the flag */
 639   pthread_mutex_t lock;
 640 } pthread_once_t;
 641
 642 /** Static initializer for pthread_once_t. */
 643 #define PTHREAD_ONCE_INIT {0, PTHREAD_MUTEX_INITIALIZER}
 644
 645 /** @nqPosix
 646 * Ensures that a piece of initialization code is executed at most once.
 647 *
 648 * @linkPthread
 649 *
 650 * @param __once_control Points to a static or extern variable statically
 651 * initialized to PTHREAD_ONCE_INIT.
 652 * @param __init_routine A pointer to the initialization function.
 653 *
 654 * @return 0.
 655 */
 656 extern int pthread_once(pthread_once_t *__once_control,
 657                         void (*__init_routine)(void));
 658
 659 /** @nqPosix
 660 * Sets the scheduling priority of a thread.
 661 *
 662 * @linkPthread
 663 *
 664 * @param thread_id Identifies the thread to operate on.
 665 * @param prio Scheduling priority to apply to that thread.
 666 *
 667 * @return 0 on success, non-zero error code otherwise.
 668 */
 669 extern int pthread_setschedprio(pthread_t thread_id, int prio);
 670
 671 /*
 672  * NOTE: this is only declared here to shut up
 673  * some warning in the c++ system header files.
 674  * We do not define this function anywhere.
 675  */
 676
 677 extern int pthread_cancel(pthread_t th);
 678
 679 /*
 680  * NOTE: There are only stub implementations of these functions.
 681  */
 682
 683 void pthread_cleanup_push(void (*func)(void *cleanup_arg), void *arg);
 684 void pthread_cleanup_pop(int execute);
 685
 686 /**
 687 * @} End of PTHREAD group
 688 */
 689
 690 #ifdef __cplusplus
 691 }
 692 #endif
 693
 694 #endif  /* pthread.h */