std:: atomic_ref

The std::atomic_ref class template applies atomic operations to the object it references. For the lifetime of the std::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 std::atomic_ref s that references the object. While any std::atomic_ref instance referencing an object exists, the object must be exclusively accessed through these std::atomic_ref instances. No subobject of an object referenced by an std::atomic_ref object may be concurrently referenced by any other std::atomic_ref object.

Atomic operations applied to an object through an std::atomic_ref are atomic with respect to atomic operations applied through any other std::atomic_ref referencing the same object.

std::atomic_ref is CopyConstructible .

Like language references, constness is shallow for std::atomic_ref - it is possible to modify the referenced value through a const std::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; }; // user-defined trivially-copyable type
alignas(std::atomic_ref<Counters>::required_alignment) Counters counter;
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 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 , 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 cv-unqualified floating-point types ( float , double , long double and cv-unqualified extended floating-point types (since C++23) ), 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

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

Specialized member functions

Notes

See also