std:: atomic_exchange, std:: atomic_exchange_explicit

From cppreference.com

< cpp ‎ | atomic

Concurrency support library

Threads

thread

(C++11)

jthread

(C++20)

hardware_destructive_interference_size hardware_constructive_interference_size

(C++17) (C++17)


                    this_thread

namespace

get_id (C++11)
yield (C++11)

sleep_for (C++11)
sleep_until (C++11)

Cooperative cancellation

stop_token (C++20)
inplace_stop_token (C++26)
never_stop_token (C++26)
stop_source (C++20)
inplace_stop_source (C++26)
stop_callback (C++20)

inplace_stop_callback (C++26)
stop_callback_for_t (C++26)
stoppable_token (C++26)
unstoppable_token (C++26)
stoppable-source (C++26)
stoppable-callback-for (C++26)

Mutual exclusion

mutex (C++11)
recursive_mutex (C++11)
shared_mutex (C++17)

timed_mutex (C++11)
recursive_timed_mutex (C++11)
shared_timed_mutex (C++14)

Generic lock management

lock (C++11)
lock_guard (C++11)
scoped_lock (C++17)
unique_lock (C++11)
shared_lock (C++14)
once_flag (C++11)
call_once (C++11)

try_lock (C++11)
defer_lock try_to_lock adopt_lock defer_lock_t try_to_lock_t adopt_lock_t (C++11) (C++11) (C++11) (C++11) (C++11) (C++11)

Condition variables

condition_variable

(C++11)

condition_variable_any

(C++11)

notify_all_at_thread_exit

(C++11)

cv_status

(C++11)

Semaphores

counting_semaphore binary_semaphore

(C++20) (C++20)

Latches and Barriers

latch

(C++20)

barrier

(C++20)

Futures

promise (C++11)
future (C++11)
shared_future (C++11)
packaged_task (C++11)
async (C++11)

launch (C++11)
future_status (C++11)
future_error (C++11)
future_category (C++11)
future_errc (C++11)

Safe Reclamation

rcu_obj_base (C++26)
rcu_domain (C++26)
rcu_default_domain (C++26)

rcu_synchronize (C++26)
rcu_barrier (C++26)
rcu_retire (C++26)

Hazard Pointers

hazard_pointer_obj_base

(C++26)

hazard_pointer

(C++26)

make_hazard_pointer

(C++26)

Atomic types
atomic (C++11)
atomic_ref (C++20)
atomic_flag (C++11)
Initialization of atomic types
atomic_init (C++11) (deprecated in C++20)
ATOMIC_VAR_INIT (C++11) (deprecated in C++20)
ATOMIC_FLAG_INIT (C++11)
Memory ordering
memory_order (C++11)
kill_dependency (C++11)
atomic_thread_fence (C++11)
atomic_signal_fence (C++11)
Free functions for atomic operations
atomic_store atomic_store_explicit (C++11) (C++11)
atomic_load atomic_load_explicit (C++11) (C++11)
atomic_exchange atomic_exchange_explicit (C++11) (C++11)
atomic_compare_exchange_weak atomic_compare_exchange_weak_explicit atomic_compare_exchange_strong atomic_compare_exchange_strong_explicit (C++11) (C++11) (C++11) (C++11)
atomic_fetch_add atomic_fetch_add_explicit (C++11) (C++11)
atomic_fetch_sub atomic_fetch_sub_explicit (C++11) (C++11)
atomic_fetch_and atomic_fetch_and_explicit (C++11) (C++11)
atomic_fetch_or atomic_fetch_or_explicit (C++11) (C++11)
atomic_fetch_xor atomic_fetch_xor_explicit (C++11) (C++11)
atomic_fetch_max atomic_fetch_max_explicit (C++26) (C++26)
atomic_fetch_min atomic_fetch_min_explicit (C++26) (C++26)
atomic_is_lock_free (C++11)
atomic_wait atomic_wait_explicit (C++20) (C++20)
atomic_notify_one (C++20)
atomic_notify_all (C++20)
Free functions for atomic flags
atomic_flag_test_and_set atomic_flag_test_and_set_explicit (C++11) (C++11)
atomic_flag_clear atomic_flag_clear_explicit (C++11) (C++11)
atomic_flag_test atomic_flag_test_explicit (C++20) (C++20)
atomic_flag_wait atomic_flag_wait_explicit (C++20) (C++20)
atomic_flag_notify_one (C++20)
atomic_flag_notify_all (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 ) .

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

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

std:: atomic_exchange, std:: atomic_exchange_explicit

Parameters

Return value

Example

Defect reports

See also

Navigation

exchange	atomically replaces the value of the atomic object and obtains the value held previously (public member function of `std::atomic<T>` )
atomic_compare_exchange_weak atomic_compare_exchange_weak_explicit atomic_compare_exchange_strong atomic_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)

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