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

 

C++

Language

Concepts

Utilities library

Strings library

Containers library

Algorithms library

Iterators library

Numerics library

Input/output library

Localizations library

Regular expressions library (C++11)

Atomic operations library (C++11)

Thread support library (C++11)

 

Atomic operations library

Types

atomic (C++11)

atomic_is_lock_free (C++11)

Functions

atomic_store atomic_store_explicit (C++11) (C++11)

atomic_load atomic_load_explicit (C++11) (C++11)

atomic_exchange atomic_exchange_explicit (C++11) (C++11)

atomic_compare_exchange_weak atomic_compare_exchange_weak_explicit atomic_compare_exchange_strong atomic_compare_exchange_strong_explicit (C++11) (C++11) (C++11) (C++11)

atomic_fetch_add atomic_fetch_add_explicit (C++11) (C++11)

atomic_fetch_sub atomic_fetch_sub_explicit (C++11) (C++11)

atomic_fetch_and atomic_fetch_and_explicit (C++11) (C++11)

atomic_fetch_or atomic_fetch_or_explicit (C++11) (C++11)

atomic_fetch_xor atomic_fetch_xor_explicit (C++11) (C++11)

Atomic flags

atomic_flag (C++11)

atomic_flag_test_and_set atomic_flag_test_and_set_explicit (C++11) (C++11)

atomic_flag_clear atomic_flag_clear_explicit (C++11) (C++11)

Initialization

atomic_init (C++11)

ATOMIC_VAR_INIT (C++11)

ATOMIC_FLAG_INIT (C++11)

Memory ordering

memory_order (C++11)

kill_dependency (C++11)

atomic_thread_fence (C++11)

atomic_signal_fence (C++11)

 

Defined in header <atomic>
template< class T > bool atomic_compare_exchange_weak(std::atomic<T>* obj, T* exp, T desr)	(1)	(since C++11)
template< class T > bool atomic_compare_exchange_weak(volatile std::atomic<T>* obj, T* exp, T desr)	(2)	(since C++11)
template< class T > bool atomic_compare_exchange_strong(std::atomic<T>* obj, T* exp, T desr)	(3)	(since C++11)
template< class T > bool atomic_compare_exchange_strong(volatile std::atomic<T>* obj, T* exp, T desr)	(4)	(since C++11)
template< class T > bool atomic_compare_exchange_weak_explicit(std::atomic<T>* obj, T* exp, T desr,                                            std::memory_order succ, std::memory_order fail)	(5)	(since C++11)
template< class T > bool atomic_compare_exchange_weak_explicit(volatile std::atomic<T>* obj, T* exp, T desr,                                            std::memory_order succ, std::memory_order fail)	(6)	(since C++11)
template< class T > bool atomic_compare_exchange_strong(std::atomic<T>* obj, T* exp, T desr,                                     std::memory_order succ, std::memory_order fail)	(7)	(since C++11)
template< class T > bool atomic_compare_exchange_strong(volatile std::atomic<T>* obj, T* exp, T desr,                                     std::memory_order succ, std::memory_order fail)	(8)	(since C++11)

In a single atomic operation, first compares the value pointed to by obj with the value pointed to by exp for equality. Then, if the values are equal, replaces the value pointed to by obj with the value of desr (performs a read-modify-write operation). Otherwise, if the values are not equal, replaces the value pointed to by exp with the value of obj (performs a load operation), using the memory model fail

1,2,5,6) The weak form of this function is allowed to fail spuriously, that is, return false and perform the load from *obj to *exp even if *obj == *exp. 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-2) obj->compare_exhange_weak(exp, desr)

3-4) obj->compare_exhange_strong(exp, desr)

5-6) obj->compare_exhange_weak(exp, desr, succ, fail)

7-8) obj->compare_exhange_strong(exp, desr, succ, fail)

Parameters

obj	-	pointer to the atomic object to test and modify
exp	-	pointer to the value expected to be found in the atomic object
desr	-	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

  (since C++11)

Example

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

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

compare_exchange_weak compare_exchange_strong	atomically compares the value of the atomic object with non-atomic argument and performs atomic exchange if equal or atomic load if not (public member function of std::atomic)
atomic_exchange atomic_exchange_explicit (C++11) (C++11)	atomically replaces the value of the atomic object with non-atomic argument and returns the old value of the atomic (function template)
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)