std::atomic(3)

NAME
std::atomic - std::atomic

Synopsis
   Defined in header <atomic>
   template< class T > (1) (since C++11)
   struct atomic;
   template< class U > (2) (since C++11)
   struct atomic<U*>;
   Defined in header <memory>
   template< class U > (3) (since C++20)
   struct atomic<std::shared_ptr<U>>;
   template< class U > (4) (since C++20)
   struct atomic<std::weak_ptr<U>>;
   Defined in header <stdatomic.h>
   #define _Atomic(T) /* see below */ (5) (since C++23)
   Each instantiation and full specialization of the std::atomic template defines an
   atomic type. If one thread writes to an atomic object while another thread reads
   from it, the behavior is well-defined (see memory model for details on data races).
   In addition, accesses to atomic objects may establish inter-thread synchronization
   and order non-atomic memory accesses as specified by std::memory_order.
   std::atomic is neither copyable nor movable.
   The compatibility macro _Atomic is provided in <stdatomic.h> such that
   _Atomic(T) is identical to std::atomic<T> while both are well-formed.
                        (since C++23)
   It is unspecified whether any declaration in namespace std is
   available when <stdatomic.h> is included.

Specializations
    Primary template
   The primary std::atomic template may be instantiated with any TriviallyCopyable type
   T satisfying both CopyConstructible and CopyAssignable. The program is ill-formed if
   any of following values is false:
     * std::is_trivially_copyable<T>::value
     * std::is_copy_constructible<T>::value
     * std::is_move_constructible<T>::value
     * std::is_copy_assignable<T>::value
     * std::is_move_assignable<T>::value
 struct Counters { int a; int b; }; // user-defined trivially-copyable type
 std::atomic<Counters> cnt; // specialization for the user-defined type
   std::atomic<bool> uses the primary template. It is guaranteed to be a standard
   layout struct.
    Partial specializations
   The standard library provides partial specializations of the std::atomic template
   for the following types with additional properties that the primary template does
   not have:
   2) Partial specializations std::atomic<U*> for all pointer types. These
   specializations have standard layout
   , trivial default constructors,
   (until C++20) and trivial destructors. Besides the operations provided for all
   atomic types, these specializations additionally support atomic arithmetic
   operations appropriate to pointer types, such as fetch_add, fetch_sub.
   3-4) Partial specializations std::atomic<std::shared_ptr<U>> and
   std::atomic<std::weak_ptr<U>> are provided for std::shared_ptr and
   std::weak_ptr. (since C++20)
   See std::atomic<std::shared_ptr> and std::atomic<std::weak_ptr> for
   details.
    Specializations for integral types
   When instantiated with one of the following integral types, std::atomic provides
   additional atomic operations appropriate to integral types such as fetch_add,
   fetch_sub, fetch_and, fetch_or, fetch_xor:
              * The character types char
                , char8_t
                (since C++20), char16_t, char32_t, and wchar_t;
              * The standard signed integer types: signed char, short, int, long, and
                long long;
              * The standard unsigned integer types: unsigned char, unsigned short,
                unsigned int, unsigned long, and unsigned long long;
              * Any additional integral types needed by the typedefs in the header
                <cstdint>.
   Additionally, the resulting std::atomic<Integral> specialization has standard layout
   , a trivial default constructor,
   (until C++20) and a trivial destructor. Signed integer arithmetic is defined to use
   two's complement; there are no undefined results.
       Specializations for floating-point types
   When instantiated with one of the standard floating-point types float,
   double, and long double
   , or one extended floating-point type
   (since C++23), std::atomic provides additional atomic operations
   appropriate to floating-point types such as fetch_add and fetch_sub.
                        (since C++20)
   Additionally, the resulting std::atomic<Floating> specialization has
   standard layout and a trivial destructor.
   No operations result in undefined behavior even if the result is not
   representable in the floating-point type. The floating-point
   environment in effect may be different from the calling thread's
   floating-point environment.
  Type aliases
   Type aliases are provided for bool and all integral types listed above, as follows:
         Aliases for all std::atomic<Integral>
   atomic_bool std::atomic<bool>
   (C++11) (typedef)
   atomic_char std::atomic<char>
   (C++11) (typedef)
   atomic_schar std::atomic<signed char>
   (C++11) (typedef)
   atomic_uchar std::atomic<unsigned char>
   (C++11) (typedef)
   atomic_short std::atomic<short>
   (C++11) (typedef)
   atomic_ushort std::atomic<unsigned short>
   (C++11) (typedef)
   atomic_int std::atomic<int>
   (C++11) (typedef)
   atomic_uint std::atomic<unsigned int>
   (C++11) (typedef)
   atomic_long std::atomic<long>
   (C++11) (typedef)
   atomic_ulong std::atomic<unsigned long>
   (C++11) (typedef)
   atomic_llong std::atomic<long long>
   (C++11) (typedef)
   atomic_ullong std::atomic<unsigned long long>
   (C++11) (typedef)
   atomic_char8_t std::atomic<char8_t>
   (C++20) (typedef)
   atomic_char16_t std::atomic<char16_t>
   (C++11) (typedef)
   atomic_char32_t std::atomic<char32_t>
   (C++11) (typedef)
   atomic_wchar_t std::atomic<wchar_t>
   (C++11) (typedef)
   atomic_int8_t std::atomic<std::int8_t>
   (C++11)(optional) (typedef)
   atomic_uint8_t std::atomic<std::uint8_t>
   (C++11)(optional) (typedef)
   atomic_int16_t std::atomic<std::int16_t>
   (C++11)(optional) (typedef)
   atomic_uint16_t std::atomic<std::uint16_t>
   (C++11)(optional) (typedef)
   atomic_int32_t std::atomic<std::int32_t>
   (C++11)(optional) (typedef)
   atomic_uint32_t std::atomic<std::uint32_t>
   (C++11)(optional) (typedef)
   atomic_int64_t std::atomic<std::int64_t>
   (C++11)(optional) (typedef)
   atomic_uint64_t std::atomic<std::uint64_t>
   (C++11)(optional) (typedef)
   atomic_int_least8_t std::atomic<std::int_least8_t>
   (C++11) (typedef)
   atomic_uint_least8_t std::atomic<std::uint_least8_t>
   (C++11) (typedef)
   atomic_int_least16_t std::atomic<std::int_least16_t>
   (C++11) (typedef)
   atomic_uint_least16_t std::atomic<std::uint_least16_t>
   (C++11) (typedef)
   atomic_int_least32_t std::atomic<std::int_least32_t>
   (C++11) (typedef)
   atomic_uint_least32_t std::atomic<std::uint_least32_t>
   (C++11) (typedef)
   atomic_int_least64_t std::atomic<std::int_least64_t>
   (C++11) (typedef)
   atomic_uint_least64_t std::atomic<std::uint_least64_t>
   (C++11) (typedef)
   atomic_int_fast8_t std::atomic<std::int_fast8_t>
   (C++11) (typedef)
   atomic_uint_fast8_t std::atomic<std::uint_fast8_t>
   (C++11) (typedef)
   atomic_int_fast16_t std::atomic<std::int_fast16_t>
   (C++11) (typedef)
   atomic_uint_fast16_t std::atomic<std::uint_fast16_t>
   (C++11) (typedef)
   atomic_int_fast32_t std::atomic<std::int_fast32_t>
   (C++11) (typedef)
   atomic_uint_fast32_t std::atomic<std::uint_fast32_t>
   (C++11) (typedef)
   atomic_int_fast64_t std::atomic<std::int_fast64_t>
   (C++11) (typedef)
   atomic_uint_fast64_t std::atomic<std::uint_fast64_t>
   (C++11) (typedef)
   atomic_intptr_t std::atomic<std::intptr_t>
   (C++11)(optional) (typedef)
   atomic_uintptr_t std::atomic<std::uintptr_t>
   (C++11)(optional) (typedef)
   atomic_size_t std::atomic<std::size_t>
   (C++11) (typedef)
   atomic_ptrdiff_t std::atomic<std::ptrdiff_t>
   (C++11) (typedef)
   atomic_intmax_t std::atomic<std::intmax_t>
   (C++11) (typedef)
   atomic_uintmax_t std::atomic<std::uintmax_t>
   (C++11) (typedef)
         Aliases for special-purpose types
   atomic_signed_lock_free a signed integral atomic type that is lock-free and for
   (C++20) which waiting/notifying is most efficient
                        (typedef)
   atomic_unsigned_lock_free a unsigned integral atomic type that is lock-free and for
   (C++20) which waiting/notifying is most efficient
                        (typedef)
   Note: std::atomic_intN_t, std::atomic_uintN_t, std::atomic_intptr_t, and
   atomic_uintptr_t are defined if and only if std::intN_t, std::uintN_t,
   std::intptr_t, and std::uintptr_t are defined, respectively.
   std::atomic_signed_lock_free and std::atomic_unsigned_lock_free are (since C++20)
   optional in freestanding implementations.

