32 Atomic operations library [atomics]
[
Note: Many operations are volatile-qualified
.The “volatile as device register”
semantics have not changed in the standard
.This qualification means that volatility is
preserved when applying these operations to volatile objects
.It does not mean that
operations on non-volatile objects become volatile
. —
end note ]
atomic() noexcept = default;
Effects:
Leaves the atomic object in an uninitialized state
. [
Note: These semantics ensure compatibility with C
. —
end note ]
constexpr atomic(T desired) noexcept;
Effects: Initializes the object with the value
desired. [
Note: It is possible to have an access to an atomic object
A
race with its construction, for example by communicating the address of the
just-constructed object
A to another thread via
memory_order_relaxed operations on a suitable atomic pointer
variable, and then immediately accessing
A in the receiving thread
.This results in undefined behavior
. —
end note ]
#define ATOMIC_VAR_INIT(value) see below
The macro expands to a token sequence suitable for
constant initialization of
an atomic variable of static storage duration of a type that is
initialization-compatible with
value.[
Note: This operation may need to initialize locks
. —
end note ]
Concurrent access to the variable being initialized, even via an atomic operation,
constitutes a data race
.[
Example:
atomic<int> v = ATOMIC_VAR_INIT(5);
—
end example ]
static constexpr bool is_always_lock_free = implementation-defined;
The
static data member
is_always_lock_free is
true
if the atomic type's operations are always lock-free, and
false otherwise
.[
Note: The value of
is_always_lock_free is consistent with the value of
the corresponding
ATOMIC_..._LOCK_FREE macro, if defined
. —
end note ]
bool is_lock_free() const volatile noexcept;
bool is_lock_free() const noexcept;
Returns: true if the object's operations are lock-free,
false otherwise
. [
Note: The return value of the
is_lock_free member function
is consistent with the value of
is_always_lock_free for the same type
. —
end note ]
void store(T desired, memory_order order = memory_order_seq_cst) volatile noexcept;
void store(T desired, memory_order order = memory_order_seq_cst) noexcept;
Requires: The
order argument shall not be
memory_order_consume,
memory_order_acquire, nor
memory_order_acq_rel. Effects: Atomically replaces the value pointed to by
this
with the value of
desired. Memory is affected according to the value of
order.T operator=(T desired) volatile noexcept;
T operator=(T desired) noexcept;
Effects: Equivalent to:
store(desired). T load(memory_order order = memory_order_seq_cst) const volatile noexcept;
T load(memory_order order = memory_order_seq_cst) const noexcept;
Requires: The
order argument shall not be
memory_order_release nor
memory_order_acq_rel. Effects: Memory is affected according to the value of
order. Returns: Atomically returns the value pointed to by
this. operator T() const volatile noexcept;
operator T() const noexcept;
Effects: Equivalent to: return load();
T exchange(T desired, memory_order order = memory_order_seq_cst) volatile noexcept;
T exchange(T desired, memory_order order = memory_order_seq_cst) noexcept;
Effects: Atomically replaces the value pointed to by
this
with
desired. Memory is affected according to the value of
order.Returns: Atomically returns the value pointed to by
this immediately before the effects
. bool compare_exchange_weak(T& expected, T desired,
memory_order success, memory_order failure) volatile noexcept;
bool compare_exchange_weak(T& expected, T desired,
memory_order success, memory_order failure) noexcept;
bool compare_exchange_strong(T& expected, T desired,
memory_order success, memory_order failure) volatile noexcept;
bool compare_exchange_strong(T& expected, T desired,
memory_order success, memory_order failure) noexcept;
bool compare_exchange_weak(T& expected, T desired,
memory_order order = memory_order_seq_cst) volatile noexcept;
bool compare_exchange_weak(T& expected, T desired,
memory_order order = memory_order_seq_cst) noexcept;
bool compare_exchange_strong(T& expected, T desired,
memory_order order = memory_order_seq_cst) volatile noexcept;
bool compare_exchange_strong(T& expected, T desired,
memory_order order = memory_order_seq_cst) noexcept;
Requires: The
failure argument shall not be
memory_order_release nor
memory_order_acq_rel. Effects: Retrieves the value in
expected. It then atomically
compares the contents of the memory pointed to by
this
for equality with that previously retrieved from
expected,
and if true, replaces the contents of the memory pointed to
by
this with that in
desired.If and only if the comparison is true, memory is affected according to the
value of
success, and if the comparison is false, memory is affected according
to the value of
failure.When only one
memory_order argument is
supplied, the value of
success is
order, and the value of
failure is
order except that a value of
memory_order_acq_rel
shall be replaced by the value
memory_order_acquire and a value of
memory_order_release shall be replaced by the value
memory_order_relaxed.If and only if the comparison is false then, after the atomic operation,
the contents of the memory in
expected are replaced by the value
read from the memory pointed to by
this during the atomic comparison
.If the operation returns
true, these
operations are atomic read-modify-write
operations (
[intro.multithread]) on the memory
pointed to by
this.Otherwise, these operations are atomic load operations on that memory
.Returns: The result of the comparison
. [
Note: For example, the effect of
compare_exchange_strong is
if (memcmp(this, &expected, sizeof(*this)) == 0)
memcpy(this, &desired, sizeof(*this));
else
memcpy(expected, this, sizeof(*this));
—
end note ]
[
Example: The expected use of the compare-and-exchange operations is as follows
.The
compare-and-exchange operations will update
expected when another iteration of
the loop is needed
.
expected = current.load();
do {
desired = function(expected);
} while (!current.compare_exchange_weak(expected, desired)); —
end example ]
[
Example: Because the expected value is updated only on failure,
code releasing the memory containing the
expected value on success will work
.list head insertion will act atomically and would not introduce a
data race in the following code:
do {
p->next = head; } while (!head.compare_exchange_weak(p->next, p)); —
end example ]
Implementations should ensure that weak compare-and-exchange operations do not
consistently return
false unless either the atomic object has value
different from
expected or there are concurrent modifications to the
atomic object
.Remarks:
A weak compare-and-exchange operation may fail spuriously
. That is, even when
the contents of memory referred to by
expected and
this are
equal, it may return
false and store back to
expected the same memory
contents that were originally there
.[
Note: This
spurious failure enables implementation of compare-and-exchange on a broader class of
machines, e.g., load-locked store-conditional machines. A
consequence of spurious failure is that nearly all uses of weak compare-and-exchange
will be in a loop
.When a compare-and-exchange is in a loop, the weak version will yield better performance
on some platforms
.When a weak compare-and-exchange would require a loop and a strong one
would not, the strong one is preferable
. —
end note ]
[
Note: The
memcpy and
memcmp semantics of the compare-and-exchange
operations may result in failed comparisons for values that compare equal with
operator== if the underlying type has padding bits, trap bits, or alternate
representations of the same value
.Thus,
compare_exchange_strong should be used
with extreme care
.On the other hand,
compare_exchange_weak should converge
rapidly
. —
end note ]