Namespaces
Variants
Views
Actions

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

From cppreference.com
< cpp‎ | atomic
m (simplify constructor in example (as atomic_var_init's page says, it's there for C11 compat; In C++, the ctor is used (e.g. in Williams book)))
(Applied P2869R4 (Remove Deprecated shared_ptr Atomic Access APIs from C++26).)
 
(11 intermediate revisions by 7 users not shown)
Line 1: Line 1:
 
{{cpp/title|atomic_exchange|atomic_exchange_explicit}}
 
{{cpp/title|atomic_exchange|atomic_exchange_explicit}}
−
{{cpp/atomic/navbar}}
+
{{cpp/thread/navbar}}
 
{{dcl begin}}
 
{{dcl begin}}
−
{{dcl header | atomic }}
+
{{dcl header|atomic}}
−
{{dcl rev begin | num=1 | since=c++11}}
+
{{dcl|num=1|since=c++11|
−
{{dcl |  
+
 
template< class T >
 
template< class T >
−
T atomic_exchange( std::atomic<T>* obj, T desr );
+
T atomic_exchange( std::atomic<T>* obj,
 +
                  typename std::atomic<T>::value_type desired ) noexcept;
 
}}
 
}}
−
{{dcl |  
+
{{dcl|num=2|since=c++11|
 
template< class T >
 
template< class T >
−
T atomic_exchange( volatile std::atomic<T>* obj, T desr );
+
T atomic_exchange( volatile std::atomic<T>* obj,
 +
                  typename std::atomic<T>::value_type desired ) noexcept;
 
}}
 
}}
−
{{dcl rev end}}
+
{{dcl|num=3|since=c++11|
−
{{dcl rev begin | num=2 | since=c++11}}
+
−
{{dcl |  
+
 
template< class T >
 
template< class T >
−
T atomic_exchange_explicit( std::atomic<T>* obj, T desr,  
+
T atomic_exchange_explicit( std::atomic<T>* obj,
−
                             std::memory_order order );
+
                            typename std::atomic<T>::value_type desired,  
 +
                             std::memory_order order ) noexcept;
 
}}
 
}}
−
{{dcl |  
+
{{dcl|num=4|since=c++11|
 
template< class T >
 
template< class T >
−
T atomic_exchange_explicit( volatile std::atomic<T>* obj, T desr,  
+
T atomic_exchange_explicit( volatile std::atomic<T>* obj,
−
                             std::memory_order order );
+
                            typename std::atomic<T>::value_type desired,  
 +
                             std::memory_order order ) noexcept;
 
}}
 
}}
−
{{dcl rev end}}
 
 
{{dcl end}}
 
{{dcl end}}
  
−
@1@ Atomically replaces the value pointed to by {{tt|obj}} with the value of {{tt|desr}} and returns the value {{tt|obj}} held previously, as if by {{c|obj->exchange(desr)}}
+
@1,2@ Atomically replaces the value pointed to by {{c|obj}} with the value of {{c|desired}} and returns the value {{c|obj}} held previously, as if by {{c|obj->exchange(desired)}}.
  
−
@2@ Atomically replaces the value pointed to by {{tt|obj}} with the value of {{tt|desr}} and returns the value {{tt|obj}} held previously, as if by {{c|obj->exchange(desr, order)}}
+
@3,4@ Atomically replaces the value pointed to by {{c|obj}} with the value of {{c|desired}} and returns the value {{c|obj}} held previously, as if by {{c|obj->exchange(desired, order)}}.
  
 
===Parameters===
 
===Parameters===
 
{{par begin}}
 
{{par begin}}
−
{{par | obj | pointer to the atomic object to modify}}
+
{{par|obj|pointer to the atomic object to modify}}
−
{{par | desr | the value to store in the atomic object}}
+
{{par|desired|the value to store in the atomic object}}
−
{{par | order | the memory sycnhronization ordering for this operation: all values are permitted.}}
+
{{par|order|the memory synchronization ordering}}
 
{{par end}}  
 
{{par end}}  
  
 
===Return value===
 
===Return value===
−
The value held previously by the atomic object pointed to by {{tt|obj}}
+
The value held previously by the atomic object pointed to by {{c|obj}}.
−
 
+
−
===Exceptions===
+
−
{{noexcept}}
+
  
 
===Example===
 
===Example===
 