Member types
   Member type Definition
   value_type T (regardless of whether specialized or not)
                   value_type (only for atomic<Integral>
   difference_type and atomic<Floating>
                   (since C++20) specializations)
                   std::ptrdiff_t (only for atomic<U*> specializations)
   difference_type is not defined in the primary atomic template or in the partial
   specializations for std::shared_ptr and std::weak_ptr.

Member functions
   constructor constructs an atomic object
                        (public member function)
   operator= stores a value into an atomic object
                        (public member function)
   is_lock_free checks if the atomic object is lock-free
                        (public member function)
                        atomically replaces the value of the atomic object with a
   store non-atomic argument
                        (public member function)
   load atomically obtains the value of the atomic object
                        (public member function)
   operator T loads a value from an atomic object
                        (public member function)
                        atomically replaces the value of the atomic object and
   exchange obtains the value held previously
                        (public member function)
                        atomically compares the value of the atomic object with
   compare_exchange_weak non-atomic argument and performs atomic exchange if equal or
   compare_exchange_strong atomic load if not
                        (public member function)
   wait blocks the thread until notified and the atomic value
   (C++20) changes
                        (public member function)
   notify_one notifies at least one thread waiting on the atomic object
   (C++20) (public member function)
   notify_all notifies all threads blocked waiting on the atomic object
   (C++20) (public member function)

