std::atomic_exchange,std::atomic_exchange_explicit(3)

NAME
std::atomic_exchange,std::atomic_exchange_explicit - std::atomic_exchange,std::atomic_exchange_explicit

Synopsis
   Defined in header <atomic>
   template< class T >
   T atomic_exchange( std::atomic<T>* obj, (1) (since C++11)
                      typename std::atomic<T>::value_type desired )
   noexcept;
   template< class T >
   T atomic_exchange( volatile std::atomic<T>* obj, (2) (since C++11)
                      typename std::atomic<T>::value_type desired )
   noexcept;
   template< class T >
   T atomic_exchange_explicit( std::atomic<T>* obj,
                        typename std::atomic<T>::value_type (3) (since C++11)
   desired,
                        std::memory_order order ) noexcept;
   template< class T >
   T atomic_exchange_explicit( volatile std::atomic<T>* obj,
                        typename std::atomic<T>::value_type (4) (since C++11)
   desired,
                        std::memory_order order ) noexcept;
   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).

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

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

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
   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 is only deduced
                      T was deduced from multiple arguments from obj

See also
                        atomically replaces the value of the atomic
   exchange object and obtains the value held previously
                        (public member function of std::atomic<T>)
   atomic_compare_exchange_weak
   atomic_compare_exchange_weak_explicit atomically compares the value of the atomic
   atomic_compare_exchange_strong object with non-atomic argument and performs
   atomic_compare_exchange_strong_explicit atomic exchange if equal or atomic load if
   (C++11) not
   (C++11) (function template)
   (C++11)
   (C++11)
   std::atomic_exchange(std::shared_ptr) specializes atomic operations for
   std::atomic_exchange_explicit(std::shared_ptr) std::shared_ptr
   (deprecated in C++20) (function template)
   (removed in C++26)
   C documentation for
   atomic_exchange,
   atomic_exchange_explicit