std::atomic_wait,std::atomic_wait_explicit

From cppreference.com

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)
Diagnostics library
Memory management library
Metaprogramming library(C++11)
General utilities library
Containers library
Iterators library
Ranges library(C++20)
Algorithms library
Strings library
Text processing library
Numerics library
Date and time library
Input/output library
Filesystem library(C++17)
Concurrency support library(C++11)
Execution control library(C++26)
Technical specifications
Symbols index
External libraries

[edit]

Concurrency support library

Threads

thread

(C++11)

jthread

(C++20)

hardware_destructive_interference_sizehardware_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_locktry_to_lockadopt_lockdefer_lock_ttry_to_lock_tadopt_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_semaphorebinary_semaphore

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

(C++20)

(C++20)

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)(deprecated in C++26)
atomic_thread_fence (C++11)
atomic_signal_fence (C++11)
Free functions for atomic operations
atomic_storeatomic_store_explicit (C++11)(C++11)
atomic_loadatomic_load_explicit (C++11)(C++11)
atomic_exchangeatomic_exchange_explicit (C++11)(C++11)
atomic_compare_exchange_weakatomic_compare_exchange_weak_explicitatomic_compare_exchange_strongatomic_compare_exchange_strong_explicit (C++11)(C++11)(C++11)(C++11)
atomic_fetch_addatomic_fetch_add_explicit (C++11)(C++11)
atomic_fetch_subatomic_fetch_sub_explicit (C++11)(C++11)
atomic_fetch_andatomic_fetch_and_explicit (C++11)(C++11)
atomic_fetch_oratomic_fetch_or_explicit (C++11)(C++11)
atomic_fetch_xoratomic_fetch_xor_explicit (C++11)(C++11)
atomic_fetch_maxatomic_fetch_max_explicit (C++26)(C++26)
atomic_fetch_minatomic_fetch_min_explicit (C++26)(C++26)
atomic_is_lock_free (C++11)
atomic_waitatomic_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_setatomic_flag_test_and_set_explicit (C++11)(C++11)
atomic_flag_clearatomic_flag_clear_explicit (C++11)(C++11)
atomic_flag_testatomic_flag_test_explicit (C++20)(C++20)
atomic_flag_waitatomic_flag_wait_explicit (C++20)(C++20)
atomic_flag_notify_one (C++20)
atomic_flag_notify_all (C++20)

[edit]

Defined in header`<atomic>`
template<class T> void atomic_wait(conststd::atomic<T>* object, typenamestd::atomic<T>::value_type old);	(1)	(since C++20)
template<class T> void atomic_wait(constvolatilestd::atomic<T>* object, typenamestd::atomic<T>::value_type old);	(2)	(since C++20)
template<class T> void atomic_wait_explicit(conststd::atomic<T>* object, typenamestd::atomic<T>::value_type old, std::memory_order order);	(3)	(since C++20)
template<class T> void atomic_wait_explicit(constvolatilestd::atomic<T>* object, typenamestd::atomic<T>::value_type old, std::memory_order order);	(4)	(since C++20)

Performs atomic waiting operations. Behaves as if it repeatedly performs the following steps:

Compare thevalue representation ofobject->load() (for overloads(1,2)) orobject->load(order) (for overloads(3,4)) with that ofold.
- If those are bitwise equal, then blocks until*object is notified bystd::atomic::notify_one() orstd::atomic::notify_all(), or the thread is unblocked spuriously.
- Otherwise, returns.

These functions are guaranteed to return only if value has changed, even if the underlying implementation unblocks spuriously.

1,2) Equivalent toobject->wait(old).

3,4) Equivalent toobject->wait(old, order).

Iforder is one ofstd::memory_order::release andstd::memory_order::acq_rel, the behavior is undefined.

[edit]Parameters

object	-	pointer to the atomic object to check and wait on
old	-	the value to check the atomic object no longer contains
order	-	the memory synchronization ordering

[edit]Return value

(none)

[edit]Notes

This form of change-detection is often more efficient than simple polling or pure spinlocks.

Due to theABA problem, transient changes fromold to another value and back toold might be missed, and not unblock.

The comparison is bitwise (similar tostd::memcmp); no comparison operator is used. Padding bits that never participate in an object's value representation are ignored.

[edit]Example

This section is incomplete
Reason: no example

[edit]See also

wait (C++20)	blocks the thread until notified and the atomic value changes (public member function of`std::atomic<T>`)[edit]
notify_one (C++20)	notifies at least one thread waiting on the atomic object (public member function of`std::atomic<T>`)[edit]
notify_all (C++20)	notifies all threads blocked waiting on the atomic object (public member function of`std::atomic<T>`)[edit]
atomic_notify_one (C++20)	notifies a thread blocked in atomic_wait (function template)[edit]
atomic_notify_all (C++20)	notifies all threads blocked in atomic_wait (function template)[edit]