share/man/man5/threads.5

   1 '\" te
   2 .\" Copyright (c) 2008, Sun Microsystems, Inc.  All Rights Reserved.
   3 .\" Copyright 2016 Joyent, Inc.
   4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   7 .TH THREADS 5 "Mar 27, 2016"
   8 .SH NAME
   9 threads, pthreads \- POSIX pthreads, c11, and illumos threads concepts
  10 .SH SYNOPSIS
  11 .SS "POSIX"
  12 .LP
  13 .nf
  14 gcc [ \fIflag\fR... ] \fIfile\fR... [ \fIlibrary\fR... ]
  15 .fi
  16
  17 .LP
  18 .nf
  19 #include <pthread.h>
  20 .fi
  21
  22 .SS "C11"
  23 .LP
  24 .nf
  25 gcc -std=c11 [ \fIflag\fR... ] \fIfile\fR... [ \fIlibrary\fR... ]
  26 .fi
  27
  28 .LP
  29 .nf
  30 #include <threads.h>
  31 .fi
  32
  33 .SS "illumos"
  34 .LP
  35 .nf
  36 gcc [ \fIflag\fR... ] \fIfile\fR... [ \fIlibrary\fR... ]
  37 .fi
  38
  39 .LP
  40 .nf
  41 #include <sched.h>
  42 .fi
  43
  44 .LP
  45 .nf
  46 #include <thread.h>
  47 .fi
  48
  49 .SH DESCRIPTION
  50 .LP
  51 A thread is an independent source of execution within a process. Every process
  52 is created with a single thread, which calls the
  53 .B main
  54 function. A process may have multiple threads, all of which are scheduled
  55 independently by the system and may run concurrently. Threads within a process
  56 all use the same address space and as a result can access all data in the
  57 process; however, each thread is created with its own attributes and its own
  58 stack. When a thread is created, it inherits the signal mask of the thread which
  59 created it, but it has no pending signals.
  60 .sp
  61 .LP
  62 All threads of execution have their own, independent life time, though it is
  63 ultimately bounded by the life time of the process. If the process terminates
  64 for any reason, whether due to a call to \fBexit\fR(3C), the receipt of a fatal
  65 signal, or some other reason, then all threads within the process are
  66 terminated. Threads may themselves exit and status information of them may be
  67 obtained, for more information, see the \fBpthread_detach\fR(3C),
  68 \fBpthread_join\fR(3C), and \fBpthread_exit\fR(3C) functions, and their
  69 equivalents as described in the tables later on in the manual.
  70 .sp
  71 .LP
  72 Most hardware platforms do not have any special synchronization for data objects
  73 which may be accessed concurrently from multiple threads of execution. To avoid
  74 such problems, programs may use atomic operations (see \fBatomic_ops\fR(3C)) and
  75 locking primitives, such as mutexes, readers/writer locks, condition variables,
  76 and semaphores. Note, that depending on the hardware platform, memory
  77 synchronization may be necessary, for more information, see \fBmembar_ops\fR(3C).
  78 .LP
  79 POSIX, C11, and illumos threads each have their own implementation within
  80 \fBlibc\fR(3LIB). All implementations are interoperable, their functionality
  81 similar, and can be used within the same application. Only POSIX threads are
  82 guaranteed to be fully portable to other POSIX-compliant environments. C11
  83 threads are an optional part of ISO C11 and may not exist on every ISO C11
  84 platform. POSIX, C11, and illumos threads require different source and include
  85 files. See \fBSYNOPSIS\fR.
  86 .SS "Similarities"
  87 .LP
  88 Most of the POSIX and illumos threading functions have counterparts with each
  89 other. POSIX function names, with the exception of the semaphore names, have a
  90 "\fBpthread\fR" prefix. Function names for similar POSIX and illumos functions
  91 have similar endings. Typically, similar POSIX and illumos functions have the
  92 same number and use of arguments.
  93 .SS "Differences"
  94 .LP
  95 POSIX pthreads and illumos threads differ in the following ways:
  96 .RS +4
  97 .TP
  98 .ie t \(bu
  99 .el o
 100 POSIX threads are more portable.
 101 .RE
 102 .RS +4
 103 .TP
 104 .ie t \(bu
 105 .el o
 106 POSIX threads establish characteristics  for each thread according to
 107 configurable attribute objects.
 108 .RE
 109 .RS +4
 110 .TP
 111 .ie t \(bu
 112 .el o
 113 POSIX pthreads implement thread cancellation.
 114 .RE
 115 .RS +4
 116 .TP
 117 .ie t \(bu
 118 .el o
 119 POSIX pthreads enforce scheduling algorithms.
 120 .RE
 121 .RS +4
 122 .TP
 123 .ie t \(bu
 124 .el o
 125 POSIX pthreads allow for clean-up handlers for \fBfork\fR(2) calls.
 126 .RE
 127 .RS +4
 128 .TP
 129 .ie t \(bu
 130 .el o
 131 illumos threads can be suspended and continued.
 132 .RE
 133 .RS +4
 134 .TP
 135 .ie t \(bu
 136 .el o
 137 illumos threads implement daemon threads, for whose demise the process does not
 138 wait.
 139 .RE
 140 .SS "Comparison to C11 Threads"
 141 .LP
 142 C11 threads are not as functional as either POSIX or illumos threads. C11
 143 threads only support intra-process locking and do not have any form of
 144 readers/writer locking or semaphores. In general, POSIX threads will be more
 145 portable than C11 threads, all POSIX-compliant systems support pthreads;
 146 however, not all C environments support C11 Threads.
 147 .sp
 148 .LP
 149 In addition to lacking other common synchronization primitives, the ISO/IEC
 150 standard for C11 threads does not have rich error semantics. In an effort to not
 151 extend the set of error numbers standardized in ISO/IEC C11, none of the
 152 routines set errno and instead multiple distinguishable errors, aside from the
 153 equivalent to ENOMEM and EBUSY, are all squashed into one. As such, users of the
 154 platform are encouraged to use POSIX threads, unless a portability concern
 155 dictates otherwise.
 156
 157 .SH FUNCTION COMPARISON
 158 .LP
 159 The following table compares the POSIX pthreads, C11 threads, and illumos
 160 threads functions.  When a comparable interface is not available either in POSIX
 161 pthreads, C11 threads  or illumos threads, a hyphen (\fB-\fR) appears in the
 162 column.
 163 .SS "Functions Related to Creation"
 164
 165 .TS
 166 l l l
 167 l l l .
 168 \fBPOSIX\fR     \fBillumos\fR   \fBC11\fR
 169 \fBpthread_create()\fR  \fBthr_create()\fR      \fBthrd_create()\fR
 170 \fBpthread_attr_init()\fR       \fB-\fR \fB-\fR
 171 \fBpthread_attr_setdetachstate()\fR     \fB-\fR \fB-\fR
 172 \fBpthread_attr_getdetachstate()\fR     \fB-\fR \fB-\fR
 173 \fBpthread_attr_setinheritsched()\fR    \fB-\fR \fB-\fR
 174 \fBpthread_attr_getinheritsched()\fR    \fB-\fR \fB-\fR
 175 \fBpthread_attr_setschedparam()\fR      \fB-\fR \fB-\fR
 176 \fBpthread_attr_getschedparam()\fR      \fB-\fR \fB-\fR
 177 \fBpthread_attr_setschedpolicy()\fR     \fB-\fR \fB-\fR
 178 \fBpthread_attr_getschedpolicy()\fR     \fB-\fR \fB-\fR
 179 \fBpthread_attr_setscope()\fR   \fB-\fR \fB-\fR
 180 \fBpthread_attr_getscope()\fR   \fB-\fR \fB-\fR
 181 \fBpthread_attr_setstackaddr()\fR       \fB-\fR \fB-\fR
 182 \fBpthread_attr_getstackaddr()\fR       \fB-\fR \fB-\fR
 183 \fBpthread_attr_setstacksize()\fR       \fB-\fR \fB-\fR
 184 \fBpthread_attr_getstacksize()\fR       \fB-\fR \fB-\fR
 185 \fBpthread_attr_getguardsize()\fR       \fB-\fR \fB-\fR
 186 \fBpthread_attr_setguardsize()\fR       \fB-\fR \fB-\fR
 187 \fBpthread_attr_destroy()\fR    \fB-\fR \fB-\fR
 188 \fB-\fR \fBthr_min_stack()\fR   \fB-\fR
 189 .TE
 190
 191 .SS "Functions Related to Exit"
 192
 193 .TS
 194 l l l
 195 l l l .
 196 \fBPOSIX\fR     \fBillumos\fR   \fBC11\fR
 197 \fBpthread_exit()\fR    \fBthr_exit()\fR        \fBthrd_exit()\fR
 198 \fBpthread_join()\fR    \fBthr_join()\fR        \fBthrd_join()\fR
 199 \fBpthread_detach()\fR  \fB-\fR \fBthrd_detach()\fR
 200 .TE
 201
 202 .SS "Functions Related to Thread Specific Data"
 203
 204 .TS
 205 l l l
 206 l l l .
 207 \fBPOSIX\fR     \fBillumos\fR   \fBC11\fR
 208 \fBpthread_key_create()\fR      \fBthr_keycreate()\fR   \fBtss_create()\fR
 209 \fBpthread_setspecific()\fR     \fBthr_setspecific()\fR \fBtss_set()\fR
 210 \fBpthread_getspecific()\fR     \fBthr_getspecific()\fR \fBtss_get()\fR
 211 \fBpthread_key_delete()\fR      \fB-\fR \fBtss_delete()\fR
 212 .TE
 213
 214 .SS "Functions Related to Signals"
 215
 216 .TS
 217 l l l
 218 l l l .
 219 \fBPOSIX\fR     \fBillumos\fR   \fBC11\fR
 220 \fBpthread_sigmask()\fR \fBthr_sigsetmask()\fR  \fB-\fR
 221 \fBpthread_kill()\fR    \fBthr_kill()\fR        \fB-\fR
 222 .TE
 223
 224 .SS "Functions Related to IDs"
 225
 226 .TS
 227 l l l
 228 l l l .
 229 \fBPOSIX\fR     \fBillumos\fR   \fBc11\fR
 230 \fBpthread_self()\fR    \fBthr_self()\fR        \fBthrd_current()\fR
 231 \fBpthread_equal()\fR   \fB-\fR \fBthrd_equal()\fR
 232 \fB-\fR \fBthr_main()\fR        \fB-\fR
 233 .TE
 234
 235 .SS "Functions Related to Scheduling"
 236
 237 .TS
 238 l l l
 239 l l l .
 240 \fBPOSIX\fR     \fBillumos\fR   \fBC11\fR
 241 \fB-\fR \fBthr_yield()\fR       \fBthrd_yield()\fR
 242 \fB-\fR \fBthr_suspend()\fR     \fB-\fR
 243 \fB-\fR \fBthr_continue()\fR    \fB-\fR
 244 \fBpthread_setconcurrency()\fR  \fBthr_setconcurrency()\fR      \fB-\fR
 245 \fBpthread_getconcurrency()\fR  \fBthr_getconcurrency()\fR      \fB-\fR
 246 \fBpthread_setschedparam()\fR   \fBthr_setprio()\fR     \fB-\fR
 247 \fBpthread_setschedprio()\fR    \fBthr_setprio()\fR     \fB-\fR
 248 \fBpthread_getschedparam()\fR   \fBthr_getprio()\fR     \fB-\fR
 249 .TE
 250
 251 .SS "Functions Related to Cancellation"
 252
 253 .TS
 254 l l l
 255 l l l .
 256 \fBPOSIX\fR     \fBillumos\fR   \fBC11\fR
 257 \fBpthread_cancel()\fR  \fB-\fR \fB-\fR
 258 \fBpthread_setcancelstate()\fR  \fB-\fR \fB-\fR
 259 \fBpthread_setcanceltype()\fR   \fB-\fR \fB-\fR
 260 \fBpthread_testcancel()\fR      \fB-\fR \fB-\fR
 261 \fBpthread_cleanup_pop()\fR     \fB-\fR \fB-\fR
 262 \fBpthread_cleanup_push()\fR    \fB-\fR \fB-\fR
 263 .TE
 264
 265 .SS "Functions Related to Mutexes"
 266
 267 .TS
 268 l l l
 269 l l l .
 270 \fBPOSIX\fR     \fBillumos\fR   \fBc11\fR
 271 \fBpthread_mutex_init()\fR      \fBmutex_init()\fR      \fBmtx_init()\fR
 272 \fBpthread_mutexattr_init()\fR  \fB-\fR \fB-\fR
 273 \fBpthread_mutexattr_setpshared()\fR    \fB-\fR \fB-\fR
 274 \fBpthread_mutexattr_getpshared()\fR    \fB-\fR \fB-\fR
 275 \fBpthread_mutexattr_setprotocol()\fR   \fB-\fR \fB-\fR
 276 \fBpthread_mutexattr_getprotocol()\fR   \fB-\fR \fB-\fR
 277 \fBpthread_mutexattr_setprioceiling()\fR        \fB-\fR \fB-\fR
 278 \fBpthread_mutexattr_getprioceiling()\fR        \fB-\fR \fB-\fR
 279 \fBpthread_mutexattr_settype()\fR       \fB-\fR \fB-\fR
 280 \fBpthread_mutexattr_gettype()\fR       \fB-\fR \fB-\fR
 281 \fBpthread_mutexattr_setrobust()\fR     \fB-\fR \fB-\fR
 282 \fBpthread_mutexattr_getrobust()\fR     \fB-\fR \fB-\fR
 283 \fBpthread_mutexattr_destroy()\fR       \fB-\fR \fBmtx_destroy()\fR
 284 \fBpthread_mutex_setprioceiling()\fR    \fB-\fR \fB-\fR
 285 \fBpthread_mutex_getprioceiling()\fR    \fB-\fR \fB-\fR
 286 \fBpthread_mutex_lock()\fR      \fBmutex_lock()\fR      \fBmtx_lock()\fR
 287 \fBpthread_mutex_timedlock()\fR \fB-\fR \fBmtx_timedlock()\fR
 288 \fBpthread_mutex_trylock()\fR   \fBmutex_trylock()\fR   \fBmtx_trylock()\fR
 289 \fBpthread_mutex_unlock()\fR    \fBmutex_unlock()\fR    \fBmtx_unlcok()\fR
 290 \fBpthread_mutex_destroy()\fR   \fBmutex_destroy()\fR   \fBmtx_destroy()\fR
 291 .TE
 292
 293 .SS "Functions Related to Condition Variables"
 294
 295 .TS
 296 l l l
 297 l l l .
 298 \fBPOSIX\fR     \fBillumos\fR   \fBC11\fR
 299 \fBpthread_cond_init()\fR       \fBcond_init()\fR       \fBcnd_init()\fR
 300 \fBpthread_condattr_init()\fR   \fB-\fR \fB-\fR
 301 \fBpthread_condattr_setpshared()\fR     \fB-\fR \fB-\fR
 302 \fBpthread_condattr_getpshared()\fR     \fB-\fR \fB-\fR
 303 \fBpthread_condattr_destroy()\fR        \fB-\fR \fB-\fR
 304 \fBpthread_cond_wait()\fR       \fBcond_wait()\fR       \fBcnd_wait()\fR
 305 \fBpthread_cond_timedwait()\fR  \fBcond_timedwait()\fR  \fBcond_timedwait()\fR
 306 \fBpthread_cond_signal()\fR     \fBcond_signal()\fR     \fBcnd_signal()\fR
 307 \fBpthread_cond_broadcast()\fR  \fBcond_broadcast()\fR  \fBcnd_broadcast()\fR
 308 \fBpthread_cond_destroy()\fR    \fBcond_destroy()\fR    \fBcnd_destroy()\fR
 309 .TE
 310
 311 .SS "Functions Related to Reader/Writer Locking"
 312
 313 .TS
 314 l l l
 315 l l l .
 316 \fBPOSIX\fR     \fBillumos\fR   \fBC11\fR
 317 \fBpthread_rwlock_init()\fR     \fBrwlock_init()\fR     \fB-\fR
 318 \fBpthread_rwlock_rdlock()\fR   \fBrw_rdlock()\fR       \fB-\fR
 319 \fBpthread_rwlock_tryrdlock()\fR        \fBrw_tryrdlock()\fR    \fB-\fR
 320 \fBpthread_rwlock_wrlock()\fR   \fBrw_wrlock()\fR       \fB-\fR
 321 \fBpthread_rwlock_trywrlock()\fR        \fBrw_trywrlock()\fR    \fB-\fR
 322 \fBpthread_rwlock_unlock()\fR   \fBrw_unlock()\fR       \fB-\fR
 323 \fBpthread_rwlock_destroy()\fR  \fBrwlock_destroy()\fR  \fB-\fR
 324 \fBpthread_rwlockattr_init()\fR \fB-\fR \fB-\fR
 325 \fBpthread_rwlockattr_destroy()\fR      \fB-\fR \fB-\fR
 326 \fBpthread_rwlockattr_getpshared()\fR   \fB-\fR \fB-\fR
 327 \fBpthread_rwlockattr_setpshared()\fR   \fB-\fR \fB-\fR
 328 .TE
 329
 330 .SS "Functions Related to Semaphores"
 331
 332 .TS
 333 l l l
 334 l l l .
 335 \fBPOSIX\fR     \fBillumos\fR   \fBC11\fR
 336 \fBsem_init()\fR        \fBsema_init()\fR       \fB-\fR
 337 \fBsem_open()\fR        \fB-\fR \fB-\fR
 338 \fBsem_close()\fR       \fB-\fR \fB-\fR
 339 \fBsem_wait()\fR        \fBsema_wait()\ \fB-\fR
 340 \fBsem_trywait()\fR     \fBsema_trywait()\fR    \fB-\fR
 341 \fBsem_post()\fR        \fBsema_post()\fR       \fB-\fR
 342 \fBsem_getvalue()\fR    \fB-\fR \fB-\fR
 343 \fBsem_unlink()\fR      \fB-\fR \fB-\fR
 344 \fBsem_destroy()\fR     \fBsema_destroy()\fR    \fB-\fR
 345 .TE
 346
 347 .SS "Functions Related to fork(\|) Clean Up"
 348
 349 .TS
 350 l l l
 351 l l l .
 352 \fBPOSIX\fR     \fBillumos\fR   \fBC11\fR
 353 \fBpthread_atfork()\fR  \fB-\fR \fB-\fR
 354 .TE
 355
 356 .SS "Functions Related to Limits"
 357
 358 .TS
 359 l l l
 360 l l l .
 361 \fBPOSIX\fR     \fBillumos\fR   \fBC11\fR
 362 \fBpthread_once()\fR    \fB-\fR \fBcall_once()\fR
 363 .TE
 364
 365 .SS "Functions Related to Debugging"
 366
 367 .TS
 368 l l l
 369 l l l .
 370 \fBPOSIX\fR     \fBillumos\fR   \fBC11\fR
 371 \fB-\fR \fBthr_stksegment()\fR  \fB-\fR
 372 .TE
 373
 374 .SH LOCKING
 375 .SS "Synchronization"
 376 .LP
 377 Multithreaded behavior is asynchronous, and therefore,  optimized for
 378 concurrent and parallel processing. As threads, always from within the same
 379 process and  sometimes from multiple processes, share global data with each
 380 other, they are not guaranteed exclusive access to the shared data at any point
 381 in time. Securing mutually exclusive access to shared data requires
 382 synchronization among the threads. Both POSIX and illumos implement four
 383 synchronization mechanisms: mutexes, condition variables, reader/writer locking
 384 (\fIoptimized frequent-read occasional-write mutex\fR), and semaphores, where as
 385 C11 threads only implement two mechanisms: mutexes and condition variables.
 386 .sp
 387 .LP
 388 Synchronizing multiple threads diminishes their concurrency. The coarser the
 389 grain of synchronization, that is, the larger the block of code that is locked,
 390 the lesser the concurrency.
 391 .SS "MT \fBfork()\fR"
 392 .LP
 393 If a threads program calls \fBfork\fR(2), it implicitly calls \fBfork1\fR(2),
 394 which replicates only the calling thread. Should there be any outstanding
 395 mutexes throughout the process, the application should call
 396 \fBpthread_atfork\fR(3C) to wait for and acquire those mutexes prior to calling
 397 \fBfork()\fR.
 398 .SH SCHEDULING
 399 .SS "POSIX Threads"
 400 .LP
 401 illumos supports the following three POSIX scheduling policies:
 402 .sp
 403 .ne 2
 404 .na
 405 \fB\fBSCHED_OTHER\fR\fR
 406 .ad
 407 .RS 15n
 408 Traditional Timesharing scheduling policy. It is based on the timesharing (TS)
 409 scheduling class.
 410 .RE
 411
 412 .sp
 413 .ne 2
 414 .na
 415 \fB\fBSCHED_FIFO\fR\fR
 416 .ad
 417 .RS 15n
 418 First-In-First-Out scheduling policy. Threads scheduled to this policy, if not
 419 preempted by a higher priority, will proceed until completion. Such threads are
 420 in real-time (RT) scheduling class. The calling process must have a effective
 421 user \fBID\fR of \fB0\fR.
 422 .RE
 423
 424 .sp
 425 .ne 2
 426 .na
 427 \fB\fBSCHED_RR\fR\fR
 428 .ad
 429 .RS 15n
 430 Round-Robin scheduling policy. Threads scheduled to this policy, if not
 431 preempted by a higher priority, will execute for a time period determined by
 432 the system. Such threads are in real-time (RT) scheduling class and the calling
 433 process must have a effective user \fBID\fR of \fB0\fR.
 434 .RE
 435
 436 .sp
 437 .LP
 438 In addition to the POSIX-specified scheduling policies above, illumos also
 439 supports these scheduling policies:
 440 .sp
 441 .ne 2
 442 .na
 443 \fB\fBSCHED_IA\fR\fR
 444 .ad
 445 .RS 13n
 446 Threads are scheduled according to the Inter-Active Class (IA) policy as
 447 described in \fBpriocntl\fR(2).
 448 .RE
 449
 450 .sp
 451 .ne 2
 452 .na
 453 \fB\fBSCHED_FSS\fR\fR
 454 .ad
 455 .RS 13n
 456 Threads are scheduled according to the Fair-Share Class (FSS) policy as
 457 described in \fBpriocntl\fR(2).
 458 .RE
 459
 460 .sp
 461 .ne 2
 462 .na
 463 \fB\fBSCHED_FX\fR\fR
 464 .ad
 465 .RS 13n
 466 Threads are scheduled according to the Fixed-Priority Class (FX) policy as
 467 described in \fBpriocntl\fR(2).
 468 .RE
 469
 470 .SS "illumos Threads"
 471 .LP
 472 Only scheduling policy supported is \fBSCHED_OTHER\fR, which is timesharing,
 473 based on the \fBTS\fR scheduling class.
 474 .SH ERRORS
 475 .LP
 476 In a multithreaded application, \fBEINTR\fR can be returned from blocking
 477 system calls when another thread calls \fBforkall\fR(2).
 478 .SH ATTRIBUTES
 479 .LP
 480 See \fBattributes\fR(5) for descriptions of the following attributes:
 481 .sp
 482
 483 .sp
 484 .TS
 485 box;
 486 c | c
 487 l | l .
 488 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 489 _
 490 MT-Level        MT-Safe, Fork 1-Safe
 491 .TE
 492
 493 .SH SEE ALSO
 494 .LP
 495 \fBcrle\fR(1), \fBfork\fR(2), \fBpriocntl\fR(2), \fBlibpthread\fR(3LIB),
 496 \fBlibrt\fR(3LIB), \fBlibthread\fR(3LIB), \fBpthread_atfork\fR(3C),
 497 \fBpthread_create\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5)
 498 .sp
 499 .LP
 500 \fILinker and Libraries Guide\fR