std::atomic_compare_exchange_weak, std::atomic_compare_exchange_strong, std::atomic_compare_exchange_weak_explicit, std::atomic_compare_exchange_strong_explicit

 

C++

Compiler support

Freestanding and hosted

Language

Standard library

Standard library headers

Named requirements

Feature test macros (C++20)

Language support library

Concepts library (C++20)

Metaprogramming library (C++11)

Diagnostics library

General utilities library

Strings library

Containers library

Iterators library

Ranges library (C++20)

Algorithms library

Numerics library

Localizations library

Input/output library

Filesystem library (C++17)

Regular expressions library (C++11)

Concurrency support library (C++11)

Execution support library (C++26)

Technical specifications

Symbols index

External libraries

 

Atomic operations library

Types

atomic (C++11)

atomic_ref (C++20)

Functions

atomic_storeatomic_store_explicit (C++11)(C++11)

atomic_loadatomic_load_explicit (C++11)(C++11)

atomic_exchangeatomic_exchange_explicit (C++11)(C++11)

atomic_compare_exchange_weakatomic_compare_exchange_weak_explicitatomic_compare_exchange_strongatomic_compare_exchange_strong_explicit (C++11)(C++11)(C++11)(C++11)

atomic_fetch_addatomic_fetch_add_explicit (C++11)(C++11)

atomic_fetch_subatomic_fetch_sub_explicit (C++11)(C++11)

atomic_fetch_andatomic_fetch_and_explicit (C++11)(C++11)

atomic_fetch_oratomic_fetch_or_explicit (C++11)(C++11)

atomic_fetch_xoratomic_fetch_xor_explicit (C++11)(C++11)

atomic_is_lock_free (C++11)

atomic_waitatomic_wait_explicit (C++20)(C++20)

atomic_notify_one (C++20)

atomic_notify_all (C++20)

Atomic flags

atomic_flag (C++11)

atomic_flag_test_and_setatomic_flag_test_and_set_explicit (C++11)(C++11)

atomic_flag_clearatomic_flag_clear_explicit (C++11)(C++11)

atomic_flag_testatomic_flag_test_explicit (C++20)(C++20)

atomic_flag_waitatomic_flag_wait_explicit (C++20)(C++20)

atomic_flag_notify_one (C++20)

atomic_flag_notify_all (C++20)

Initialization

atomic_init (C++11)(deprecated in C++20)

ATOMIC_VAR_INIT (C++11)(deprecated in C++20)

ATOMIC_FLAG_INIT (C++11)(deprecated in C++20)

Memory ordering

memory_order (C++11)

kill_dependency (C++11)

atomic_thread_fence (C++11)

atomic_signal_fence (C++11)

 

Template:ddcl list begin <tr class="t-dsc-header">

<td>

Defined in header <atomic>

</td>

<td></td> <td></td> </tr> <tr class="t-dcl ">

<td >

template< class T >

bool atomic_compare_exchange_weak( std::atomic<T>* obj,
                                   T* expected, T desired );
template< class T >
bool atomic_compare_exchange_weak( volatile std::atomic<T>* obj,

                                   T* expected, T desired );

</td>

<td > (1) </td> <td > (since C++11) </td> </tr> <tr class="t-dcl ">

<td >

template< class T >

bool atomic_compare_exchange_strong( std::atomic<T>* obj,
                                     T* expected, T desired );
template< class T >
bool atomic_compare_exchange_strong( volatile std::atomic<T>* obj,

                                     T* expected, T desired );

</td>

<td > (2) </td> <td > (since C++11) </td> </tr> <tr class="t-dcl ">

<td >

template< class T >

bool atomic_compare_exchange_weak_explicit( std::atomic<T>* obj,
                                            T* expected, T desired,
                                            std::memory_order succ,
                                            std::memory_order fail );
template< class T >
bool atomic_compare_exchange_weak_explicit( volatile std::atomic<T>* obj,
                                            T* expected, T desired,
                                            std::memory_order succ,

                                            std::memory_order fail );

</td>

<td > (3) </td> <td > (since C++11) </td> </tr> <tr class="t-dcl ">

<td >

template< class T >

bool atomic_compare_exchange_strong_explicit( std::atomic<T>* obj,
                                              T* expected, T desired,
                                              std::memory_order succ,
                                              std::memory_order fail );
template< class T >
bool atomic_compare_exchange_strong_explicit( volatile std::atomic<T>* obj,
                                              T* expected, T desired,
                                              std::memory_order succ,

                                              std::memory_order fail );

</td>

<td > (4) </td> <td > (since C++11) </td> </tr> Template:ddcl list end

Atomically compares the value pointed to by obj with the value pointed to by expected, and if those are equal, replaces the former with desired (performs read-modify-write operation). Otherwise, loads the actual value pointed to by obj into *expected (performs load operation).

The memory models for the read-modify-write and load operations are succ and fail respectively. The (1-2) versions use std::memory_order_seq_cst by default.

The weak forms ((1) and (3)) of the functions are allowed to fail spuriously, that is, act as if *obj != *expected even if they are equal. 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.

These functions are defined in terms of member functions of std::atomic:

1) obj->compare_exchange_weak(exp, desr)

2) obj->compare_exchange_strong(exp, desr)

3) obj->compare_exchange_weak(exp, desr, succ, fail)

4) obj->compare_exchange_strong(exp, desr, succ, fail)

Parameters

obj	-	pointer to the atomic object to test and modify
expected	-	pointer to the value expected to be found in the atomic object
desired	-	the value to store in the atomic object if it is as expected
succ	-	the memory sycnhronization ordering for the read-modify-write operation if the comparison succeeds. All values are permitted.
fail	-	the memory sycnhronization ordering for the load operation if the comparison fails. Cannot be std::memory_order_release or std::memory_order_ack_rel and cannot specify stronger ordering than succ

Return value

The result of the comparison: true if *obj was equal to *exp, false otherwise.

Exceptions

noexcept specification:  

noexcept

  

Example

This example shows how compare-and-exchange may be used to implement lock-free append to a singly linked list

Run this code

void append(list* s, node* n)
{
    node* head;
    do {
        head = s->head;
        n->next = head;
    } while(! std::atomic_compare_exchange_weak(s->head, head, n));
}

See also

Template:cpp/atomic/atomic/dcl list compare exchangeTemplate:cpp/atomic/dcl list atomic exchange

std::atomic_compare_exchange_weak(std::shared_ptr) std::atomic_compare_exchange_strong(std::shared_ptr)	specializes atomic operations for std::shared_ptr (function template)
C documentation for atomic_compare_exchange, atomic_compare_exchange_explicit