Print this page
11622 clean up rarer mandoc lint warnings
*** 7,17 ****
.TH THREADS 5 "Mar 27, 2016"
.SH NAME
threads, pthreads \- POSIX pthreads, c11, and illumos threads concepts
.SH SYNOPSIS
.SS "POSIX"
- .LP
.nf
gcc -D_REENTRANT [ \fIflag\fR... ] \fIfile\fR... [ \fIlibrary\fR... ]
.fi
.LP
--- 7,16 ----
*** 18,28 ****
.nf
#include <pthread.h>
.fi
.SS "C11"
- .LP
.nf
gcc -std=c11 -D_REENTRANT [ \fIflag\fR... ] \fIfile\fR... [ \fIlibrary\fR... ]
.fi
.LP
--- 17,26 ----
*** 29,39 ****
.nf
#include <threads.h>
.fi
.SS "illumos"
- .LP
.nf
gcc -D_REENTRANT [ \fIflag\fR... ] \fIfile\fR... [ \fIlibrary\fR... ]
.fi
.LP
--- 27,36 ----
*** 45,55 ****
.nf
#include <thread.h>
.fi
.SH DESCRIPTION
- .LP
A thread is an independent source of execution within a process. Every process
is created with a single thread, which calls the
.B main
function. A process may have multiple threads, all of which are scheduled
independently by the system and may run concurrently. Threads within a process
--- 42,51 ----
*** 82,99 ****
guaranteed to be fully portable to other POSIX-compliant environments. C11
threads are an optional part of ISO C11 and may not exist on every ISO C11
platform. POSIX, C11, and illumos threads require different source and include
files. See \fBSYNOPSIS\fR.
.SS "Similarities"
- .LP
Most of the POSIX and illumos threading functions have counterparts with each
other. POSIX function names, with the exception of the semaphore names, have a
"\fBpthread\fR" prefix. Function names for similar POSIX and illumos functions
have similar endings. Typically, similar POSIX and illumos functions have the
same number and use of arguments.
.SS "Differences"
- .LP
POSIX pthreads and illumos threads differ in the following ways:
.RS +4
.TP
.ie t \(bu
.el o
--- 78,93 ----
*** 136,146 ****
.el o
illumos threads implement daemon threads, for whose demise the process does not
wait.
.RE
.SS "Comparison to C11 Threads"
- .LP
C11 threads are not as functional as either POSIX or illumos threads. C11
threads only support intra-process locking and do not have any form of
readers/writer locking or semaphores. In general, POSIX threads will be more
portable than C11 threads, all POSIX-compliant systems support pthreads;
however, not all C environments support C11 Threads.
--- 130,139 ----
*** 153,163 ****
equivalent to ENOMEM and EBUSY, are all squashed into one. As such, users of the
platform are encouraged to use POSIX threads, unless a portability concern
dictates otherwise.
.SH FUNCTION COMPARISON
- .LP
The following table compares the POSIX pthreads, C11 threads, and illumos
threads functions. When a comparable interface is not available either in POSIX
pthreads, C11 threads or illumos threads, a hyphen (\fB-\fR) appears in the
column.
.SS "Functions Related to Creation"
--- 146,155 ----
*** 334,344 ****
l l l .
\fBPOSIX\fR \fBillumos\fR \fBC11\fR
\fBsem_init()\fR \fBsema_init()\fR \fB-\fR
\fBsem_open()\fR \fB-\fR \fB-\fR
\fBsem_close()\fR \fB-\fR \fB-\fR
! \fBsem_wait()\fR \fBsema_wait()\ \fB-\fR
\fBsem_trywait()\fR \fBsema_trywait()\fR \fB-\fR
\fBsem_post()\fR \fBsema_post()\fR \fB-\fR
\fBsem_getvalue()\fR \fB-\fR \fB-\fR
\fBsem_unlink()\fR \fB-\fR \fB-\fR
\fBsem_destroy()\fR \fBsema_destroy()\fR \fB-\fR
--- 326,336 ----
l l l .
\fBPOSIX\fR \fBillumos\fR \fBC11\fR
\fBsem_init()\fR \fBsema_init()\fR \fB-\fR
\fBsem_open()\fR \fB-\fR \fB-\fR
\fBsem_close()\fR \fB-\fR \fB-\fR
! \fBsem_wait()\fR \fBsema_wait()\fR \fB-\fR
\fBsem_trywait()\fR \fBsema_trywait()\fR \fB-\fR
\fBsem_post()\fR \fBsema_post()\fR \fB-\fR
\fBsem_getvalue()\fR \fB-\fR \fB-\fR
\fBsem_unlink()\fR \fB-\fR \fB-\fR
\fBsem_destroy()\fR \fBsema_destroy()\fR \fB-\fR
*** 371,381 ****
\fB-\fR \fBthr_stksegment()\fR \fB-\fR
.TE
.SH LOCKING
.SS "Synchronization"
- .LP
Multithreaded behavior is asynchronous, and therefore, optimized for
concurrent and parallel processing. As threads, always from within the same
process and sometimes from multiple processes, share global data with each
other, they are not guaranteed exclusive access to the shared data at any point
in time. Securing mutually exclusive access to shared data requires
--- 363,372 ----
*** 387,405 ****
.LP
Synchronizing multiple threads diminishes their concurrency. The coarser the
grain of synchronization, that is, the larger the block of code that is locked,
the lesser the concurrency.
.SS "MT \fBfork()\fR"
- .LP
If a threads program calls \fBfork\fR(2), it implicitly calls \fBfork1\fR(2),
which replicates only the calling thread. Should there be any outstanding
mutexes throughout the process, the application should call
\fBpthread_atfork\fR(3C) to wait for and acquire those mutexes prior to calling
\fBfork()\fR.
.SH SCHEDULING
.SS "POSIX Threads"
- .LP
illumos supports the following three POSIX scheduling policies:
.sp
.ne 2
.na
\fB\fBSCHED_OTHER\fR\fR
--- 378,394 ----
*** 466,495 ****
Threads are scheduled according to the Fixed-Priority Class (FX) policy as
described in \fBpriocntl\fR(2).
.RE
.SS "illumos Threads"
- .LP
Only scheduling policy supported is \fBSCHED_OTHER\fR, which is timesharing,
based on the \fBTS\fR scheduling class.
.SH ERRORS
- .LP
In a multithreaded application, \fBEINTR\fR can be returned from blocking
system calls when another thread calls \fBforkall\fR(2).
.SH USAGE
.SS "\fB-mt\fR compiler option"
- .LP
The \fB-mt\fR compiler option compiles and links for multithreaded code. It
compiles source files with \(mi\fBD_REENTRANT\fR and augments the set of
support libraries properly.
.sp
.LP
Users of other compilers such as gcc and clang should manually set
\(mi\fBD_REENTRANT\fR on the compilation line. There are no other libraries or
flags necessary.
.SH ATTRIBUTES
- .LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp
.sp
.TS
--- 455,480 ----
*** 500,510 ****
_
MT-Level MT-Safe, Fork 1-Safe
.TE
.SH SEE ALSO
- .LP
\fBcrle\fR(1), \fBfork\fR(2), \fBpriocntl\fR(2), \fBlibpthread\fR(3LIB),
\fBlibrt\fR(3LIB), \fBlibthread\fR(3LIB), \fBpthread_atfork\fR(3C),
\fBpthread_create\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5)
.sp
.LP
--- 485,494 ----