Namespaces
Variants
Views
Actions

Difference between revisions of "cpp/atomic/atomic compare exchange"

From cppreference.com
< cpp‎ | atomic
m (Text replace - "/sidebar" to "/navbar")
m (Fix typos)
Line 49: Line 49:
 
These functions are defined in terms of member functions of {{c|std::atomic}}:
 
These functions are defined in terms of member functions of {{c|std::atomic}}:
  
−
1-2) {{c|obj->compare_exhange_weak(exp, desr)}}
+
1-2) {{c|obj->compare_exchange_weak(exp, desr)}}
  
−
3-4) {{c|obj->compare_exhange_strong(exp, desr)}}
+
3-4) {{c|obj->compare_exchange_strong(exp, desr)}}
  
−
5-6) {{c|obj->compare_exhange_weak(exp, desr, succ, fail)}}
+
5-6) {{c|obj->compare_exchange_weak(exp, desr, succ, fail)}}
  
−
7-8) {{c|obj->compare_exhange_strong(exp, desr, succ, fail)}}
+
7-8) {{c|obj->compare_exchange_strong(exp, desr, succ, fail)}}
  
  

Revision as of 16:07, 28 July 2012

 
C++
 
Atomic operations library
Types
(C++11)
(C++20)
Functions
(C++11)(C++11)
(C++11)(C++11)
(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)
(C++11)(C++11)
(C++11)(C++11)
(C++11)(C++11)
(C++11)(C++11)
(C++11)(C++11)
(C++11)
(C++20)(C++20)
(C++20)
(C++20)
Atomic flags
(C++11)
(C++11)(C++11)
(C++11)(C++11)
(C++20)(C++20)
(C++20)(C++20)
(C++20)
(C++20)
Initialization
(C++11)(deprecated in C++20)
(C++11)(deprecated in C++20)
(C++11)(deprecated in C++20)
Memory ordering
(C++11)
(C++11)
(C++11)
(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* exp, T desr)
</td>

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

<td >
template< class T >
bool atomic_compare_exchange_weak(volatile std::atomic<T>* obj, T* exp, T desr)
</td>

<td > (2) </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* exp, T desr)
</td>

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

<td >
template< class T >
bool atomic_compare_exchange_strong(volatile std::atomic<T>* obj, T* exp, T desr)
</td>

<td > (4) </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* exp, T desr,

                                           std::memory_order succ, std::memory_order fail)
</td>

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

<td >
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)
</td>

<td > (6) </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* exp, T desr,

                                    std::memory_order succ, std::memory_order fail)
</td>

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

<td >
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)
</td>

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

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_exchange_weak(exp, desr)

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

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

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


Contents

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
  

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
 specializes atomic operations for std::shared_ptr
(function template)
Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/atomic/atomic_compare_exchange&oldid=38266"