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.

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(3) which shall behave as described in kill_dependency(3).

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

The following sections are informative.

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

V1_chap04(7)

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

CHANGE HISTORY

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

End of informative text.