Docs4dev
Docs
c / latest / thread.html

Concurrency support library

C includes built-in support for threads, atomic operations, mutual exclusion, condition variables, and thread-specific storages.

These features are optionally provided:

  • if the macro constant __STDC_NO_THREADS__ is defined by the compiler, the header <threads.h> and all of the names provided in it are not provided;
  • if the macro constant __STDC_NO_ATOMICS__ is defined by the compiler, the header <stdatomic.h> and all of the names provided in it are not provided.

See also _Atomic type specifier and qualifier.

Threads

Defined in header <threads.h>
thrd_t implementation-defined complete object type identifying a thread
(C11)
creates a thread
(function)
(C11)
checks if two identifiers refer to the same thread
(function)
(C11)
obtains the current thread identifier
(function)
(C11)
suspends execution of the calling thread for the given period of time
(function)
(C11)
yields the current time slice
(function)
(C11)
terminates the calling thread
(function)
(C11)
detaches a thread
(function)
(C11)
blocks until a thread terminates
(function)
(C11)
indicates a thread error status
(constant)
thrd_start_t
(C11)
a typedef of the function pointer type int(*)(void*), used by thrd_create
(typedef)

Atomic operations

Defined in header <stdatomic.h>
Operations on atomic types
(C11)
indicates that the given atomic type is lock-free
(macro constant)
(C11)
indicates whether the atomic object is lock-free
(function)
(C11)
stores a value in an atomic object
(function)
(C11)
reads a value from an atomic object
(function)
(C11)
swaps a value with the value of an atomic object
(function)
(C11)
swaps a value with an atomic object if the old value is what is expected, otherwise reads the old value
(function)
(C11)
atomic addition
(function)
(C11)
atomic subtraction
(function)
(C11)
atomic bitwise OR
(function)
(C11)
atomic bitwise exclusive OR
(function)
(C11)
atomic bitwise AND
(function)
Flag type and operations
(C11)
lock-free atomic boolean flag
(struct)
(C11)
sets an atomic_flag to true and returns the old value
(function)
(C11)
sets an atomic_flag to false
(function)
Initialization
(C11)
initializes an existing atomic object
(function)
(C11)(deprecated in C17)(removed in C23)
initializes a new atomic object
(function macro)
(C11)
initializes a new atomic_flag
(macro constant)
Memory synchronization ordering
(C11)
defines memory ordering constraints
(enum)
(C11)
breaks a dependency chain for memory_order_consume
(function macro)
(C11)
generic memory order-dependent fence synchronization primitive
(function)
(C11)
fence between a thread and a signal handler executed in the same thread
(function)
Convenience type aliases
Typedef name Full type name
atomic_bool(C11) _Atomic _Bool
atomic_char(C11) _Atomic char
atomic_schar(C11) _Atomic signed char
atomic_uchar(C11) _Atomic unsigned char
atomic_short(C11) _Atomic short
atomic_ushort(C11) _Atomic unsigned short
atomic_int(C11) _Atomic int
atomic_uint(C11) _Atomic unsigned int
atomic_long(C11) _Atomic long
atomic_ulong(C11) _Atomic unsigned long
atomic_llong(C11) _Atomic long long
atomic_ullong(C11) _Atomic unsigned long long
atomic_char8_t(C23) _Atomic char8_t
atomic_char16_t(C11) _Atomic char16_t
atomic_char32_t(C11) _Atomic char32_t
atomic_wchar_t(C11) _Atomic wchar_t
atomic_int_least8_t(C11) _Atomic int_least8_t
atomic_uint_least8_t(C11) _Atomic uint_least8_t
atomic_int_least16_t(C11) _Atomic int_least16_t
atomic_uint_least16_t(C11) _Atomic uint_least16_t
atomic_int_least32_t(C11) _Atomic int_least32_t
atomic_uint_least32_t(C11) _Atomic uint_least32_t
atomic_int_least64_t(C11) _Atomic int_least64_t
atomic_uint_least64_t(C11) _Atomic uint_least64_t
atomic_int_fast8_t(C11) _Atomic int_fast8_t
atomic_uint_fast8_t(C11) _Atomic uint_fast8_t
atomic_int_fast16_t(C11) _Atomic int_fast16_t
atomic_uint_fast16_t(C11) _Atomic uint_fast16_t
atomic_int_fast32_t(C11) _Atomic int_fast32_t
atomic_uint_fast32_t(C11) _Atomic uint_fast32_t
atomic_int_fast64_t(C11) _Atomic int_fast64_t
atomic_uint_fast64_t(C11) _Atomic uint_fast64_t
atomic_intptr_t(C11) _Atomic intptr_t
atomic_uintptr_t(C11) _Atomic uintptr_t
atomic_size_t(C11) _Atomic size_t
atomic_ptrdiff_t(C11) _Atomic ptrdiff_t
atomic_intmax_t(C11) _Atomic intmax_t
atomic_uintmax_t(C11) _Atomic uintmax_t

