Names specified here
Name Description Notes Source Availability
__STDC_NO_ATOMICS__ Indicator of lack of standard atomics L ? M Predefined C11
_Atomic Type specifier for atomic types L ? Q Keyword C11
atomic_compare_exchange_strong_explicit() Compare and then exchange a value with an atomic variable according to explicit constraints without spurious failure L (·) Predefined C11
atomic_compare_exchange_weak_explicit() Compare and then exchange a value with an atomic variable according to explicit constraints L (·) Predefined C11
Names specified for <stdatomic.h>, “Atomics”
Name Description Notes Source Availability
ATOMIC_BOOL_LOCK_FREE Lock-free property of type atomic_bool ? M <stdatomic.h> C11
ATOMIC_CHAR16_T_LOCK_FREE Lock-free property of type atomic_char16_t ? M <stdatomic.h> C11
ATOMIC_CHAR32_T_LOCK_FREE Lock-free property of type atomic_char32_t ? M <stdatomic.h> C11
ATOMIC_CHAR_LOCK_FREE Lock-free property of type atomic_char ? M <stdatomic.h> C11
ATOMIC_FLAG_INIT Initializer for atomic_flag ? M <stdatomic.h> C11
ATOMIC_INT_LOCK_FREE Lock-free property of type atomic_int ? M <stdatomic.h> C11
ATOMIC_LLONG_LOCK_FREE Lock-free property of type atomic_llong ? M <stdatomic.h> C11
ATOMIC_LONG_LOCK_FREE Lock-free property of type atomic_long ? M <stdatomic.h> C11
ATOMIC_POINTER_LOCK_FREE Lock-free property of pointer-to-object types ? M <stdatomic.h> C11
ATOMIC_SHORT_LOCK_FREE Lock-free property of type atomic_short ? M <stdatomic.h> C11
ATOMIC_VAR_INIT Initializer for atomic types ? M <stdatomic.h> C11
ATOMIC_WCHAR_T_LOCK_FREE Lock-free property of type atomic_wchar_t ? M <stdatomic.h> C11
atomic Type specifier for atomic types ? M Q <stdatomic.h> C11
atomic_bool Atomic boolean type ? T <stdatomic.h> C11
atomic_char Atomic character type ? T <stdatomic.h> C11
atomic_char16_t Atomic character type ? T <stdatomic.h> C11
atomic_char32_t Atomic character type ? T <stdatomic.h> C11
atomic_compare_exchange_strong() Compare and then exchange a value with an atomic variable without spurious failure ? (·) <stdatomic.h> C11
atomic_compare_exchange_weak() Compare and then exchange a value with an atomic variable ? (·) <stdatomic.h> C11
atomic_exchange() Exchange a value with an atomic variable ? (·) <stdatomic.h> C11
atomic_exchange_explicit() Exchange a value with an atomic variable according to explicit constraints ? (·) <stdatomic.h> C11
atomic_fetch_add() Update atomic variable with computed value ? (·) <stdatomic.h> C11
atomic_fetch_add_explicit() Update atomic variable with computed value according to explicit constraints ? (·) <stdatomic.h> C11
atomic_fetch_and() Update atomic variable with computed value ? (·) <stdatomic.h> C11
atomic_fetch_and_explicit() Update atomic variable with computed value according to explicit constraints ? (·) <stdatomic.h> C11
atomic_fetch_or() Update atomic variable with computed value ? (·) <stdatomic.h> C11
atomic_fetch_or_explicit() Update atomic variable with computed value according to explicit constraints ? (·) <stdatomic.h> C11
atomic_fetch_sub() Update atomic variable with computed value ? (·) <stdatomic.h> C11
atomic_fetch_sub_explicit() Update atomic variable with computed value according to explicit constraints ? (·) <stdatomic.h> C11
atomic_fetch_xor() Update atomic variable with computed value ? (·) <stdatomic.h> C11
atomic_fetch_xor_explicit() Update atomic variable with computed value according to explicit constraints ? (·) <stdatomic.h> C11
atomic_flag Lock-free atomic flag ? T <stdatomic.h> C11
atomic_flag_clear() Atomically clear variable returning previous value ? (·) <stdatomic.h> C11
atomic_flag_clear_explicit() Atomically clear variable returning previous value according to explicit constraints ? (·) <stdatomic.h> C11
atomic_flag_test_and_set() Atomically set variable returning previous value ? (·) <stdatomic.h> C11
atomic_flag_test_and_set_explicit() Atomically set variable returning previous value according to explicit constraints ? (·) <stdatomic.h> C11
atomic_init() Initialise atomic variable ? (·) <stdatomic.h> C11
atomic_int Atomic integer type ? T <stdatomic.h> C11
atomic_int_fast16_t Atomic integer type ? T <stdatomic.h> C11
atomic_int_fast32_t Atomic integer type ? T <stdatomic.h> C11
atomic_int_fast64_t Atomic integer type ? T <stdatomic.h> C11
atomic_int_fast8_t Atomic integer type ? T <stdatomic.h> C11
atomic_int_least16_t Atomic integer type ? T <stdatomic.h> C11
atomic_int_least32_t Atomic integer type ? T <stdatomic.h> C11
atomic_int_least64_t Atomic integer type ? T <stdatomic.h> C11
atomic_int_least8_t Atomic integer type ? T <stdatomic.h> C11
atomic_intmax_t Atomic integer type ? T <stdatomic.h> C11
atomic_intptr_t Atomic integer type ? T <stdatomic.h> C11
atomic_is_lock_free() Test lock-free property of atomic variable ? (·) <stdatomic.h> C11
atomic_llong Atomic integer type ? T <stdatomic.h> C11
atomic_load() Read an atomic variable ? (·) <stdatomic.h> C11
atomic_load_explicit() Read an atomic variable according to explicit constraints ? (·) <stdatomic.h> C11
atomic_long Atomic integer type ? T <stdatomic.h> C11
atomic_ptrdiff_t Atomic integer type ? T <stdatomic.h> C11
atomic_schar Atomic character type ? T <stdatomic.h> C11
atomic_short Atomic integer type ? T <stdatomic.h> C11
atomic_signal_fence() Declare fence between thread ∧ signal handler ? (·) <stdatomic.h> C11
atomic_size_t Atomic integer type ? T <stdatomic.h> C11
atomic_store() Write an atomic variable ? (·) <stdatomic.h> C11
atomic_store_explicit() Write an atomic variable according to explicit constraints ? (·) <stdatomic.h> C11
atomic_thread_fence() Declare a fence between threads ? (·) <stdatomic.h> C11
atomic_uchar Atomic character type ? T <stdatomic.h> C11
atomic_uint Atomic integer type ? T <stdatomic.h> C11
atomic_uint_fast16_t Atomic integer type ? T <stdatomic.h> C11
atomic_uint_fast32_t Atomic integer type ? T <stdatomic.h> C11
atomic_uint_fast64_t Atomic integer type ? T <stdatomic.h> C11
atomic_uint_fast8_t Atomic integer type ? T <stdatomic.h> C11
atomic_uint_least16_t Atomic integer type ? T <stdatomic.h> C11
atomic_uint_least32_t Atomic integer type ? T <stdatomic.h> C11
atomic_uint_least64_t Atomic integer type ? T <stdatomic.h> C11
atomic_uint_least8_t Atomic integer type ? T <stdatomic.h> C11
atomic_uintmax_t Atomic integer type ? T <stdatomic.h> C11
atomic_uintptr_t Atomic integer type ? T <stdatomic.h> C11
atomic_ullong Atomic integer type ? T <stdatomic.h> C11
atomic_ulong Atomic integer type ? T <stdatomic.h> C11
atomic_ushort Atomic integer type ? T <stdatomic.h> C11
atomic_wchar_t Atomic character type ? T <stdatomic.h> C11
kill_dependency() Terminate dependency chain ? M (·) <stdatomic.h> C11
memory_order Type for memory-ordering constraints ? T <stdatomic.h> C11
memory_order_acq_rel Memory-order constraint ? <stdatomic.h> C11
memory_order_acquire Memory-order constraint ? <stdatomic.h> C11
memory_order_consume Memory-order constraint ? <stdatomic.h> C11
memory_order_relaxed Memory-order constraint ? <stdatomic.h> C11
memory_order_release Memory-order constraint ? <stdatomic.h> C11
memory_order_seq_cst Memory-order constraint ? <stdatomic.h> C11

