std::atomic_ref(3)

💖 std::atomic_ref 💖

Okay bestie, so this whole page is from the C++ Standard Library manual, and we're about to get into std::atomic_ref — and honestly? It's giving "make any object go atomic" main character energy. Let's go. ✨

🌸 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*>;

🦋 DESCRIPTION 🦋

So the std::atomic_ref class template literally just applies atomic operations to the object it references. For the entire lifetime of the std::atomic_ref object, that referenced object is considered an atomic object. And if one thread writes to an atomic object while another thread reads from it, the behavior is well-defined (peep the memory model for the deets on data races). Also — accesses to atomic objects can establish inter-thread synchronization and can order non-atomic memory accesses exactly as std::memory_order specifies. Slay. 💅

The lifetime of an object must exceed the lifetime of all std::atomic_refs that reference it. And 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. Not me being strict, but fr fr, that's the rule. 🙈

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. Iconic coordination. 🤝

std::atomic_ref is CopyConstructible. 👑

And like language references, constness is shallow for std::atomic_ref — which means you can modify the referenced value through a const std::atomic_ref object. Yes bestie, even a const one can change the thing it points to. Plot twist. 😭

---

🌈 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. On top of the operations provided for all atomic types, these specializations additionally support atomic arithmetic operations appropriate to pointer types, such as fetch_add, fetch_sub. Pointer math but make it atomic. 🎀

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. No cap — two's complement all the way. 🔥

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 ✨

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

---

🎀 CONSTANTS 🎀

• is_always_lock_free [static] — indicates that the type is always lock-free (public static member constant)
• required_alignment [static] — indicates the required alignment of an object to be referenced by atomic_ref (public static member constant)

---

🫶 SPECIALIZED MEMBER FUNCTIONS 🫶

Specialized for integral, floating-point and pointer types

• fetch_add — atomically adds the argument to the value stored in the referenced object and obtains the value held previously (public member function)
• fetch_sub — atomically subtracts the argument from the value stored in the referenced object and obtains the value held previously (public member function)
• operator+=, operator-= — atomically adds to or subtracts from the referenced value (public member function)

Specialized for integral and pointer types only

• fetch_max (C++26) — atomically performs std::max between the argument and the value of the referenced object and obtains the value held previously (public member function)
• fetch_min (C++26) — atomically performs std::min between the argument and the value of the referenced object and obtains the value held previously (public member function)
• operator++, operator++(int), operator--, operator--(int) — atomically increments or decrements the referenced object by one (public member function)

Specialized for integral types only

• fetch_and — atomically performs bitwise AND between the argument and the value of the referenced object and obtains the value held previously (public member function)
• fetch_or — atomically performs bitwise OR between the argument and the value of the referenced object and obtains the value held previously (public member function)
• fetch_xor — atomically performs bitwise XOR between the argument and the value of the referenced object and obtains the value held previously (public member function)
• operator&=, operator|=, operator^= — atomically performs bitwise AND, OR, XOR with the referenced value (public member function)

---

🌟 NOTES 🌟

Feature-test macro check bestie:

---

👑 SEE ALSO 👑

• atomic (C++11) — atomic class template and specializations for bool, integral, floating-point, (since C++20) and pointer types (class template)

---

This page is literally brought to you by http://cppreference.com and the date 2024.06.10, so if you ever need to cite your sources, that's right there. Periodt. 💖✨

Stay atomic, bestie — don't let those data races catch you slippin'. 💅🔥🌈