manual/threads.texi

   1 @node POSIX Threads
   2 @c @node POSIX Threads, Internal Probes, 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 @comment pthread.h
  24 @comment POSIX
  25 @deftypefun int pthread_key_create (pthread_key_t *@var{key}, void (*@var{destructor})(void*))
  26 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
  27 @c pthread_key_create ok
  28 @c  KEY_UNUSED ok
  29 @c  KEY_USABLE ok
  30 Create a thread-specific data key for the calling thread, referenced by
  31 @var{key}.
  32
  33 Objects declared with the C++11 @code{thread_local} keyword are destroyed
  34 before thread-specific data, so they should not be used in thread-specific
  35 data destructors or even as members of the thread-specific data, since the
  36 latter is passed as an argument to the destructor function.
  37 @end deftypefun
  38
  39 @comment pthread.h
  40 @comment POSIX
  41 @deftypefun int pthread_key_delete (pthread_key_t @var{key})
  42 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
  43 @c pthread_key_delete ok
  44 @c   This uses atomic compare and exchange to increment the seq number
  45 @c   after testing it's not a KEY_UNUSED seq number.
  46 @c  KEY_UNUSED dup ok
  47 Destroy the thread-specific data @var{key} in the calling thread.  The
  48 destructor for the thread-specific data is not called during destruction, nor
  49 is it called during thread exit.
  50 @end deftypefun
  51
  52 @comment pthread.h
  53 @comment POSIX
  54 @deftypefun void *pthread_getspecific (pthread_key_t @var{key})
  55 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
  56 @c pthread_getspecific ok
  57 Return the thread-specific data associated with @var{key} in the calling
  58 thread.
  59 @end deftypefun
  60
  61 @comment pthread.h
  62 @comment POSIX
  63 @deftypefun int pthread_setspecific (pthread_key_t @var{key}, const void *@var{value})
  64 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acucorrupt{} @acsmem{}}}
  65 @c pthread_setspecific @asucorrupt @ascuheap @acucorrupt @acsmem
  66 @c   a level2 block may be allocated by a signal handler after
  67 @c   another call already made a decision to allocate it, thus losing
  68 @c   the allocated value.  the seq number is updated before the
  69 @c   value, which might cause an earlier-generation value to seem
  70 @c   current if setspecific is cancelled or interrupted by a signal
  71 @c  KEY_UNUSED ok
  72 @c  calloc dup @ascuheap @acsmem
  73 Associate the thread-specific @var{value} with @var{key} in the calling thread.
  74 @end deftypefun
  75
  76
  77 @node Non-POSIX Extensions
  78 @section Non-POSIX Extensions
  79
  80 In addition to implementing the POSIX API for threads, @theglibc{} provides
  81 additional functions and interfaces to provide functionality not specified in
  82 the standard.
  83
  84 @menu
  85 * Default Thread Attributes::             Setting default attributes for
  86                                           threads in a process.
  87 @end menu
  88
  89 @node Default Thread Attributes
  90 @subsection Setting Process-wide defaults for thread attributes
  91
  92 @Theglibc{} provides non-standard API functions to set and get the default
  93 attributes used in the creation of threads in a process.
  94
  95 @comment pthread.h
  96 @comment GNU
  97 @deftypefun int pthread_getattr_default_np (pthread_attr_t *@var{attr})
  98 @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
  99 @c Takes lock around read from default_pthread_attr.
 100 Get the default attribute values and set @var{attr} to match.  This
 101 function returns @math{0} on success and a non-zero error code on
 102 failure.
 103 @end deftypefun
 104
 105 @comment pthread.h
 106 @comment GNU
 107 @deftypefun int pthread_setattr_default_np (pthread_attr_t *@var{attr})
 108 @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{}}}
 109 @c pthread_setattr_default_np @ascuheap @asulock @aculock @acsmem
 110 @c  check_sched_policy_attr ok
 111 @c  check_sched_priority_attr ok
 112 @c   sched_get_priority_min dup ok
 113 @c   sched_get_priority_max dup ok
 114 @c  check_cpuset_attr ok
 115 @c   determine_cpumask_size ok
 116 @c  check_stacksize_attr ok
 117 @c  lll_lock @asulock @aculock
 118 @c  free dup @ascuheap @acsmem
 119 @c  realloc dup @ascuheap @acsmem
 120 @c  memcpy dup ok
 121 @c  lll_unlock @asulock @aculock
 122 Set the default attribute values to match the values in @var{attr}.  The
 123 function returns @math{0} on success and a non-zero error code on failure.
 124 The following error codes are defined for this function:
 125
 126 @table @code
 127 @item EINVAL
 128 At least one of the values in @var{attr} does not qualify as valid for the
 129 attributes or the stack address is set in the attribute.
 130 @item ENOMEM
 131 The system does not have sufficient memory.
 132 @end table
 133 @end deftypefun
 134
 135 @c FIXME these are undocumented:
 136 @c pthread_atfork
 137 @c pthread_attr_destroy
 138 @c pthread_attr_getaffinity_np
 139 @c pthread_attr_getdetachstate
 140 @c pthread_attr_getguardsize
 141 @c pthread_attr_getinheritsched
 142 @c pthread_attr_getschedparam
 143 @c pthread_attr_getschedpolicy
 144 @c pthread_attr_getscope
 145 @c pthread_attr_getstack
 146 @c pthread_attr_getstackaddr
 147 @c pthread_attr_getstacksize
 148 @c pthread_attr_init
 149 @c pthread_attr_setaffinity_np
 150 @c pthread_attr_setdetachstate
 151 @c pthread_attr_setguardsize
 152 @c pthread_attr_setinheritsched
 153 @c pthread_attr_setschedparam
 154 @c pthread_attr_setschedpolicy
 155 @c pthread_attr_setscope
 156 @c pthread_attr_setstack
 157 @c pthread_attr_setstackaddr
 158 @c pthread_attr_setstacksize
 159 @c pthread_barrierattr_destroy
 160 @c pthread_barrierattr_getpshared
 161 @c pthread_barrierattr_init
 162 @c pthread_barrierattr_setpshared
 163 @c pthread_barrier_destroy
 164 @c pthread_barrier_init
 165 @c pthread_barrier_wait
 166 @c pthread_cancel
 167 @c pthread_cleanup_push
 168 @c pthread_cleanup_pop
 169 @c pthread_condattr_destroy
 170 @c pthread_condattr_getclock
 171 @c pthread_condattr_getpshared
 172 @c pthread_condattr_init
 173 @c pthread_condattr_setclock
 174 @c pthread_condattr_setpshared
 175 @c pthread_cond_broadcast
 176 @c pthread_cond_destroy
 177 @c pthread_cond_init
 178 @c pthread_cond_signal
 179 @c pthread_cond_timedwait
 180 @c pthread_cond_wait
 181 @c pthread_create
 182 @c pthread_detach
 183 @c pthread_equal
 184 @c pthread_exit
 185 @c pthread_getaffinity_np
 186 @c pthread_getattr_np
 187 @c pthread_getconcurrency
 188 @c pthread_getcpuclockid
 189 @c pthread_getname_np
 190 @c pthread_getschedparam
 191 @c pthread_join
 192 @c pthread_kill
 193 @c pthread_kill_other_threads_np
 194 @c pthread_mutexattr_destroy
 195 @c pthread_mutexattr_getkind_np
 196 @c pthread_mutexattr_getprioceiling
 197 @c pthread_mutexattr_getprotocol
 198 @c pthread_mutexattr_getpshared
 199 @c pthread_mutexattr_getrobust
 200 @c pthread_mutexattr_getrobust_np
 201 @c pthread_mutexattr_gettype
 202 @c pthread_mutexattr_init
 203 @c pthread_mutexattr_setkind_np
 204 @c pthread_mutexattr_setprioceiling
 205 @c pthread_mutexattr_setprotocol
 206 @c pthread_mutexattr_setpshared
 207 @c pthread_mutexattr_setrobust
 208 @c pthread_mutexattr_setrobust_np
 209 @c pthread_mutexattr_settype
 210 @c pthread_mutex_consistent
 211 @c pthread_mutex_consistent_np
 212 @c pthread_mutex_destroy
 213 @c pthread_mutex_getprioceiling
 214 @c pthread_mutex_init
 215 @c pthread_mutex_lock
 216 @c pthread_mutex_setprioceiling
 217 @c pthread_mutex_timedlock
 218 @c pthread_mutex_trylock
 219 @c pthread_mutex_unlock
 220 @c pthread_once
 221 @c pthread_rwlockattr_destroy
 222 @c pthread_rwlockattr_getkind_np
 223 @c pthread_rwlockattr_getpshared
 224 @c pthread_rwlockattr_init
 225 @c pthread_rwlockattr_setkind_np
 226 @c pthread_rwlockattr_setpshared
 227 @c pthread_rwlock_destroy
 228 @c pthread_rwlock_init
 229 @c pthread_rwlock_rdlock
 230 @c pthread_rwlock_timedrdlock
 231 @c pthread_rwlock_timedwrlock
 232 @c pthread_rwlock_tryrdlock
 233 @c pthread_rwlock_trywrlock
 234 @c pthread_rwlock_unlock
 235 @c pthread_rwlock_wrlock
 236 @c pthread_self
 237 @c pthread_setaffinity_np
 238 @c pthread_setcancelstate
 239 @c pthread_setcanceltype
 240 @c pthread_setconcurrency
 241 @c pthread_setname_np
 242 @c pthread_setschedparam
 243 @c pthread_setschedprio
 244 @c pthread_sigmask
 245 @c pthread_sigqueue
 246 @c pthread_spin_destroy
 247 @c pthread_spin_init
 248 @c pthread_spin_lock
 249 @c pthread_spin_trylock
 250 @c pthread_spin_unlock
 251 @c pthread_testcancel
 252 @c pthread_timedjoin_np
 253 @c pthread_tryjoin_np
 254 @c pthread_yield