{{example
 
{{example
−
| A spinlock mutex can be implemented in userspace using an atomic exchange operation, similar to {{c|std::atomic_flag_test_and_set}}:
+
|A spinlock mutex can be implemented in userspace using an atomic exchange operation, similar to {{c|std::atomic_flag_test_and_set}}:
−
| code=
+
|code=
 +
#include <atomic>
 +
#include <iostream>
 
#include <thread>
 
#include <thread>
 
#include <vector>
 
#include <vector>
−
#include <iostream>
 
−
#include <atomic>
 
  
 
std::atomic<bool> lock(false); // holds true when locked
 
std::atomic<bool> lock(false); // holds true when locked
 
                               // holds false when unlocked
 
                               // holds false when unlocked
 +
 +
int new_line{1}; // the access is synchronized via atomic lock variable
  
 
void f(int n)
 
void f(int n)
 
{
 
{
−
     for (int cnt = 0; cnt < 100; ++cnt) {
+
     for (int cnt = 0; cnt < 100; ++cnt)
−
         while(std::atomic_exchange_explicit(&lock, true, std::memory_order_acquire))
+
    {
−
            ; // spin until acquired
+
         while (std::atomic_exchange_explicit(&lock, true, std::memory_order_acquire))
−
         std::cout << "Output from thread " << n << '\n';
+
            ; // spin until acquired
 +
         std::cout << n << (new_line++ % 80 ? "" : "\n");
 
         std::atomic_store_explicit(&lock, false, std::memory_order_release);
 
         std::atomic_store_explicit(&lock, false, std::memory_order_release);
 
     }
 
     }
 
}
 
}
 +
 
int main()
 
int main()
 
{
 
{
 
     std::vector<std::thread> v;
 
     std::vector<std::thread> v;
−
     for (int n = 0; n < 10; ++n) {
+
     for (int n = 0; n < 8; ++n)
 
         v.emplace_back(f, n);
 
         v.emplace_back(f, n);
−
    }
+
     for (auto& t : v)
−
     for (auto& t : v) {
+
 
         t.join();
 
         t.join();
−
    }
 
 
}
 
}
−
| output=
+
|p=true
−
Output from thread 2
+
|output=
−
Output from thread 6
+
02222222222222222222222002222222222222222222222222222222222222222222222222222222
−
Output from thread 7
+
22222222200022222222202222211111111111110000011111111100000000000000110001111111
−
...<exactly 1000 lines>...
+
00011111000001111110000011111100000111000000001111111111111110000010000001001111
 +
11011111111011111011000000000000111100000000000001111000011133333333333333333333
 +
33333333333333333333333333333333333333333333333333333333333333333333333333333333
 +
44444444444444444444444444444444444444444444444444444444444444444444444444444444
 +
44444444444444444444555555555555555555555555555555555555555555555555555555555555
 +
55555555555555555555555555555555555555556666666666666666666666666666666666666666
 +
66666666666666666666666666666666666666666666666666666666666677777777777777777777
 +
77777777777777777777777777777777777777777777777777777777777777777777777777777777
 
}}
 
}}
 +
 +
===Defect reports===
 +
{{dr list begin}}
 +
{{dr list item|std=C++11|paper=P0558R1|before=exact type match was required because<br>{{tt|T}} was deduced from multiple arguments|after={{tt|T}} is only deduced<br>from {{c|obj}}}}
 +
{{dr list end}}
  
 
===See also===
 
===See also===
 
{{dsc begin}}
 
{{dsc begin}}
−
{{dsc inc | cpp/atomic/atomic/dsc exchange | mem=std::atomic<T>}}
+
{{dsc inc|cpp/atomic/atomic/dsc exchange|mem=std::atomic<T>}}
−
{{dsc inc | cpp/atomic/dsc atomic_compare_exchange}}
+
{{dsc inc|cpp/atomic/dsc atomic_compare_exchange}}
−
{{dsc tfun | cpp/memory/shared_ptr/atomic | title=std::atomic_exchange{{dsc small|(std::shared_ptr)}}
+
{{dsc break}}
−
<br>std::atomic_exchange_explicit{{dsc small|(std::shared_ptr)}} | specializes atomic operations for {{lc|std::shared_ptr}} }}
+
{{dsc tfun|cpp/memory/shared_ptr/atomic|notes={{mark life|deprecated=c++20|removed=c++26|br=yes}}|title=std::atomic_exchange{{dsc small|(std::shared_ptr)}}
−
{{dsc see c | c/atomic/atomic_exchange | atomic_exchange | atomic_exchange_explicit}}
+
<br>std::atomic_exchange_explicit{{dsc small|(std::shared_ptr)}}|specializes atomic operations for {{lc|std::shared_ptr}}}}
 +
{{dsc see c|c/atomic/atomic_exchange|atomic_exchange|atomic_exchange_explicit}}
 
{{dsc end}}
 
{{dsc end}}
  
−
[[de:cpp/atomic/atomic exchange]]
+
{{langlinks|de|es|fr|it|ja|pt|ru|zh}}
−
[[es:cpp/atomic/atomic exchange]]
+
−
[[fr:cpp/atomic/atomic exchange]]
+
−
[[it:cpp/atomic/atomic exchange]]
+
−
[[ja:cpp/atomic/atomic exchange]]
+
−
[[pt:cpp/atomic/atomic exchange]]
+
−
[[ru:cpp/atomic/atomic exchange]]
+
−
[[zh:cpp/atomic/atomic exchange]]
+

Latest revision as of 05:24, 24 April 2024

 
C++
 
