# std::atomic_wait, std::atomic_wait_explicit

> C++ Atlas: `cppatlas.com/w/cpp/atomic/atomic_wait` | Source: https://en.cppreference.com/w/cpp/atomic/atomic_wait | Domain: atomic | Standards: C++20

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

## Official Specification Summary (cppreference)

```cpp
// Defined in header <atomic>

template< class T >
void atomic_wait( const std::atomic<T>* object,
                  typename std::atomic<T>::value_type old ); // (1) (since C++20)

template< class T >
void atomic_wait( const volatile std::atomic<T>* object,
                  typename std::atomic<T>::value_type old ); // (2) (since C++20)

template< class T >
void atomic_wait_explicit( const std::atomic<T>* object,
                           typename std::atomic<T>::value_type old,
                           std::memory_order order ); // (3) (since C++20)

template< class T >
void atomic_wait_explicit( const volatile std::atomic<T>* object,
                           typename std::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 the value representation of `object->load()` (for overloads (1,2)) or `object->load(order)` (for overloads (3,4)) with that of `old`.
  - If those are bitwise equal, then blocks until `*object` is notified by `std::atomic::notify_one()` or `std::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 to `object->wait(old)`.

3,4) Equivalent to `object->wait(old, order)`.

If `order` is one of `std::memory_order::release` and `std::memory_order::acq_rel`, the behavior is undefined.

### 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

### Return value

(none)

### Notes

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

Due to the ABA problem, transient changes from `old` to another value and back to `old` might be missed, and not unblock.

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

### Example

> Note: This section is incomplete Reason: no example

### See also

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

---
Attribution: content from https://en.cppreference.com/w/cpp/atomic/atomic_wait (cppreference.com), licensed under CC-BY-SA 3.0 and GFDL. Modified: converted to markdown, study notes added. Offline snapshot of 9 February 2025.