template<classT>structatomic_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
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
.
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
in the core language, constness is shallow for std::atomic_ref - it is possible to modify the referenced value through a conststd::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 false and std::is_volatile_v<T> is true.
std::atomic_ref is
.
Nested types
Type Definition value_typestd::remove_cv_t<T>difference_typevalue_type, if T is an arithmetic type other than cvbool.
Otherwise,
, if T is a pointer-to-object type.
Otherwise, not defined.
Data members
Member Description T*ptrthe 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)
compare_exchange_weakcompare_exchange_strong
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 T is an arithmetic type other than cvbool or a pointer-to-object type
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 T is an integral type other than cvbool or a pointer-to-object type
(C++26)
atomically performs
between the argument and the value of the referenced object and obtains the value held previously
(public member function)
(C++26)
atomically performs
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)
Provided only when T is an integral type other than cvbool
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)
operator&=operator|=operator^=
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<>structatomic_ref</*integral-type*/>; (1) (since C++20)template<>structatomic_ref</*floating-point-type*/>; (2) (since C++20)template<class/*pointer-type*/>requires/* see below */structatomic_ref</*pointer-type*/>; (3) (since C++20)1)/*integral-type*/ denotes a possibly cv-qualified integral type other than cvbool.
2)/*floating-point-type*/ denotes a possibly cv-qualified floating-point type.
3) The partial specialization is provided for /*pointer-type*/ types that are possibly cv-qualified pointer-to-object types.
Notes
Implementations may merge the specified specializations. E.g. MSVC STL merges all of them into the primary template.
When T is cvvoid 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).
macro ValueStdFeature
(C++20)std::atomic_ref
(C++26)constexpr
and std::atomic_refDefect reports
The following behavior-changing defect reports were applied retroactively to previously published C++ standards.
DR Applied to Behavior as published Correct behavior
(
) 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 TSee also
(C++11)
atomic class template and specializations for bool, integral, floating-point,(since C++20) and pointer types
(class template)