manual/threads.texi

   1 @node POSIX Threads
   2 @c @node POSIX Threads, , Cryptographic Functions, Top
   3 @chapter POSIX Threads
   4 @c %MENU% POSIX Threads
   5 @cindex pthreads
   6
   7 This chapter describes the @glibcadj{} POSIX Thread implementation.
   8
   9 @menu
  10 * Thread-specific Data::          Support for creating and
  11                                   managing thread-specific data
  12 * Non-POSIX Extensions::          Additional functions to extend
  13                                   POSIX Thread functionality
  14 @end menu
  15
  16 @node Thread-specific Data
  17 @section Thread-specific Data
  18
  19 The @glibcadj{} implements functions to allow users to create and manage
  20 data specific to a thread.  Such data may be destroyed at thread exit,
  21 if a destructor is provided.  The following functions are defined:
  22
  23 @table @code
  24
  25 @item int pthread_key_create (pthread_key_t *@var{key}, void (*@var{destructor})(void*))
  26 Create a thread-specific data key for the calling thread, referenced by
  27 @var{key}.
  28
  29 Objects declared with the C++11 @code{thread_local} keyword are destroyed
  30 before thread-specific data, so they should not be used in thread-specific
  31 data destructors or even as members of the thread-specific data, since the
  32 latter is passed as an argument to the destructor function.
  33
  34 @item int pthread_key_delete (pthread_key_t @var{key})
  35 Destroy the thread-specific data @var{key} in the calling thread.  The
  36 destructor for the thread-specific data is not called during destruction, nor
  37 is it called during thread exit.
  38
  39 @item void *pthread_getspecific (pthread_key_t @var{key})
  40 Return the thread-specific data associated with @var{key} in the calling
  41 thread.
  42
  43 @item int pthread_setspecific (pthread_key_t @var{key}, const void *@var{value})
  44 Associate the thread-specific @var{value} with @var{key} in the calling thread.
  45
  46 @end table
  47
  48 @node Non-POSIX Extensions
  49 @section Non-POSIX Extensions
  50
  51 In addition to implementing the POSIX API for threads, @theglibc{} provides
  52 additional functions and interfaces to provide functionality not specified in
  53 the standard.
  54
  55 @menu
  56 * Default Thread Attributes::             Setting default attributes for
  57                                           threads in a process.
  58 @end menu
  59
  60 @node Default Thread Attributes
  61 @subsection Setting Process-wide defaults for thread attributes
  62
  63 @Theglibc{} provides non-standard API functions to set and get the default
  64 attributes used in the creation of threads in a process.
  65
  66 @deftypefun int pthread_getattr_default_np (pthread_attr_t *@var{attr})
  67 Get the default attribute values and set @var{attr} to match.  This
  68 function returns @math{0} on success and a non-zero error code on
  69 failure.
  70 @end deftypefun
  71
  72 @deftypefun int pthread_getattr_default_np (pthread_attr_t *@var{attr})
  73 Set the default attribute values to match the values in @var{attr}.  The
  74 function returns @math{0} on success and a non-zero error code on failure.
  75 The following error codes are defined for this function:
  76
  77 @table @code
  78 @item EINVAL
  79 At least one of the values in @var{attr} does not qualify as valid for the
  80 attributes or the stack address is set in the attribute.
  81 @item ENOMEM
  82 The system does not have sufficient memory.
  83 @end table
  84 @end deftypefun