NAME
atomic_compare_exchange_strong
atomic_compare_exchange_strong_explicit
atomic_compare_exchange_weak
atomic_compare_exchange_weak_explicit —
atomically compare and exchange the values of two
objects
SYNOPSIS
#include
<stdatomic.h>
_Bool atomic_compare_exchange_strong(volatile A *object,
C *expected, C desired);
_Bool atomic_compare_exchange_strong_explicit(volatile A *object,
C *expected, C desired, memory_order success, memory_order failure);
_Bool atomic_compare_exchange_weak(volatile A *object,
C *expected, C desired);
_Bool atomic_compare_exchange_weak_explicit(volatile A *object,
C *expected, C desired, memory_order success, memory_order failure);
DESCRIPTION
[CX] The functionality described on this reference page is aligned with the ISO C standard. Any conflict between the requirements described here and the ISO C standard is unintentional. This volume of POSIX.1-2024 defers to the ISO C standard.
Implementations that define the macro __STDC_NO_ATOMICS__ need not provide the <stdatomic.h> header nor support these generic functions.
The
atomic_compare_exchange_strong_explicit () generic
function shall atomically compare the contents of the memory pointed to by
object for equality with that pointed to by
expected, and if true, shall replace the contents of the
memory pointed to by object with
desired, and if
false, shall update the contents of the memory pointed to by
expected with that pointed to by
object.
This operation shall be an atomic read-modify-write operation (see XBD
V1_chap04(7)). If the comparison is true,
memory shall be affected according to the value of
success, and if the comparison is false,
memory shall be affected according to the value of
failure. The application shall ensure that
failure is not
memory_order_release nor
memory_order_acq_rel, and shall ensure that
failure is no stronger than success.
The atomic_compare_exchange_strong ()
generic function shall be equivalent to
atomic_compare_exchange_strong_explicit () called with
success and failure both set to
memory_order_seq_cst.
The atomic_compare_exchange_weak_explicit () generic function shall be equivalent to atomic_compare_exchange_strong_explicit (), except that the compare-and-exchange operation may fail spuriously. That is, even when the contents of memory referred to by expected and object are equal, it may return zero and store back to expected the same memory contents that were originally there.
The
atomic_compare_exchange_weak
() generic function shall be equivalent to
atomic_compare_exchange_weak_explicit () called with
success and failure both set to
memory_order_seq_cst.
RETURN VALUE
These generic functions shall return the result of the comparison.
ERRORS
No errors are defined.
EXAMPLES
None.
APPLICATION USAGE
A consequence of spurious failure is that nearly all uses of weak compare-and-exchange will be in a loop. For example:
exp = atomic_load(&cur);
do {
des = function(exp);
} while (!atomic_compare_exchange_weak(&cur, &exp, des));
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.
RATIONALE
None.
FUTURE DIRECTIONS
None.
SEE ALSO
CHANGE HISTORY
First released in Issue 8. Included for alignment with the ISO/IEC 9899:2018 standard.