std::atomic_ref
| Defined in header <atomic>
|
||
| template< class T > struct atomic_ref; |
(since C++20) | |
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_refs 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.
Like references in the core language, constness is shallow for std::atomic_ref - it is possible to modify the referenced value through a const std::atomic_ref object.
If any of the following conditions are satisfied, the program is ill-formed:
- std::is_trivially_copyable_v<T> is false.
-
is_always_lock_freeis false and std::is_volatile_v<T> is true.
std::atomic_ref is CopyConstructible.
Nested types
| Type | Definition |
value_type
|
std::remove_cv_t<T> |
difference_type
|
|
Data members
| Member | Description |
T* ptr
|
the pointer to the referenced object (exposition-only member object*) |
| [static] |
indicates that the type is always lock-free (public static member constant) |
| [static] |
indicates the required alignment of an object to be referenced by atomic_ref (public static member constant) |
Member functions
constructs an atomic_ref object (public member function) | |
stores a value into the object referenced by an atomic_ref object (public member function) | |
checks if the atomic_ref object is lock-free (public member function) | |
| atomically replaces the value of the referenced object with a non-atomic argument (public member function) | |
| atomically obtains the value of the referenced object (public member function) | |
| loads a value from the referenced object (public member function) | |
| atomically replaces the value of the referenced object and obtains the value held previously (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 (public member function) | |
| blocks the thread until notified and the atomic value changes (public member function) | |
| notifies at least one thread waiting on the atomic object (public member function) | |
| notifies all threads blocked waiting on the atomic object (public member function) | |
| (C++26) |
returns the object's address (public member function) |
Provided only when
| |
| atomically adds the argument to the value stored in the referenced object and obtains the value held previously (public member function) | |
| atomically subtracts the argument from the value stored in the referenced object and obtains the value held previously (public member function) | |
| atomically adds to or subtracts from the referenced value (public member function) | |
Provided only when
| |
| (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) |
| (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) |
| atomically increments or decrements the referenced object by one (public member function) | |
Provided only when
| |
| atomically performs bitwise AND between the argument and the value of the referenced object and obtains the value held previously (public member function) | |
| atomically performs bitwise OR between the argument and the value of the referenced object and obtains the value held previously (public member function) | |
| atomically performs bitwise XOR between the argument and the value of the referenced object and obtains the value held previously (public member function) | |
| atomically performs bitwise AND, OR, XOR with the referenced value (public member function) | |
Specializations
The standard specifies that std::atomic_ref has following specializations:
| template<> struct atomic_ref</*integral-type*/>; |
(1) | (since C++20) |
| template<> struct atomic_ref</*floating-point-type*/>; |
(2) | (since C++20) |
| template< class /*pointer-type*/ > requires /* see below */ |
(3) | (since C++20) |
Notes
Implementations may merge the specified specializations. E.g. MSVC STL merges all of them into the primary template.
When T is cv void or a function type, std::atomic_ref<T*> (i.e. std::atomic_ref<void*>, std::atomic_ref<int(*)()> etc.) does not have difference_type or any operation requiring pointer arithmetic or relational comparison(since C++26).
| Feature-test macro | Value | Std | Feature |
|---|---|---|---|
__cpp_lib_atomic_ref |
201806L |
(C++20) | std::atomic_ref
|
__cpp_lib_constexpr_atomic |
202411L |
(C++26) | constexpr std::atomic and std::atomic_ref
|
Defect reports
The following behavior-changing defect reports were applied retroactively to previously published C++ standards.
| DR | Applied to | Behavior as published | Correct behavior |
|---|---|---|---|
| LWG 3508 (P3323R1) |
C++20 | atomic_ref<T> had unimplementable operations if T is a const type or pointer-to-non-object type
|
these operations are either constained or not provided for unsuitable T
|
See also
| (C++11) |
atomic class template and specializations for bool, integral, floating-point,(since C++20) and pointer types (class template) |