Tribblix: manual page: threads.7

THREADS(7) Standards, Environments, and Macros THREADS(7)

NAME

threads, pthreads - POSIX pthreads, c11, and illumos threads concepts

SYNOPSIS

POSIX

gcc -D_REENTRANT [ flag... ] file... [ library... ]

#include <pthread.h>

C11
gcc -std=c11 -D_REENTRANT [ flag... ] file... [ library... ]

#include <threads.h>

illumos
gcc -D_REENTRANT [ flag... ] file... [ library... ]

#include <sched.h>

#include <thread.h>

DESCRIPTION

A thread is an independent source of execution within a process.
Every process is created with a single thread, which calls the 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 all use the same address space and as a
result can access all data in the process; however, each thread is
created with its own attributes and its own stack. When a thread is
created, it inherits the signal mask of the thread which created it,
but it has no pending signals.

All threads of execution have their own, independent life time,
though it is ultimately bounded by the life time of the process. If
the process terminates for any reason, whether due to a call to
exit(3C), the receipt of a fatal signal, or some other reason, then
all threads within the process are terminated. Threads may themselves
exit and status information of them may be obtained, for more
information, see the pthread_detach(3C), pthread_join(3C), and
pthread_exit(3C) functions, and their equivalents as described in the
tables later on in the manual.

Most hardware platforms do not have any special synchronization for
data objects which may be accessed concurrently from multiple threads
of execution. To avoid such problems, programs may use atomic
operations (see atomic_ops(3C)) and locking primitives, such as
mutexes, readers/writer locks, condition variables, and semaphores.
Note, that depending on the hardware platform, memory synchronization
may be necessary, for more information, see membar_ops(3C).

POSIX, C11, and illumos threads each have their own implementation
within libc(3LIB). All implementations are interoperable, their
functionality similar, and can be used within the same application.
Only POSIX threads are 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
SYNOPSIS.

Similarities

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 "pthread" 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.

Differences

POSIX pthreads and illumos threads differ in the following ways:

o POSIX threads are more portable.

o POSIX threads establish characteristics for each thread
according to configurable attribute objects.

o POSIX pthreads implement thread cancellation.

o POSIX pthreads enforce scheduling algorithms.

o POSIX pthreads allow for clean-up handlers for fork(2)
calls.

o illumos threads can be suspended and continued.

o illumos threads implement daemon threads, for whose demise
the process does not wait.

Comparison to C11 Threads
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.

In addition to lacking other common synchronization primitives, the
ISO/IEC standard for C11 threads does not have rich error semantics.
In an effort to not extend the set of error numbers standardized in
ISO/IEC C11, none of the routines set errno and instead multiple
distinguishable errors, aside from the 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.

FUNCTION COMPARISON

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 (-) appears in the column.

Functions Related to Creation

POSIX illumos C11
pthread_create() thr_create() thrd_create()
pthread_attr_init() - -
pthread_attr_setdetachstate() - -
pthread_attr_getdetachstate() - -
pthread_attr_setinheritsched() - -
pthread_attr_getinheritsched() - -
pthread_attr_setschedparam() - -
pthread_attr_getschedparam() - -
pthread_attr_setschedpolicy() - -
pthread_attr_getschedpolicy() - -
pthread_attr_setscope() - -
pthread_attr_getscope() - -
pthread_attr_setstackaddr() - -
pthread_attr_getstackaddr() - -
pthread_attr_setstacksize() - -
pthread_attr_getstacksize() - -
pthread_attr_getguardsize() - -
pthread_attr_setguardsize() - -
pthread_attr_destroy() - -
- thr_min_stack() -

Functions Related to Exit

POSIX illumos C11
pthread_exit() thr_exit() thrd_exit()
pthread_join() thr_join() thrd_join()
pthread_detach() - thrd_detach()

Functions Related to Thread Specific Data

POSIX illumos C11
pthread_key_create() thr_keycreate() tss_create()
pthread_setspecific() thr_setspecific() tss_set()
pthread_getspecific() thr_getspecific() tss_get()
pthread_key_delete() - tss_delete()

Functions Related to Signals

POSIX illumos C11
pthread_sigmask() thr_sigsetmask() -
pthread_kill() thr_kill() -

Functions Related to IDs

POSIX illumos c11
pthread_self() thr_self() thrd_current()
pthread_equal() - thrd_equal()
- thr_main() -

Functions Related to Scheduling

POSIX illumos C11
- thr_yield() thrd_yield()
- thr_suspend() -
- thr_continue() -
pthread_setconcurrency() thr_setconcurrency() -
pthread_getconcurrency() thr_getconcurrency() -
pthread_setschedparam() thr_setprio() -
pthread_setschedprio() thr_setprio() -
pthread_getschedparam() thr_getprio() -

Functions Related to Cancellation

POSIX illumos C11
pthread_cancel() - -
pthread_setcancelstate() - -
pthread_setcanceltype() - -
pthread_testcancel() - -
pthread_cleanup_pop() - -
pthread_cleanup_push() - -

Functions Related to Mutexes

