Difference between revisions of "cpp/atomic/atomic compare exchange"
(fmt) |
m (Use new list syntax) |
||
| Line 53: | Line 53: | ||
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@ {{c|obj->compare_exchange_weak(exp, desr)}} | |
| − | + | @2@ {{c|obj->compare_exchange_strong(exp, desr)}} | |
| − | + | @3@ {{c|obj->compare_exchange_weak(exp, desr, succ, fail)}} | |
| − | + | @4@ {{c|obj->compare_exchange_strong(exp, desr, succ, fail)}} | |
| − | + | ||
| − | + | ||
===Parameters=== | ===Parameters=== | ||
Revision as of 12:18, 30 August 2012
Template:ddcl list begin <tr class="t-dsc-header">
<td><atomic>
<td></td> <td></td> </tr> <tr class="t-dcl ">
<td >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,
<td > (1) </td> <td > (since C++11) </td> </tr> <tr class="t-dcl ">
<td >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,
<td > (2) </td> <td > (since C++11) </td> </tr> <tr class="t-dcl ">
<td >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,
<td > (3) </td> <td > (since C++11) </td> </tr> <tr class="t-dcl ">
<td >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,
<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:
Contents |
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
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
| specializes atomic operations for std::shared_ptr (function template) | |
| C documentation for atomic_compare_exchange, atomic_compare_exchange_explicit
| |