This header is available in C11.

[ Work in progress : Translate this page.]
The shield wall has been penetrated by atomics!

C11 specifies functions and types for atomic operations on data shared between threads in <stdatomic.h>. These are only available if __STDC_NO_ATOMICS__ is not defined. (It expands to 1 if it is.)

The keyword _Atomic modifies a type to make it atomic. It can only be applied to native types, pointer-to-object types, or their typedef equivalents.

Say something about how _Atomic can wrap around a type.

<stdatomic.h> defines a number of type aliases for atomic types:

Alias Atomic type Lock-free indicator
atomic_flag Unspecified Always lock free
None _Atomic pointer-to-object-type ATOMIC_POINTER_LOCK_FREE
atomic_bool _Atomic bool ATOMIC_BOOL_LOCK_FREE
atomic_uchar _Atomic unsigned char ATOMIC_CHAR_LOCK_FREE
atomic_char _Atomic char
atomic_schar _Atomic signed char
atomic_ushort _Atomic unsigned short ATOMIC_SHORT_LOCK_FREE
atomic_short _Atomic short
atomic_uint _Atomic unsigned ATOMIC_INT_LOCK_FREE
atomic_int _Atomic int
atomic_ulong _Atomic unsigned long ATOMIC_LONG_LOCK_FREE
atomic_long _Atomic long
atomic_ullong _Atomic unsigned long long ATOMIC_LLONG_LOCK_FREE
atomic_llong _Atomic long long
atomic_wchar_t _Atomic wchar_t ATOMIC_WCHAR_T_LOCK_FREE
atomic_char16_t _Atomic char16_t ATOMIC_CHAR16_T_LOCK_FREE
atomic_char32_t _Atomic char32_t ATOMIC_CHAR32_T_LOCK_FREE
atomic_size_t _Atomic size_t [No way to tell?]
atomic_ptrdiff_t _Atomic ptrdiff_t [No way to tell?]
atomic_uint_least8_t _Atomic uint_least8_t [No way to tell?]
atomic_int_least8_t _Atomic int_least8_t
atomic_uint_least16_t _Atomic uint_least16_t [No way to tell?]
atomic_int_least16_t _Atomic int_least16_t
atomic_uint_least32_t _Atomic uint_least32_t [No way to tell?]
atomic_int_least32_t _Atomic int_least32_t
atomic_uint_least64_t _Atomic uint_least64_t [No way to tell?]
atomic_int_least64_t _Atomic int_least64_t
atomic_uint_fast8_t _Atomic uint_fast8_t [No way to tell?]
atomic_int_fast8_t _Atomic int_fast8_t
atomic_uint_fast16_t _Atomic uint_fast16_t [No way to tell?]
atomic_int_fast16_t _Atomic int_fast16_t
atomic_uint_fast32_t _Atomic uint_fast32_t [No way to tell?]
atomic_int_fast32_t _Atomic int_fast32_t
atomic_uint_fast64_t _Atomic uint_fast64_t [No way to tell?]
atomic_int_fast64_t _Atomic int_fast64_t

