std::atomic_ref(3) | C++ Standard Libary | std::atomic_ref(3) |
NAME¶
std::atomic_ref - std::atomic_ref
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*>;
The std::atomic_ref class template applies atomic operations to the object it
references. For the lifetime of the 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 atomic_refs that
references the object. While any atomic_ref instances referencing an object
exists,
the object must be exclusively accessed through these atomic_ref instances.
No
subobject of an object referenced by an atomic_ref object may be concurrently
referenced by any other atomic_ref object.
Atomic operations applied to an object through an atomic_ref are atomic with
respect
to atomic operations applied through any other atomic_ref referencing the
same
object.
std::atomic_ref is CopyConstructible.
Like language references, constness is shallow for atomic_ref - it is
possible to
modify the referenced value through a const 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; } counter; // user-defined trivially-copyable
type
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 floating-point types float, double, and
long
double, 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¶
Member type Definition
value_type see below
value_type (only for atomic_ref<Integral> and
atomic_ref<Floating>
difference_type specializations)
std::ptrdiff_t (only for atomic_ref<T*> specializations)
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)
stores a value into the object referenced by an atomic_ref
operator= object
(public member function)
is_lock_free checks if the atomic_ref object is lock-free
(public member function)
atomically replaces the value of the referenced object with
store 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)
atomically replaces the value of the referenced object and
exchange obtains the value held previously
(public member function)
atomically compares the value of the referenced object with
compare_exchange_weak non-atomic argument and performs atomic exchange if
equal or
compare_exchange_strong atomic load if not
(public member function)
wait blocks the thread until notified and the atomic value
(C++20) changes
(public member function)
notify_one notifies at least one thread waiting on the atomic object
(C++20) (public member function)
notify_all notifies all threads blocked waiting on the atomic object
(C++20) (public member function)
Constants¶
is_always_lock_free indicates that the type is always lock-free
[static] (public static member constant)
required_alignment indicates the required alignment of an object to be
[static] referenced by atomic_ref
(public static member constant)
Specialized member functions¶
atomically adds the argument to the value stored in the
referenced
fetch_add object and obtains the value held previously
(public member function)
atomically subtracts the argument from the value stored in the
fetch_sub referenced object and obtains the value held previously
(public member function)
atomically performs bitwise AND between the argument and the value
fetch_and of the referenced object and obtains the value held previously
(public member function)
atomically performs bitwise OR between the argument and the value of
fetch_or the referenced object and obtains the value held previously
(public member function)
atomically performs bitwise XOR between the argument and the value
fetch_xor of the referenced object and obtains the value held previously
(public member function)
operator++
operator++(int) atomically increments or decrements the referenced object by
one
operator-- (public member function)
operator--(int)
operator+=
operator-= atomically adds, subtracts, or performs bitwise AND, OR, XOR with
operator&= the referenced value
operator|= (public member function)
operator^=
Notes¶
Feature-test macro: __cpp_lib_atomic_ref
See also¶
atomic atomic class template and specializations for bool,
integral, and pointer
(C++11) types
(class template)
2022.07.31 | http://cppreference.com |