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

Latest revision as of 05:24, 24 April 2024

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).

#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

exchange	atomically replaces the value of the atomic object and obtains the value held previously (public member function of `std::atomic<T>`) [edit]
atomic_compare_exchange_weakatomic_compare_exchange_weak_explicitatomic_compare_exchange_strongatomic_compare_exchange_strong_explicit (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]

std::atomic_exchange(std::shared_ptr) std::atomic_exchange_explicit(std::shared_ptr) (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

@@ Line 1: / Line 1: @@
 {{cpp/title|atomic_exchange|atomic_exchange_explicit}}
-{{cpp/atomic/navbar}}
+{{cpp/thread/navbar}}
-{{ddcl list begin}}
+{{dcl begin}}
-{{ddcl list header | atomic }}
+{{dcl header|atomic}}
-{{ddcl list item | num=1 | notes={{mark since c++11}} | 1=
+{{dcl|num=1|since=c++11|
 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;
 }}
-{{ddcl list item | num=2 | notes={{mark since c++11}} | 1=
+{{dcl|num=2|since=c++11|
 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;
 }}
-{{ddcl list item | num=3 | notes={{mark since c++11}} | 1=
+{{dcl|num=3|since=c++11|
 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;
 }}
-{{ddcl list item | num=4 | notes={{mark since c++11}} | 1=
+{{dcl|num=4|since=c++11|
 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;
 }}
-{{ddcl list end}}
+{{dcl end}}
--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->exhange(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)}}.
--4) 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->exhange(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===
+{{par begin}}
-{{param list begin}}
+{{par|obj|pointer to the atomic object to modify}}
-{{param list item | obj | pointer to the atomic object to modify}}
+{{par|desired|the value to store in the atomic object}}
-{{param list item | desr | the value to store in the atomic object}}
+{{par|order|the memory synchronization ordering}}
-{{param list item | order | the memory sycnhronization ordering for this operation: all values are permitted.}}
+{{par end}}
-{{param list end}}
 ===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
- | A spinlock mutex can be implemented in userspace using an atomic exchange operation, similar to 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 <vector>
-#include <iostream>
-#include <atomic>
-std::atomic<bool> lock = ATOMIC_VAR_INIT(false);
+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) {
+     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);
      }
 }
 int main()
 {
      std::vector<std::thread> v;
-     for (int n = 0; n < 10; ++n) {
+     for (int n = 0; n < 8; ++n)
          v.emplace_back(f, n);
-    }
+     for (auto& t : v)
-     for (auto& t : v) {
          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===
-{{dcl list begin}}
+{{dsc begin}}
-{{dcl list template | cpp/atomic/atomic/dcl list exchange | mem=std::atomic<T>}}
+{{dsc inc|cpp/atomic/atomic/dsc exchange|mem=std::atomic<T>}}
-{{dcl list template | cpp/atomic/dcl list atomic_compare_exchange}}
+{{dsc inc|cpp/atomic/dsc atomic_compare_exchange}}
-{{dcl list tfun | cpp/memory/shared_ptr/atomic_access | title=std::atomic_exchange{{dcl small|(std::shared_ptr)}}
+{{dsc break}}
-<br>std::atomic_exchange_explicit{{dcl small|(std::shared_ptr)}} | specializes atomic operations for {{c|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)}}
-{{dcl list 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}}}}
-{{dcl list end}}
+{{dsc see c|c/atomic/atomic_exchange|atomic_exchange|atomic_exchange_explicit}}
+{{dsc end}}
+{{langlinks|de|es|fr|it|ja|pt|ru|zh}}

Compiler support
Freestanding and hosted
Language
Standard library
Standard library headers
Named requirements
Feature test macros (C++20)
Language support library
Concepts library (C++20)
Metaprogramming library (C++11)
Diagnostics library
General utilities library
Strings library
Containers library
Iterators library
Ranges library (C++20)
Algorithms library
Numerics library
Localizations library
Input/output library
Filesystem library (C++17)
Regular expressions library (C++11)
Concurrency support library (C++11)
Execution support library (C++26)
Technical specifications
Symbols index
External libraries

cppreference.com

Namespaces

Variants

Views

Actions

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

Latest revision as of 05:24, 24 April 2024

Contents

[edit] Parameters

[edit] Return value

[edit] Example

[edit] Defect reports

[edit] See also

Navigation

Toolbox

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