std::atomic_ref (3) - Linux Manuals

std::atomic_ref: std::atomic_ref

NAME

std::atomic_ref - std::atomic_ref

Synopsis

Defined in header <atomic>
template< class T > (1) (since C++20)
struct atomic_ref;
template< class T > (2) (since C++20)
struct atomic_ref<T*>;

The std::atomic_ref class template applies atomic operations to the object it references. For the lifetime of the atomic_ref object, the object it references is considered an atomic object. 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.
The lifetime of an object must exceed the lifetime of all atomic_refs that references the object. While any atomic_ref instances referencing an object exists, the object must be exclusively accessed through these atomic_ref instances. No subobject of an object referenced by an atomic_ref object may be concurrently referenced by any other atomic_ref object.
Atomic operations applied to an object through an atomic_ref are atomic with respect to atomic operations applied through any other atomic_ref referencing the same object.
std::atomic_ref is CopyConstructible.
Like language references, constness is shallow for atomic_ref - it is possible to modify the referenced value through a const atomic_ref object.

Specializations

Primary template

The primary std::atomic_ref template may be instantiated with any TriviallyCopyable type T (including bool):

  struct Counters { int a; int b; } counter; // user-defined trivially-copyable type
  std::atomic_ref<Counters> cnt(counter); // specialization for the user-defined type

Partial specialization for pointer types

The standard library provides partial specializations of the std::atomic_ref template for for all pointer types. In addition to the operations provided for all atomic types, these specializations additionally support atomic arithmetic operations appropriate to pointer types, such as fetch_add, fetch_sub.

Specializations for integral types

When instantiated with one of the following integral types, std::atomic_ref 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>.

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 floating-point types float, double, and long double, std::atomic_ref provides additional atomic operations appropriate to floating-point types such as fetch_add and fetch_sub.
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.

Member types

Member type Definition
value_type see below
difference_type value_type (only for atomic_ref<Integral> and atomic_ref<Floating> specializations)
                std::ptrdiff_t (only for atomic_ref<T*> specializations)

For every std::atomic_ref<X> (whether or not specialized), std::atomic_ref<X>::value_type is X.
difference_type is not defined in the primary atomic_ref template.

Member functions

                        constructs an atomic_ref object
constructor (public member function)
                        stores a value into the object referenced by an atomic_ref object
operator= (public member function)
                        checks if the atomic_ref object is lock-free
is_lock_free (public member function)
                        atomically replaces the value of the referenced object with a non-atomic argument
store (public member function)
                        atomically obtains the value of the referenced object
load (public member function)
                        loads a value from the referenced object
operator_T (public member function)
                        atomically replaces the value of the referenced object and obtains the value held previously
exchange (public member function)
                        atomically compares the value of the referenced object with non-atomic argument and performs atomic exchange if equal or atomic load if not
compare_exchange_weak (public member function)
compare_exchange_strong

Constants

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

required_alignment indicates that the required alignment of an object to be referenced by atomic_ref
                        (public static member constant)
[static]

Specialized member functions

                atomically adds the argument to the value stored in the referenced object and obtains the value held previously
fetch_add (public member function)
                atomically subtracts the argument from the value stored in the referenced object and obtains the value held previously
fetch_sub (public member function)
                atomically performs bitwise AND between the argument and the value of the referenced object and obtains the value held previously
fetch_and (public member function)
                atomically performs bitwise OR between the argument and the value of the referenced object and obtains the value held previously
fetch_or (public member function)
                atomically performs bitwise XOR between the argument and the value of the referenced object and obtains the value held previously
fetch_xor (public member function)

operator++ atomically increments or decrements the referenced object by one
operator++(int) (public member function)
operator--
operator--(int)

operator+=
operator-= atomically adds, subtracts, or performs bitwise AND, OR, XOR with the referenced value
operator&= (public member function)
operator|=
operator^=