|
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Defined in header <atomic> | ||
template<class T> struct atomic_ref; | (since C++20) | |
Thestd::atomic_ref class template applies atomic operations to the object it references.
For the lifetime of thestd::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 (seememory 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 bystd::memory_order.
The lifetime of an object must exceed the lifetime of allstd::atomic_refs that references the object. While anystd::atomic_ref instance referencing an object exists, the object must be exclusively accessed through thesestd::atomic_ref instances. No subobject of an object referenced by anstd::atomic_ref object may be concurrently referenced by any otherstd::atomic_ref object.
Atomic operations applied to an object through anstd::atomic_ref are atomic with respect to atomic operations applied through any otherstd::atomic_ref referencing the same object.
Likereferences in the core language, constness is shallow forstd::atomic_ref - it is possible to modify the referenced value through aconststd::atomic_ref object.
If any of the following conditions are satisfied, the program is ill-formed:
is_always_lock_free isfalse andstd::is_volatile_v<T> istrue.std::atomic_ref isCopyConstructible.
Contents |
| Type | Definition |
value_type | std::remove_cv_t<T> |
difference_type |
|
| 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)[edit] |
[static] | indicates the required alignment of an object to be referenced byatomic_ref(public static member constant)[edit] |
constructs anatomic_ref object(public member function)[edit] | |
stores a value into the object referenced by anatomic_ref object(public member function)[edit] | |
checks if theatomic_ref object is lock-free(public member function)[edit] | |
| atomically replaces the value of the referenced object with a non-atomic argument (public member function)[edit] | |
| atomically obtains the value of the referenced object (public member function)[edit] | |
| loads a value from the referenced object (public member function)[edit] | |
| atomically replaces the value of the referenced object and obtains the value held previously (public member function)[edit] | |
| 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)[edit] | |
| blocks the thread until notified and the atomic value changes (public member function)[edit] | |
| notifies at least one thread waiting on the atomic object (public member function)[edit] | |
| notifies all threads blocked waiting on the atomic object (public member function)[edit] | |
(C++26) | returns the object's address (public member function)[edit] |
Provided only when | |
| atomically adds the argument to the value stored in the referenced object and obtains the value held previously (public member function)[edit] | |
| atomically subtracts the argument from the value stored in the referenced object and obtains the value held previously (public member function)[edit] | |
| atomically adds to or subtracts from the referenced value (public member function)[edit] | |
Provided only when | |
(C++26) | atomically performsstd::max between the argument and the value of the referenced object and obtains the value held previously (public member function)[edit] |
(C++26) | atomically performsstd::min between the argument and the value of the referenced object and obtains the value held previously (public member function)[edit] |
| atomically increments or decrements the referenced object by one (public member function)[edit] | |
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)[edit] | |
| atomically performs bitwise OR between the argument and the value of the referenced object and obtains the value held previously (public member function)[edit] | |
| atomically performs bitwise XOR between the argument and the value of the referenced object and obtains the value held previously (public member function)[edit] | |
| atomically performs bitwise AND, OR, XOR with the referenced value (public member function)[edit] | |
The standard specifies thatstd::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) |
Implementations may merge the specified specializations. E.g. MSVC STL merges all of them into the primary template.
WhenT iscvvoid or a function type,std::atomic_ref<T*> (i.e.std::atomic_ref<void*>,std::atomic_ref<int(*)()> etc.) does not havedifference_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) | constexprstd::atomic andstd::atomic_ref |
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 aconst type or pointer-to-non-object type | these operations are either constained or not provided for unsuitable T |
(C++11) | atomic class template and specializations for bool, integral, floating-point,(since C++20) and pointer types (class template)[edit] |
