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 4.15.1 Memory Ordering). 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

XBD 4.15.1 Memory Ordering, <stdatomic.h>

CHANGE HISTORY

First released in Issue 8. Included for alignment with the ISO/IEC 9899:2018 standard.