public member function
<atomic>

std::atomic::compare_exchange_strong

(1)
bool compare_exchange_strong (T& expected, T val,
           memory_order sync = memory_order_seq_cst) volatile noexcept;
bool compare_exchange_strong (T& expected, T val,
           memory_order sync = memory_order_seq_cst) noexcept;
(2)
bool compare_exchange_strong (T& expected, T val,
           memory_order success, memory_order failure) volatile noexcept;
bool compare_exchange_strong (T& expected, T val,
           memory_order success, memory_order failure) noexcept;
Compare and exchange contained value (strong)
Compares the contents of the contained value with expected:
- if true, it replaces the contained value with val (like store).
- if false, it replaces expected with the contained value .

The function always accesses the contained value to read it, and -if the comparison is true- it then also replaces it. But the entire operation is atomic: the value cannot be modified by other threads between the instant its value is read and the moment it is replaced.

The memory order used in (2) depends on the result of the comparison: if true, it uses success; if false, it uses failure.

Note that this function compares directly the physical contents of the contained value with the contents of expected; This may result in failed comparisons for values that compare equal using operator== (if the underlying type has padding bits, trap values, or alternate representations of the same value), although this comparison shall converge rapidly in a loop that preserves expected such as those generally used with compare_exchange_weak.

Unlike compare_exchange_weak, this strong version is required to always return true when expected indeed compares equal to the contained object, not allowing spurious failures. However, on certain machines, and for certain algorithms that check this in a loop, compare_exchange_weak may lead to significantly better performance.

Parameters

expected
Reference to an object whose value is compared to the contained value, and which -in case it doesn't match- is overwritten with the contained value.
T is atomic's template parameter (the type of the contained value).
val
Value to copy to the contained object in case expected matches the contained value.
T is atomic's template parameter (the type of the contained value).
sync
Synchronization mode for the operation.
This can be any of the possible values of the enum type memory_order:
valuememory orderdescription
memory_order_relaxedRelaxedNo synchronization of side effects.
memory_order_consumeConsume Synchronizes the visible side effects on values carrying dependencies from the last release or sequentially consistent operation.
memory_order_acquireAcquireSynchronizes all visible side effects from the last release or sequentially consistent operation.
memory_order_releaseReleaseSynchronizes side effects with the next consume or acquire operation.
memory_order_acq_relAcquire/ReleaseReads as an acquire operation and writes as a release operation (as described above).
memory_order_seq_cstSequentially consistentSynchronizes all visible side effects with the other sequentially consistent operations, following a single total order.
success
Synchronization mode for the operation in case expected matches the contained value.
failure
Synchronization mode for the operation in case expected does not match the contained value. This shall not be a stronger mode than success and shall neither be memory_order_release nor memory_order_acq_rel.

Return value

true if expected compares equal to the contained value.
false otherwise.

Example

See compare_exchange_weak's example.

Data races

No data races (atomic operation). Memory order specified by argument sync (or arguments success and failure).

Exception safety

No-throw guarantee: never throws exceptions.

See also