The Open Group Base Specifications Issue 8
IEEE Std 1003.1-2024
Copyright © 2001-2024 The IEEE and The Open Group

NAME

stdatomic.h — atomics

SYNOPSIS

#include <stdatomic.h>

DESCRIPTION

[CX] [Option Start] 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. [Option End]

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] [Option Start] 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. [Option End]  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);

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

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.

End of informative text.

 

return to top of page

UNIX® is a registered Trademark of The Open Group.
POSIX™ is a Trademark of The IEEE.
Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved
[ Main Index | XBD | XSH | XCU | XRAT ]