|
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Member functions | ||||
atomic::compare_exchange_strongatomic::compare_exchange_weak | ||||
(C++20) | ||||
(C++20) | ||||
(C++20) | ||||
| Constants | ||||
(C++17) | ||||
| Specialized member functions | ||||
| Specialized for integral, floating-point(C++20) and pointer types | ||||
| Specialized for integral and pointer types only | ||||
(C++26) | ||||
(C++26) | ||||
| Specialized for integral types only | ||||
bool compare_exchange_weak( T& expected, T desired, std::memory_order success, | (1) | (since C++11) |
bool compare_exchange_weak( T& expected, T desired, std::memory_order success, | (2) | (since C++11) |
bool compare_exchange_weak( T& expected, T desired, std::memory_order order= | (3) | (since C++11) |
bool compare_exchange_weak( T& expected, T desired, std::memory_order order= | (4) | (since C++11) |
bool compare_exchange_strong( T& expected, T desired, std::memory_order success, | (5) | (since C++11) |
bool compare_exchange_strong( T& expected, T desired, std::memory_order success, | (6) | (since C++11) |
bool compare_exchange_strong( T& expected, T desired, std::memory_order order= | (7) | (since C++11) |
bool compare_exchange_strong ( T& expected, T desired, | (8) | (since C++11) |
Atomically compares theobject representation(until C++20)value representation(since C++20) of*this with that ofexpected. If those are bitwise-equal, replaces the former withdesired (performs read-modify-write operation). Otherwise, loads the actual value stored in*this intoexpected (performs load operation).
| Overloads | Memory model for | |
|---|---|---|
| read‑modify‑write operation | load operation | |
| (1,2,5,6) | success | failure |
| (3,4,7,8) | order |
|
Iffailure is stronger thansuccess or(until C++17) is one ofstd::memory_order_release andstd::memory_order_acq_rel, the behavior is undefined.
It is deprecated ifstd::atomic<T>::is_always_lock_free isfalse and anyvolatile overload participates in overload resolution. | (since C++20) |
Contents |
| expected | - | reference 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 |
| success | - | the memory synchronization ordering for the read-modify-write operation if the comparison succeeds |
| failure | - | the memory synchronization ordering for the load operation if the comparison fails |
| order | - | the memory synchronization ordering for both operations |
true if the underlying atomic value was successfully changed,false otherwise.
The comparison and copying are bitwise (similar tostd::memcmp andstd::memcpy); no constructor, assignment operator, or comparison operator are used.
compare_exchange_weak is allowed to fail spuriously, that is, acts as if*this!= expected even if they are equal. When a compare-and-exchange is in a loop,compare_exchange_weak will yield better performance on some platforms.
Whencompare_exchange_weak would require a loop andcompare_exchange_strong would not,compare_exchange_strong is preferable unless the object representation ofT may includepadding bits,(until C++20) trap bits, or offers multiple object representations for the same value (e.g. floating-point NaN). In those cases,compare_exchange_weak typically works because it quickly converges on some stable object representation.
For a union with bits that participate in the value representations of some members but not the others, compare-and-exchange might always fail because such padding bits have indeterminate values when they do not participate in the value representation of the active member.
Padding bits that never participate in an object's value representation are ignored. | (since C++20) |
Compare-and-exchange operations are often used as basic building blocks oflock-free data structures.
#include <atomic> template<typename T>struct node{ T data; node* next; node(const T& data): data(data), next(nullptr){}}; template<typename T>class stack{std::atomic<node<T>*> head;public:void push(const T& data){ node<T>* new_node= new node<T>(data); // put the current value of head into new_node->next new_node->next= head.load(std::memory_order_relaxed); // now make new_node the new head, but if the head// is no longer what's stored in new_node->next// (some other thread must have inserted a node just now)// then put that new head into new_node->next and try againwhile(!head.compare_exchange_weak(new_node->next, new_node,std::memory_order_release,std::memory_order_relaxed));// the body of the loop is empty // Note: the above use is not thread-safe in at least// GCC prior to 4.8.3 (bug 60272), clang prior to 2014-05-05 (bug 18899)// MSVC prior to 2014-03-17 (bug 819819). The following is a workaround:// node<T>* old_head = head.load(std::memory_order_relaxed);// do// {// new_node->next = old_head;// }// while (!head.compare_exchange_weak(old_head, new_node,// std::memory_order_release,// std::memory_order_relaxed));}}; int main(){ stack<int> s; s.push(1); s.push(2); s.push(3);}
Demonstrates howstd::compare_exchange_strong either changes the value of the atomic variable or the variable used for comparison.
| This section is incomplete Reason: more practical use of the strong CAS would be nice, such as where Concurrency in Action uses it |
#include <atomic>#include <iostream> std::atomic<int> ai; int tst_val=4;int new_val=5;bool exchanged=false; void valsout(){std::cout<<"ai = "<< ai<<" tst_val = "<< tst_val<<" new_val = "<< new_val<<" exchanged = "<<std::boolalpha<< exchanged<<'\n';} int main(){ ai=3; valsout(); // tst_val != ai ==> tst_val is modified exchanged= ai.compare_exchange_strong(tst_val, new_val); valsout(); // tst_val == ai ==> ai is modified exchanged= ai.compare_exchange_strong(tst_val, new_val); valsout();}
Output:
ai = 3 tst_val = 4 new_val = 5 exchanged = falseai = 3 tst_val = 3 new_val = 5 exchanged = falseai = 5 tst_val = 3 new_val = 5 exchanged = true
| atomically compares the value of the atomic object with non-atomic argument and performs atomic exchange if equal or atomic load if not (function template)[edit] |