POSIX illumos c11
pthread_mutex_init() mutex_init() mtx_init()
pthread_mutexattr_init() - -
pthread_mutexattr_setpshared() - -
pthread_mutexattr_getpshared() - -
pthread_mutexattr_setprotocol() - -
pthread_mutexattr_getprotocol() - -
pthread_mutexattr_setprioceiling() - -
pthread_mutexattr_getprioceiling() - -
pthread_mutexattr_settype() - -
pthread_mutexattr_gettype() - -
pthread_mutexattr_setrobust() - -
pthread_mutexattr_getrobust() - -
pthread_mutexattr_destroy() - mtx_destroy()
pthread_mutex_setprioceiling() - -
pthread_mutex_getprioceiling() - -
pthread_mutex_lock() mutex_lock() mtx_lock()
pthread_mutex_timedlock() - mtx_timedlock()
pthread_mutex_trylock() mutex_trylock() mtx_trylock()
pthread_mutex_unlock() mutex_unlock() mtx_unlock()
pthread_mutex_destroy() mutex_destroy() mtx_destroy()

Functions Related to Condition Variables

POSIX illumos C11
pthread_cond_init() cond_init() cnd_init()
pthread_condattr_init() - -
pthread_condattr_setpshared() - -
pthread_condattr_getpshared() - -
pthread_condattr_destroy() - -
pthread_cond_wait() cond_wait() cnd_wait()
pthread_cond_timedwait() cond_timedwait() cond_timedwait()
pthread_cond_signal() cond_signal() cnd_signal()
pthread_cond_broadcast() cond_broadcast() cnd_broadcast()
pthread_cond_destroy() cond_destroy() cnd_destroy()

Functions Related to Reader/Writer Locking

POSIX illumos C11
pthread_rwlock_init() rwlock_init() -
pthread_rwlock_rdlock() rw_rdlock() -
pthread_rwlock_tryrdlock() rw_tryrdlock() -
pthread_rwlock_wrlock() rw_wrlock() -
pthread_rwlock_trywrlock() rw_trywrlock() -
pthread_rwlock_unlock() rw_unlock() -
pthread_rwlock_destroy() rwlock_destroy() -
pthread_rwlockattr_init() - -
pthread_rwlockattr_destroy() - -
pthread_rwlockattr_getpshared() - -
pthread_rwlockattr_setpshared() - -

Functions Related to Semaphores

POSIX illumos C11
sem_init() sema_init() -
sem_open() - -
sem_close() - -
sem_wait() sema_wait() -
sem_trywait() sema_trywait() -
sem_post() sema_post() -
sem_getvalue() - -
sem_unlink() - -
sem_destroy() sema_destroy() -

Functions Related to fork() Clean Up

POSIX illumos C11
pthread_atfork() - -

Functions Related to Limits

POSIX illumos C11
pthread_once() - call_once()

Functions Related to Debugging

POSIX illumos C11
- thr_stksegment() -

LOCKING

Synchronization

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 synchronization among the threads. Both POSIX
and illumos implement four synchronization mechanisms: mutexes,
condition variables, reader/writer locking (optimized frequent-read
occasional-write mutex), and semaphores, where as C11 threads only
implement two mechanisms: mutexes and condition variables.

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.

MT fork()
If a threads program calls fork(2), it implicitly calls fork1(2),
which replicates only the calling thread. Should there be any
outstanding mutexes throughout the process, the application should
call pthread_atfork(3C) to wait for and acquire those mutexes prior
to calling fork().

SCHEDULING

POSIX Threads

illumos supports the following three POSIX scheduling policies:

SCHED_OTHER
Traditional Timesharing scheduling policy. It is based
on the timesharing (TS) scheduling class.

SCHED_FIFO
First-In-First-Out scheduling policy. Threads
scheduled to this policy, if not preempted by a higher
priority, will proceed until completion. Such threads
are in real-time (RT) scheduling class. The calling
process must have a effective user ID of 0.

SCHED_RR
Round-Robin scheduling policy. Threads scheduled to
this policy, if not preempted by a higher priority,
will execute for a time period determined by the
system. Such threads are in real-time (RT) scheduling
class and the calling process must have a effective
user ID of 0.

In addition to the POSIX-specified scheduling policies above, illumos
also supports these scheduling policies:

SCHED_IA
Threads are scheduled according to the Inter-Active
Class (IA) policy as described in priocntl(2).

SCHED_FSS
Threads are scheduled according to the Fair-Share Class
(FSS) policy as described in priocntl(2).

SCHED_FX
Threads are scheduled according to the Fixed-Priority
Class (FX) policy as described in priocntl(2).

illumos Threads
Only scheduling policy supported is SCHED_OTHER, which is
timesharing, based on the TS scheduling class.

ERRORS

In a multithreaded application, EINTR can be returned from blocking
system calls when another thread calls forkall(2).

USAGE

-mt compiler option
The -mt compiler option compiles and links for multithreaded code. It
compiles source files with -D_REENTRANT and augments the set of
support libraries properly.

Users of other compilers such as gcc and clang should manually set
-D_REENTRANT on the compilation line. There are no other libraries or
flags necessary.

ATTRIBUTES