1 THREADS(5) Standards, Environments, and Macros THREADS(5) 2 3 4 5 NAME 6 threads, pthreads - POSIX pthreads, c11, and illumos threads concepts 7 8 SYNOPSIS 9 POSIX 10 gcc -D_REENTRANT [ flag... ] file... [ library... ] 11 12 13 #include <pthread.h> 14 15 16 C11 17 gcc -std=c11 -D_REENTRANT [ flag... ] file... [ library... ] 18 19 20 #include <threads.h> 21 22 23 illumos 24 gcc -D_REENTRANT [ flag... ] file... [ library... ] 25 26 27 #include <sched.h> 28 29 30 #include <thread.h> 31 32 33 DESCRIPTION 34 A thread is an independent source of execution within a process. Every 35 process is created with a single thread, which calls the main function. 36 A process may have multiple threads, all of which are scheduled 37 independently by the system and may run concurrently. Threads within a 38 process all use the same address space and as a result can access all 39 data in the process; however, each thread is created with its own 40 attributes and its own stack. When a thread is created, it inherits the 41 signal mask of the thread which created it, but it has no pending 42 signals. 43 44 45 All threads of execution have their own, independent life time, though 46 it is ultimately bounded by the life time of the process. If the 47 process terminates for any reason, whether due to a call to exit(3C), 48 the receipt of a fatal signal, or some other reason, then all threads 49 within the process are terminated. Threads may themselves exit and 50 status information of them may be obtained, for more information, see 51 the pthread_detach(3C), pthread_join(3C), and pthread_exit(3C) 52 functions, and their equivalents as described in the tables later on in 53 the manual. 54 55 56 Most hardware platforms do not have any special synchronization for 57 data objects which may be accessed concurrently from multiple threads 58 of execution. To avoid such problems, programs may use atomic 59 operations (see atomic_ops(3C)) and locking primitives, such as 60 mutexes, readers/writer locks, condition variables, and semaphores. 61 Note, that depending on the hardware platform, memory synchronization 62 may be necessary, for more information, see membar_ops(3C). 63 64 POSIX, C11, and illumos threads each have their own implementation 65 within libc(3LIB). All implementations are interoperable, their 66 functionality similar, and can be used within the same application. 67 Only POSIX threads are guaranteed to be fully portable to other POSIX- 68 compliant environments. C11 threads are an optional part of ISO C11 and 69 may not exist on every ISO C11 platform. POSIX, C11, and illumos 70 threads require different source and include files. See SYNOPSIS. 71 72 Similarities 73 Most of the POSIX and illumos threading functions have counterparts 74 with each other. POSIX function names, with the exception of the 75 semaphore names, have a "pthread" prefix. Function names for similar 76 POSIX and illumos functions have similar endings. Typically, similar 77 POSIX and illumos functions have the same number and use of arguments. 78 79 Differences 80 POSIX pthreads and illumos threads differ in the following ways: 81 82 o POSIX threads are more portable. 83 84 o POSIX threads establish characteristics for each thread 85 according to configurable attribute objects. 86 87 o POSIX pthreads implement thread cancellation. 88 89 o POSIX pthreads enforce scheduling algorithms. 90 91 o POSIX pthreads allow for clean-up handlers for fork(2) 92 calls. 93 94 o illumos threads can be suspended and continued. 95 96 o illumos threads implement daemon threads, for whose demise 97 the process does not wait. 98 99 Comparison to C11 Threads 100 C11 threads are not as functional as either POSIX or illumos threads. 101 C11 threads only support intra-process locking and do not have any form 102 of readers/writer locking or semaphores. In general, POSIX threads will 103 be more portable than C11 threads, all POSIX-compliant systems support 104 pthreads; however, not all C environments support C11 Threads. 105 106 107 In addition to lacking other common synchronization primitives, the 108 ISO/IEC standard for C11 threads does not have rich error semantics. In 109 an effort to not extend the set of error numbers standardized in 110 ISO/IEC C11, none of the routines set errno and instead multiple 111 distinguishable errors, aside from the equivalent to ENOMEM and EBUSY, 112 are all squashed into one. As such, users of the platform are 113 encouraged to use POSIX threads, unless a portability concern dictates 114 otherwise. 115 116 117 FUNCTION COMPARISON 118 The following table compares the POSIX pthreads, C11 threads, and 119 illumos threads functions. When a comparable interface is not 120 available either in POSIX pthreads, C11 threads or illumos threads, a 121 hyphen (-) appears in the column. 122 123 Functions Related to Creation 124 125 POSIX illumos C11 126 pthread_create() thr_create() thrd_create() 127 pthread_attr_init() - - 128 pthread_attr_setdetachstate() - - 129 pthread_attr_getdetachstate() - - 130 pthread_attr_setinheritsched() - - 131 pthread_attr_getinheritsched() - - 132 pthread_attr_setschedparam() - - 133 pthread_attr_getschedparam() - - 134 pthread_attr_setschedpolicy() - - 135 pthread_attr_getschedpolicy() - - 136 pthread_attr_setscope() - - 137 pthread_attr_getscope() - - 138 pthread_attr_setstackaddr() - - 139 pthread_attr_getstackaddr() - - 140 pthread_attr_setstacksize() - - 141 pthread_attr_getstacksize() - - 142 pthread_attr_getguardsize() - - 143 pthread_attr_setguardsize() - - 144 pthread_attr_destroy() - - 145 - thr_min_stack() - 146 147 148 Functions Related to Exit 149 150 POSIX illumos C11 151 pthread_exit() thr_exit() thrd_exit() 152 pthread_join() thr_join() thrd_join() 153 pthread_detach() - thrd_detach() 154 155 156 Functions Related to Thread Specific Data 157 158 POSIX illumos C11 159 pthread_key_create() thr_keycreate() tss_create() 160 pthread_setspecific() thr_setspecific() tss_set() 161 pthread_getspecific() thr_getspecific() tss_get() 162 pthread_key_delete() - tss_delete() 163 164 165 Functions Related to Signals 166 167 POSIX illumos C11 168 pthread_sigmask() thr_sigsetmask() - 169 pthread_kill() thr_kill() - 170 171 172 Functions Related to IDs 173 174 POSIX illumos c11 175 pthread_self() thr_self() thrd_current() 176 pthread_equal() - thrd_equal() 177 - thr_main() - 178 179 180 Functions Related to Scheduling 181 182 POSIX illumos C11 183 - thr_yield() thrd_yield() 184 - thr_suspend() - 185 - thr_continue() - 186 pthread_setconcurrency() thr_setconcurrency() - 187 pthread_getconcurrency() thr_getconcurrency() - 188 pthread_setschedparam() thr_setprio() - 189 pthread_setschedprio() thr_setprio() - 190 pthread_getschedparam() thr_getprio() - 191 192 193 Functions Related to Cancellation 194 195 POSIX illumos C11 196 pthread_cancel() - - 197 pthread_setcancelstate() - - 198 pthread_setcanceltype() - - 199 pthread_testcancel() - - 200 pthread_cleanup_pop() - - 201 pthread_cleanup_push() - - 202 203 204 Functions Related to Mutexes 205 206 POSIX illumos c11 207 pthread_mutex_init() mutex_init() mtx_init() 208 pthread_mutexattr_init() - - 209 pthread_mutexattr_setpshared() - - 210 pthread_mutexattr_getpshared() - - 211 pthread_mutexattr_setprotocol() - - 212 pthread_mutexattr_getprotocol() - - 213 pthread_mutexattr_setprioceiling() - - 214 pthread_mutexattr_getprioceiling() - - 215 pthread_mutexattr_settype() - - 216 pthread_mutexattr_gettype() - - 217 pthread_mutexattr_setrobust() - - 218 pthread_mutexattr_getrobust() - - 219 pthread_mutexattr_destroy() - mtx_destroy() 220 pthread_mutex_setprioceiling() - - 221 pthread_mutex_getprioceiling() - - 222 pthread_mutex_lock() mutex_lock() mtx_lock() 223 pthread_mutex_timedlock() - mtx_timedlock() 224 pthread_mutex_trylock() mutex_trylock() mtx_trylock() 225 pthread_mutex_unlock() mutex_unlock() mtx_unlock() 226 pthread_mutex_destroy() mutex_destroy() mtx_destroy() 227 228 229 Functions Related to Condition Variables 230 231 POSIX illumos C11 232 pthread_cond_init() cond_init() cnd_init() 233 pthread_condattr_init() - - 234 pthread_condattr_setpshared() - - 235 pthread_condattr_getpshared() - - 236 pthread_condattr_destroy() - - 237 pthread_cond_wait() cond_wait() cnd_wait() 238 pthread_cond_timedwait() cond_timedwait() cond_timedwait() 239 pthread_cond_signal() cond_signal() cnd_signal() 240 pthread_cond_broadcast() cond_broadcast() cnd_broadcast() 241 pthread_cond_destroy() cond_destroy() cnd_destroy() 242 243 244 Functions Related to Reader/Writer Locking 245 246 POSIX illumos C11 247 pthread_rwlock_init() rwlock_init() - 248 pthread_rwlock_rdlock() rw_rdlock() - 249 pthread_rwlock_tryrdlock() rw_tryrdlock() - 250 pthread_rwlock_wrlock() rw_wrlock() - 251 pthread_rwlock_trywrlock() rw_trywrlock() - 252 pthread_rwlock_unlock() rw_unlock() - 253 pthread_rwlock_destroy() rwlock_destroy() - 254 pthread_rwlockattr_init() - - 255 pthread_rwlockattr_destroy() - - 256 pthread_rwlockattr_getpshared() - - 257 pthread_rwlockattr_setpshared() - - 258 259 260 Functions Related to Semaphores 261 262 POSIX illumos C11 263 sem_init() sema_init() - 264 sem_open() - - 265 sem_close() - - 266 sem_wait() sema_wait() - 267 sem_trywait() sema_trywait() - 268 sem_post() sema_post() - 269 sem_getvalue() - - 270 sem_unlink() - - 271 sem_destroy() sema_destroy() - 272 273 274 Functions Related to fork() Clean Up 275 276 POSIX illumos C11 277 pthread_atfork() - - 278 279 280 Functions Related to Limits 281 282 POSIX illumos C11 283 pthread_once() - call_once() 284 285 286 Functions Related to Debugging 287 288 POSIX illumos C11 289 - thr_stksegment() - 290 291 292 LOCKING 293 Synchronization 294 Multithreaded behavior is asynchronous, and therefore, optimized for 295 concurrent and parallel processing. As threads, always from within the 296 same process and sometimes from multiple processes, share global data 297 with each other, they are not guaranteed exclusive access to the shared 298 data at any point in time. Securing mutually exclusive access to shared 299 data requires synchronization among the threads. Both POSIX and illumos 300 implement four synchronization mechanisms: mutexes, condition 301 variables, reader/writer locking (optimized frequent-read occasional- 302 write mutex), and semaphores, where as C11 threads only implement two 303 mechanisms: mutexes and condition variables. 304 305 306 Synchronizing multiple threads diminishes their concurrency. The 307 coarser the grain of synchronization, that is, the larger the block of 308 code that is locked, the lesser the concurrency. 309 310 MT fork() 311 If a threads program calls fork(2), it implicitly calls fork1(2), which 312 replicates only the calling thread. Should there be any outstanding 313 mutexes throughout the process, the application should call 314 pthread_atfork(3C) to wait for and acquire those mutexes prior to 315 calling fork(). 316 317 SCHEDULING 318 POSIX Threads 319 illumos supports the following three POSIX scheduling policies: 320 321 SCHED_OTHER 322 Traditional Timesharing scheduling policy. It is based 323 on the timesharing (TS) scheduling class. 324 325 326 SCHED_FIFO 327 First-In-First-Out scheduling policy. Threads scheduled 328 to this policy, if not preempted by a higher priority, 329 will proceed until completion. Such threads are in real- 330 time (RT) scheduling class. The calling process must 331 have a effective user ID of 0. 332 333 334 SCHED_RR 335 Round-Robin scheduling policy. Threads scheduled to this 336 policy, if not preempted by a higher priority, will 337 execute for a time period determined by the system. Such 338 threads are in real-time (RT) scheduling class and the 339 calling process must have a effective user ID of 0. 340 341 342 343 In addition to the POSIX-specified scheduling policies above, illumos 344 also supports these scheduling policies: 345 346 SCHED_IA 347 Threads are scheduled according to the Inter-Active Class 348 (IA) policy as described in priocntl(2). 349 350 351 SCHED_FSS 352 Threads are scheduled according to the Fair-Share Class 353 (FSS) policy as described in priocntl(2). 354 355 356 SCHED_FX 357 Threads are scheduled according to the Fixed-Priority 358 Class (FX) policy as described in priocntl(2). 359 360 361 illumos Threads 362 Only scheduling policy supported is SCHED_OTHER, which is timesharing, 363 based on the TS scheduling class. 364 365 ERRORS 366 In a multithreaded application, EINTR can be returned from blocking 367 system calls when another thread calls forkall(2). 368 369 USAGE 370 -mt compiler option 371 The -mt compiler option compiles and links for multithreaded code. It 372 compiles source files with -D_REENTRANT and augments the set of support 373 libraries properly. 374 375 376 Users of other compilers such as gcc and clang should manually set 377 -D_REENTRANT on the compilation line. There are no other libraries or 378 flags necessary. 379 380 ATTRIBUTES 381 See attributes(5) for descriptions of the following attributes: 382 383 384 385 386 +---------------+----------------------+ 387 |ATTRIBUTE TYPE | ATTRIBUTE VALUE | 388 +---------------+----------------------+ 389 |MT-Level | MT-Safe, Fork 1-Safe | 390 +---------------+----------------------+ 391 392 SEE ALSO 393 crle(1), fork(2), priocntl(2), libpthread(3LIB), librt(3LIB), 394 libthread(3LIB), pthread_atfork(3C), pthread_create(3C), attributes(5), 395 standards(5) 396 397 398 Linker and Libraries Guide 399 400 401 402 March 27, 2016 THREADS(5)