# Concurrency support library

> C++ Atlas: `cppatlas.com/w/c/thread` | Source: https://en.cppreference.com/w/c/thread | Domain: Concurrency support | Standards: C11, C17, C23

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

## Official Specification Summary (cppreference)

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
- `thrd_create` (C11): creates a thread (function)
- `thrd_equal` (C11): checks if two identifiers refer to the same thread (function)
- `thrd_current` (C11): obtains the current thread identifier (function)
- `thrd_sleep` (C11): suspends execution of the calling thread for the given period of time (function)
- `thrd_yield` (C11): yields the current time slice (function)
- `thrd_exit` (C11): terminates the calling thread (function)
- `thrd_detach` (C11): detaches a thread (function)
- `thrd_join` (C11): blocks until a thread terminates (function)
- `thrd_success` (C11), `thrd_timedout`, `thrd_busy`, `thrd_nomem`, `thrd_error`: 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**

- `ATOMIC_BOOL_LOCK_FREE` (C11), `ATOMIC_CHAR_LOCK_FREE`, `ATOMIC_CHAR16_T_LOCK_FREE`, `ATOMIC_CHAR32_T_LOCK_FREE`, `ATOMIC_WCHAR_T_LOCK_FREE`, `ATOMIC_SHORT_LOCK_FREE`, `ATOMIC_INT_LOCK_FREE`, `ATOMIC_LONG_LOCK_FREE`, `ATOMIC_LLONG_LOCK_FREE`, `ATOMIC_POINTER_LOCK_FREE`: indicates that the given atomic type is lock-free (macro constant)
- `atomic_is_lock_free` (C11): indicates whether the atomic object is lock-free (function)
- `atomic_store` (C11), `atomic_store_explicit`: stores a value in an atomic object (function)
- `atomic_load` (C11), `atomic_load_explicit`: reads a value from an atomic object (function)
- `atomic_exchange` (C11), `atomic_exchange_explicit`: swaps a value with the value of an atomic object (function)
- `atomic_compare_exchange_strong` (C11), `atomic_compare_exchange_strong_explicit`, `atomic_compare_exchange_weak`, `atomic_compare_exchange_weak_explicit`: swaps a value with an atomic object if the old value is what is expected, otherwise reads the old value (function)
- `atomic_fetch_add` (C11), `atomic_fetch_add_explicit`: atomic addition (function)
- `atomic_fetch_sub` (C11), `atomic_fetch_sub_explicit`: atomic subtraction (function)
- `atomic_fetch_or` (C11), `atomic_fetch_or_explicit`: atomic bitwise OR (function)
- `atomic_fetch_xor` (C11), `atomic_fetch_xor_explicit`: atomic bitwise exclusive OR (function)
- `atomic_fetch_and` (C11), `atomic_fetch_and_explicit`: atomic bitwise AND (function)

**Flag type and operations**

- `atomic_flag` (C11): lock-free atomic boolean flag (struct)
- `atomic_flag_test_and_set` (C11), `atomic_flag_test_and_set_explicit`: sets an atomic_flag to true and returns the old value (function)
- `atomic_flag_clear` (C11), `atomic_flag_clear_explicit`: sets an atomic_flag to false (function)

**Initialization**

- `atomic_init` (C11): initializes an existing atomic object (function)
- `ATOMIC_VAR_INIT` (C11): initializes a new atomic object (function macro)
- `ATOMIC_FLAG_INIT` (C11): initializes a new `atomic_flag` (macro constant)

**Memory synchronization ordering**

- `memory_order` (C11): defines memory ordering constraints (enum)
- `kill_dependency` (C11): breaks a dependency chain for `memory_order_consume` (function macro)
- `atomic_thread_fence` (C11): generic memory order-dependent fence synchronization primitive (function)
- `atomic_signal_fence` (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` (until C23) `_Atomic bool` (since C23)
- `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
- `mtx_init` (C11): creates a mutex (function)
- `mtx_lock` (C11): blocks until locks a mutex (function)
- `mtx_timedlock` (C11): blocks until locks a mutex or times out (function)
- `mtx_trylock` (C11): locks a mutex or returns without blocking if already locked (function)
- `mtx_unlock` (C11): unlocks a mutex (function)
- `mtx_destroy` (C11): destroys a mutex (function)
- `mtx_plain` (C11), `mtx_recursive` (C11), `mtx_timed` (C11): defines the type of a mutex (enum)

**Call once**

- `call_once` (C11): calls a function exactly once (function)

### Condition variables

Defined in header `<threads.h>`

- `cnd_t`: condition variable identifier
- `cnd_init` (C11): creates a condition variable (function)
- `cnd_signal` (C11): unblocks one thread blocked on a condition variable (function)
- `cnd_broadcast` (C11): unblocks all threads blocked on a condition variable (function)
- `cnd_wait` (C11): blocks on a condition variable (function)
- `cnd_timedwait` (C11): blocks on a condition variable, with a timeout (function)
- `cnd_destroy` (C11): destroys a condition variable (function)

### Thread-local storage

Defined in header `<threads.h>`

- `thread_local` (C11): convenience macro for storage-class specifier `_Thread_local` (keyword macro)
- `tss_t`: thread-specific storage pointer
- `TSS_DTOR_ITERATIONS` (C11): maximum number of times destructors are called (macro constant)
- `tss_dtor_t` (C11): function pointer type `void(*)(void*)`, used for TSS destructor (typedef)
- `tss_create` (C11): creates thread-specific storage pointer with a given destructor (function)
- `tss_get` (C11): reads from thread-specific storage (function)
- `tss_set` (C11): write to thread-specific storage (function)
- `tss_delete` (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 `#undef`ing 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:2024):

  - 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](https://en.cppreference.com/w/cpp/thread)

### External links

GNU GCC Libc Manual: ISO C Mutexes

---
Attribution: content from https://en.cppreference.com/w/c/thread (cppreference.com), licensed under CC-BY-SA 3.0 and GFDL. Modified: converted to markdown, study notes added. Offline snapshot of 9 February 2025.