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