te
Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved.
Copyright 2016 Joyent, Inc.
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.
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.
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]
threads, pthreads - POSIX pthreads, c11, and illumos threads concepts

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

#include <pthread.h>

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

#include <threads.h>

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

#include <sched.h>

#include <thread.h>

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.

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. POSIX pthreads and illumos threads differ in the following ways: 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.

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.

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() -

POSIX illumos C11

pthread_exit() thr_exit() thrd_exit()

pthread_join() thr_join() thrd_join()

pthread_detach() - thrd_detach()

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()

POSIX illumos C11

pthread_sigmask() thr_sigsetmask() -

pthread_kill() thr_kill() -

POSIX illumos c11

pthread_self() thr_self() thrd_current()

pthread_equal() - thrd_equal()

- thr_main() -

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() -

POSIX illumos C11

pthread_cancel() - -

pthread_setcancelstate() - -

pthread_setcanceltype() - -

pthread_testcancel() - -

pthread_cleanup_pop() - -

pthread_cleanup_push() - -

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()

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()

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() - -

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() -

POSIX illumos C11

pthread_atfork() - -

POSIX illumos C11

pthread_once() - call_once()

POSIX illumos C11

- thr_stksegment() -

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.

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(). illumos supports the following three POSIX scheduling policies: SCHED_OTHER SCHED_FIFO SCHED_RR

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

SCHED_FSS SCHED_FX Only scheduling policy supported is SCHED_OTHER, which is timesharing, based on the TS scheduling class. In a multithreaded application, EINTR can be returned from blocking system calls when another thread calls forkall(2). 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.

See attributes(7) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

MT-Level MT-Safe, Fork 1-Safe

crle (1), fork (2), priocntl (2), pthread_atfork (3C), pthread_create (3C), libpthread (3LIB), librt (3LIB), libthread (3LIB), attributes (7), standards (7)

Linker and Libraries Guide