Concurrency support library
Threads
(C++11)
(C++20)
(C++17)(C++17)
this_thread namespace
(C++11)
(C++11)
(C++11)
(C++11)
Cooperative cancellation
Mutual exclusion
(C++11)
(C++11)
(C++17)
Generic lock management
(C++11)
(C++11)
(C++17)
(C++11)
(C++14)
(C++11)
(C++11)
(C++11)
(C++11)(C++11)(C++11)(C++11)(C++11)(C++11)
Condition variables
(C++11)
(C++11)
(C++11)
(C++11)
Semaphores
(C++20)(C++20)
Latches and Barriers
(C++20)
(C++20)
Futures
(C++11)
(C++11)
(C++11)
(C++11)
(C++11)
(C++11)
(C++11)
(C++11)
(C++11)
(C++11)
Safe Reclamation
(C++26)
(C++26)
(C++26)
Hazard Pointers
(C++26)
(C++26)
(C++26)
Atomic types
(C++11)
(C++20)
(C++11)
Initialization of atomic types
(C++11)(deprecated in C++20)
(C++11)(deprecated in C++20)
(C++11)
Memory ordering
(C++11)
(C++11)
(C++11)
(C++11)
Free functions for atomic operations
(C++11)(C++11)
(C++11)(C++11)
atomic_exchangeatomic_exchange_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++11)
(C++26)(C++26)
(C++26)(C++26)
(C++11)
(C++20)(C++20)
(C++20)
(C++20)
Free functions for atomic flags
(C++11)(C++11)
(C++11)(C++11)
(C++20)(C++20)
(C++20)(C++20)
(C++20)
(C++20)
 
Defined in header <atomic>
template< class T >

T atomic_exchange( std::atomic<T>* obj,

                   typename std::atomic<T>::value_type desired ) noexcept;
 (1) (since C++11)
template< class T >

T atomic_exchange( volatile std::atomic<T>* obj,

                   typename std::atomic<T>::value_type desired ) noexcept;
 (2) (since C++11)
template< class T >

T atomic_exchange_explicit( std::atomic<T>* obj,
                            typename std::atomic<T>::value_type desired,

                            std::memory_order order ) noexcept;
 (3) (since C++11)
template< class T >

T atomic_exchange_explicit( volatile std::atomic<T>* obj,
                            typename std::atomic<T>::value_type desired,

                            std::memory_order order ) noexcept;
 (4) (since C++11)
1,2) Atomically replaces the value pointed to by obj with the value of desired and returns the value obj held previously, as if by obj->exchange(desired).
3,4) Atomically replaces the value pointed to by obj with the value of desired and returns the value obj held previously, as if by obj->exchange(desired, order).

Contents

[edit] Parameters

obj - pointer to the atomic object to modify
desired - the value to store in the atomic object
order - the memory synchronization ordering

[edit] Return value

The value held previously by the atomic object pointed to by obj.

[edit] Example

A spinlock mutex can be implemented in userspace using an atomic exchange operation, similar to std::atomic_flag_test_and_set:

Run this code
#include <atomic>
#include <iostream>
#include <thread>
#include <vector>
 
std::atomic<bool> lock(false); // holds true when locked
                               // holds false when unlocked
 
int new_line{1}; // the access is synchronized via atomic lock variable
 
void f(int n)
{
    for (int cnt = 0; cnt < 100; ++cnt)
    {
        while (std::atomic_exchange_explicit(&lock, true, std::memory_order_acquire))
            ; // spin until acquired
        std::cout << n << (new_line++ % 80 ? "" : "\n");
        std::atomic_store_explicit(&lock, false, std::memory_order_release);
    }
}
 
int main()
{
    std::vector<std::thread> v;
    for (int n = 0; n < 8; ++n)
        v.emplace_back(f, n);
    for (auto& t : v)
        t.join();
}

Possible output: 

02222222222222222222222002222222222222222222222222222222222222222222222222222222
22222222200022222222202222211111111111110000011111111100000000000000110001111111
00011111000001111110000011111100000111000000001111111111111110000010000001001111
11011111111011111011000000000000111100000000000001111000011133333333333333333333
33333333333333333333333333333333333333333333333333333333333333333333333333333333
44444444444444444444444444444444444444444444444444444444444444444444444444444444
44444444444444444444555555555555555555555555555555555555555555555555555555555555
55555555555555555555555555555555555555556666666666666666666666666666666666666666
66666666666666666666666666666666666666666666666666666666666677777777777777777777
77777777777777777777777777777777777777777777777777777777777777777777777777777777

[edit] Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

DR Applied to Behavior as published Correct behavior
P0558R1 C++11 exact type match was required because
T was deduced from multiple arguments 		T is only deduced
from obj

[edit] See also

 atomically replaces the value of the atomic object and obtains the value held previously
(public member function of std::atomic<T>) [edit]
(C++11)(C++11)(C++11)(C++11)
 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]
(deprecated in C++20)(removed in C++26)
 specializes atomic operations for std::shared_ptr
(function template)
C documentation for atomic_exchange, atomic_exchange_explicit
Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/atomic/atomic_exchange&oldid=171254"