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:
- 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.
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.