Constants
   is_always_lock_free indicates that the type is always lock-free
   [static] (C++17) (public static member constant)

Specialized member functions
                   atomically adds the argument to the value stored in the atomic
   fetch_add object and obtains the value held previously
                   (public member function)
                   atomically subtracts the argument from the value stored in the
   fetch_sub atomic object and obtains the value held previously
                   (public member function)
                   atomically performs bitwise AND between the argument and the value
   fetch_and of the atomic object and obtains the value held previously
                   (public member function)
                   atomically performs bitwise OR between the argument and the value of
   fetch_or the atomic object and obtains the value held previously
                   (public member function)
                   atomically performs bitwise XOR between the argument and the value
   fetch_xor of the atomic object and obtains the value held previously
                   (public member function)
   operator++
   operator++(int) increments or decrements the atomic value by one
   operator-- (public member function)
   operator--(int)
   operator+=
   operator-= adds, subtracts, or performs bitwise AND, OR, XOR with the atomic
   operator&= value
   operator|= (public member function)
   operator^=

Notes
   There are non-member function template equivalents for all member functions of
   std::atomic. Those non-member functions may be additionally overloaded for types
   that are not specializations of std::atomic, but are able to guarantee atomicity.
   The only such type in the standard library is std::shared_ptr<U>.
   _Atomic is a keyword and used to provide atomic types in C.
   Implementations are recommended to ensure that the representation of _Atomic(T) in C
   is same as that of std::atomic<T> in C++ for every possible type T. The mechanisms
   used to ensure atomicity and memory ordering should be compatible.
   On gcc and clang, some of the functionality described here requires linking against
   -latomic.
  Defect reports
   The following behavior-changing defect reports were applied retroactively to
   previously published C++ standards.
      DR Applied to Behavior as published Correct behavior
                       typedefs for atomic versions
   LWG 2441 C++11 of optional added
                       fixed width integer types were
                       missing
                       template argument deduction
                       for some functions specification was substantially
   P0558R1 C++11 for atomic types might rewritten:
                       accidently fail; member typedefs value_type and
                       invalid pointer operations difference_type are added
                       were provided
                       std::atomic<T> was permitted
   LWG 3012 C++11 for such specializations are
                       any T that is trivially forbidden
                       copyable but not copyable

See also
   atomic_flag the lock-free boolean atomic type
   (C++11) (class)
   std::atomic<std::shared_ptr> atomic shared pointer
   (C++20) (class template specialization)
   std::atomic<std::weak_ptr> atomic weak pointer
   (C++20) (class template specialization)