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