typedef names matching ^atomic_[a-z] might be added to <stdatomic.h>.

Function with names matching ^atomic_[a-z] might be added to <stdatomic.h>.

typedef names matching ^memory_[a-z] might be added to <stdatomic.h>.

Enumeration constants with names matching ^memory_order_[a-z] might be added to memory_order in <stdatomic.h>.

Initialization of atomics

#include <stdatomic.h>
atomic-type ATOMIC_VAR_INIT(non-atomic-type val);
void atomic_init(volatile atomic-type *ptr, non-atomic-type val);

A static or thread-local [Why does thread-local even matter? It cannot be accessed by multiple threads anyway.] atomic variable is safely zero-initialized by default. Atomic variables can also be initialized explicitly at declaration with ATOMIC_VAR_INIT:

atomic_int obj = ATOMIC_VAR_INIT(10);
[ Work in progress : What's the use of a thread-local atomic?]

Atomic flags should be initialized with ATOMIC_FLAG_INIT:

atomic_flag obj = ATOMIC_FLAG_INIT;

To initialize at a point other than the declaration, use atomic_init:

atomic_int obj;
atomic_init(&obj, 10);

Automatic variables must be initialized with ATOMIC_VAR_INIT, ATOMIC_FLAG_INIT or atomic_init. Note that these three approaches do not prevent race conditions.

Atomic operations

An operation on an atomic variable is safe to a limited degree from race conditions caused by multiple threads attempting to update the same variable. Modifications to atomic variables must be done through a limited set of generic functions and macros declared by <stdatomic.h>. In their declarations, atomic-type matches any atomic type. non-atomic-type matches the corresponding non-atomic type. atomic-modifying-type is the same, except when dealing with atomic pointer types, in which case, it is ptrdiff_t.

#include <stdatomic.h>

void atomic_store(volatile atomic-type *obj,
                  non-atomic-type value);
void atomic_store_explicit(volatile atomic-type *obj,
                           non-atomic-type value,
                           memory_order order);
#include <stdatomic.h>

non-atomic-type atomic_load(volatile atomic-type *obj);
non-atomic-type atomic_load_explicit(volatile atomic-type *obj,
                                    memory_order order);
#include <stdatomic.h>

non-atomic-type atomic_exchange(volatile atomic-type *obj,
                               non-atomic-type value);
non-atomic-type atomic_exchange_explicit(volatile atomic-type *obj,
                                        non-atomic-type value,
                                        memory_order order);
#include <stdatomic.h>

_Bool
atomic_compare_exchange_strong(volatile atomic-type *obj,
                                        non-atomic-type *expect,
                                        non-atomic-type value);
_Bool
atomic_compare_exchange_strong_explicit(volatile atomic-type *obj,
                                        non-atomic-type *expect,
                                        non-atomic-type value,
                                        memory_order success,
                                        memory_order failure);

_Bool
atomic_compare_exchange_weak(volatile atomic-type *obj,
                             non-atomic-type *expect,
                             non-atomic-type value);
_Bool
atomic_compare_exchange_weak_explicit(volatile atomic-type *obj,
                                      non-atomic-type *expect,
                                      non-atomic-type value,
                                      memory_order success,
                                      memory_order failure);
#include <stdatomic.h>

non-atomic-type atomic_fetch_add(volatile atomic-type *obj,
                               atomic-modifying-type value);
non-atomic-type atomic_fetch_sub(volatile atomic-type *obj,
                               atomic-modifying-type value);
non-atomic-type atomic_fetch_or(volatile atomic-type *obj,
                               atomic-modifying-type value);
non-atomic-type atomic_fetch_xor(volatile atomic-type *obj,
                               atomic-modifying-type value);
non-atomic-type atomic_fetch_and(volatile atomic-type *obj,
                               atomic-modifying-type value);
#include <stdatomic.h>

_Bool
atomic_flag_test_and_set(volatile atomic_flag *obj);
_Bool
atomic_flag_test_and_set_explicit(volatile atomic_flag *obj,
                                  memory_order order);
#include <stdatomic.h>

void atomic_flag_clear(volatile atomic_flag *obj);
void atomic_flag_clear_explicit(volatile atomic_flag *obj,
                                memory_order order);

Lock-free property

#include <stdatomic.h>
_Bool atomic_is_lock_free(const volatile atomic-type *ptr);

Some atomic objects are lock-free. [But what does that mean?] You can determine whether an atomic object obj is lock-free by calling atomic_is_lock_free(&obj). Each of the macros ending in _LOCK_FREE expands to 2 if the corresponding type is always lock-free, 1 if sometimes, and 0 if never.

Macros with names matching ^ATOMIC_[A-Z] might be added to <stdatomic.h>.

Missing

  • memory_order_relaxed
  • atomic
  • memory_order_release
  • atomic_fetch_add_explicit
  • memory_order_acquire
  • memory_order_acq_rel
  • atomic_fetch_and_explicit
  • memory_order_seq_cst
  • atomic_fetch_xor_explicit
  • atomic_fetch_sub_explicit
  • kill_dependency
  • atomic_fetch_or_explicit
  • atomic_signal_fence
  • memory_order_consume
  • atomic_thread_fence

CHaR
Sitemap Supported
Site format updated 2024-06-05T22:37:07.391+0000
Data updated 1970-01-01T00:00:00.000+0000
Page updated 2023-10-04T20:24:03.209+0000