NAME

stdatomic.h — atomics

SYNOPSIS

#include <stdatomic.h>

DESCRIPTION

^[CX] The functionality described on this reference page is aligned with the ISO C standard. Any conflict between the requirements described here and the ISO C standard is unintentional. This volume of POSIX.1-2024 defers to the ISO C standard.

Implementations that define the macro __STDC_NO_ATOMICS__ need not provide this header nor support any of its facilities.

The <stdatomic.h> header shall define the atomic_flag type as a structure type. This type provides the classic test-and-set functionality. It shall have two states, set and clear. Operations on an object of type atomic_flag shall be lock free.

The <stdatomic.h> header shall define each of the atomic integer types in the following table as a type that has the same representation and alignment requirements as the corresponding direct type.

Note:

The same representation and alignment requirements are meant to imply interchangeability as arguments to functions, return values from functions, and members of unions.

Atomic type name	Direct type
atomic_bool	_Atomic _Bool
atomic_char	_Atomic char
atomic_schar	_Atomic signed char
atomic_uchar	_Atomic unsigned char
atomic_short	_Atomic short
atomic_ushort	_Atomic unsigned short
atomic_int	_Atomic int
atomic_uint	_Atomic unsigned int
atomic_long	_Atomic long
atomic_ulong	_Atomic unsigned long
atomic_llong	_Atomic long long
atomic_ullong	_Atomic unsigned long long
atomic_char16_t	_Atomic char16_t
atomic_char32_t	_Atomic char32_t
atomic_wchar_t	_Atomic wchar_t
atomic_int_least8_t	_Atomic int_least8_t
atomic_uint_least8_t	_Atomic uint_least8_t
atomic_int_least16_t	_Atomic int_least16_t
atomic_uint_least16_t	_Atomic uint_least16_t
atomic_int_least32_t	_Atomic int_least32_t
atomic_uint_least32_t	_Atomic uint_least32_t
atomic_int_least64_t	_Atomic int_least64_t
atomic_uint_least64_t	_Atomic uint_least64_t
atomic_int_fast8_t	_Atomic int_fast8_t
atomic_uint_fast8_t	_Atomic uint_fast8_t
atomic_int_fast16_t	_Atomic int_fast16_t
atomic_uint_fast16_t	_Atomic uint_fast16_t
atomic_int_fast32_t	_Atomic int_fast32_t
atomic_uint_fast32_t	_Atomic uint_fast32_t
atomic_int_fast64_t	_Atomic int_fast64_t
atomic_uint_fast64_t	_Atomic uint_fast64_t
atomic_intptr_t	_Atomic intptr_t
atomic_uintptr_t	_Atomic uintptr_t
atomic_size_t	_Atomic size_t
atomic_ptrdiff_t	_Atomic ptrdiff_t
atomic_intmax_t	_Atomic intmax_t
atomic_uintmax_t	_Atomic uintmax_t

The <stdatomic.h> header shall define the memory_order type as an enumerated type whose enumerators shall include at least the following:

memory_order_relaxed

memory_order_consume

memory_order_acquire

memory_order_release

memory_order_acq_rel

memory_order_seq_cst

The <stdatomic.h> header shall define the following atomic lock-free macros:

ATOMIC_BOOL_LOCK_FREE
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

which shall expand to constant expressions suitable for use in #if preprocessing directives and which shall indicate the lock-free property of the corresponding atomic types (both signed and unsigned). A value of 0 shall indicate that the type is never lock-free; a value of 1 shall indicate that the type is sometimes lock-free; a value of 2 shall indicate that the type is always lock-free.

The <stdatomic.h> header shall define the macro ATOMIC_FLAG_INIT which shall expand to an initializer for an object of type atomic_flag. This macro shall initialize an atomic_flag to the clear state. An atomic_flag that is not explicitly initialized with ATOMIC_FLAG_INIT is initially in an indeterminate state.

^[OB] The <stdatomic.h> header shall define the macro ATOMIC_VAR_INIT(value) which shall expand to a token sequence suitable for initializing an atomic object of a type that is initialization-compatible with the non-atomic type of its value argument.  An atomic object with automatic storage duration that is not explicitly initialized is initially in an indeterminate state.

The <stdatomic.h> header shall define the macro kill_dependency() which shall behave as described in kill_dependency.

The <stdatomic.h> header shall declare the following generic functions, where A refers to an atomic type, C refers to its corresponding non-atomic type, and M is C for atomic integer types or ptrdiff_t for atomic pointer types.

_Bool   atomic_compare_exchange_strong(volatile A *, C *, C);
_Bool   atomic_compare_exchange_strong_explicit(volatile A *, C *, C, memory_order, memory_order);
_Bool   atomic_compare_exchange_weak(volatile A *, C *, C);
_Bool   atomic_compare_exchange_weak_explicit(volatile A *, C *, C, memory_order, memory_order);
C       atomic_exchange(volatile A *, C);
C       atomic_exchange_explicit(volatile A *, C, memory_order);
C       atomic_fetch_add(volatile A *, M);
C       atomic_fetch_add_explicit(volatile A *, M, memory_order);
C       atomic_fetch_and(volatile A *, M);
C       atomic_fetch_and_explicit(volatile A *, M, memory_order);
C       atomic_fetch_or(volatile A *, M);
C       atomic_fetch_or_explicit(volatile A *, M, memory_order);
C       atomic_fetch_sub(volatile A *, M);
C       atomic_fetch_sub_explicit(volatile A *, M, memory_order);
C       atomic_fetch_xor(volatile A *, M);
C       atomic_fetch_xor_explicit(volatile A *, M, memory_order);
void    atomic_init(volatile A *, C);
_Bool   atomic_is_lock_free(const volatile A *);
C       atomic_load(const volatile A *);
C       atomic_load_explicit(const volatile A *, memory_order);
void    atomic_store(volatile A *, C);
void    atomic_store_explicit(volatile A *, C, memory_order);

It is unspecified whether any generic function declared in <stdatomic.h> is a macro or an identifier declared with external linkage. If a macro definition is suppressed in order to access an actual function, or a program defines an external identifier with the name of a generic function, the behavior is undefined.

The following shall be declared as functions and may also be defined as macros. Function prototypes shall be provided.

void    atomic_flag_clear(volatile atomic_flag *);
void    atomic_flag_clear_explicit(volatile atomic_flag *,
                memory_order);
_Bool   atomic_flag_test_and_set(volatile atomic_flag *);
_Bool   atomic_flag_test_and_set_explicit(
                volatile atomic_flag *, memory_order);
void    atomic_signal_fence(memory_order);
void    atomic_thread_fence(memory_order);

APPLICATION USAGE

None.

RATIONALE

Since operations on the atomic_flag type are lock free, the operations should also be address-free. No other type requires lock-free operations, so the atomic_flag type is the minimum hardware-implemented type needed to conform to this standard. The remaining types can be emulated with atomic_flag, though with less than ideal properties.

The representation of atomic integer types need not have the same size as their corresponding regular types. They should have the same size whenever possible, as it eases effort required to port existing code.

FUTURE DIRECTIONS

The ISO C standard states that the macro ATOMIC_VAR_INIT is an obsolescent feature. This macro may be removed in a future version of this standard.

SEE ALSO

4.15.1 Memory Ordering

XSH atomic_compare_exchange_strong, atomic_exchange, atomic_fetch_add, atomic_flag_clear, atomic_flag_test_and_set, atomic_init, atomic_is_lock_free, atomic_load, atomic_signal_fence, atomic_store, kill_dependency .

CHANGE HISTORY

First released in Issue 8. Included for alignment with the ISO/IEC 9899:2018 standard.