Mutual exclusion

Defined in header <threads.h>
mtx_t mutex identifier
(C11)
creates a mutex
(function)
(C11)
blocks until locks a mutex
(function)
(C11)
blocks until locks a mutex or times out
(function)
(C11)
locks a mutex or returns without blocking if already locked
(function)
(C11)
unlocks a mutex
(function)
(C11)
destroys a mutex
(function)
(C11)(C11)(C11)
defines the type of a mutex
(enum)
Call once
(C11)
calls a function exactly once
(function)

Condition variables

Defined in header <threads.h>
cnd_t condition variable identifier
(C11)
creates a condition variable
(function)
(C11)
unblocks one thread blocked on a condition variable
(function)
(C11)
unblocks all threads blocked on a condition variable
(function)
(C11)
blocks on a condition variable
(function)
(C11)
blocks on a condition variable, with a timeout
(function)
(C11)
destroys a condition variable
(function)

Thread-local storage

Defined in header <threads.h>
(C11)(removed in C23)
convenience macro for storage-class specifier _Thread_local
(keyword macro)
tss_t thread-specific storage pointer
(C11)
maximum number of times destructors are called
(macro constant)
tss_dtor_t
(C11)
function pointer type void(*)(void*), used for TSS destructor
(typedef)
(C11)
creates thread-specific storage pointer with a given destructor
(function)
(C11)
reads from thread-specific storage
(function)
(C11)
write to thread-specific storage
(function)
(C11)
releases the resources held by a given thread-specific pointer
(function)

Reserved identifiers

In future revisions of the C standard:

  • function names, type names, and enumeration constants that begin with either cnd_, mtx_, thrd_, or tss_, and a lowercase letter may be added to the declarations in the <threads.h> header;
  • macros that begin with ATOMIC_ and an uppercase letter may be added to the macros defined in the <stdatomic.h> header;
  • typedef names that begin with either atomic_ or memory_, and a lowercase letter may be added to the declarations in the <stdatomic.h> header;
  • enumeration constants that begin with memory_order_ and a lowercase letter may be added to the definition of the memory_order type in the <stdatomic.h> header;
  • function names that begin with atomic_ and a lowercase letter may be added to the declarations in the <stdatomic.h> header.

Identifiers reserved for functions names are always potentially(since C23) reserved for use as identifiers with external linkage, while other identifiers list here are potentially(since C23) reserved when <stdatomic.h> is included.

Declaring, defining, or #undefing such an identifier results in undefined behavior if it is provided by the standard or implementation(since C23). Portable programs should not use those identifiers.

References

  • C23 standard (ISO/IEC 9899:2023):
    • 7.17 Atomics <stdatomic.h> (p: TBD)
    • 7.26 Threads <threads.h> (p: TBD)
    • 7.31.8 Atomics <stdatomic.h> (p: TBD)
    • 7.31.15 Threads <threads.h> (p: TBD)
  • C17 standard (ISO/IEC 9899:2018):
    • 7.17 Atomics <stdatomic.h> (p: 200-209)
    • 7.26 Threads <threads.h> (p: 274-283)
    • 7.31.8 Atomics <stdatomic.h> (p: 332)
    • 7.31.15 Threads <threads.h> (p: 333)
  • C11 standard (ISO/IEC 9899:2011):
    • 7.17 Atomics <stdatomic.h> (p: 273-286)
    • 7.26 Threads <threads.h> (p: 376-387)
    • 7.31.8 Atomics <stdatomic.h> (p: 455-456)
    • 7.31.15 Threads <threads.h> (p: 456)

See also

C++ documentation for Concurrency support library
GNU GCC Libc Manual: ISO C Mutexes

© cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
https://en.cppreference.com/w/c/thread