std::atomic...it_explicit(3)

💖 NAME 💖

Welcome to the std::atomic...it_explicit(3) page from the C++ Standard Libary manual (yes, that spelling is literally in the header, not my typo 💀). This whole vibe is about std::atomic_flag_wait and std::atomic_flag_wait_explicit, bestie.

✨ Synopsis ✨

First, the header tea:

Defined in header <atomic>

Then the overloads, all since C++20:

• (1) (since C++20)

void atomic_flag_wait( const atomic_flag* object, bool old ) noexcept;

• (2) (since C++20)

void atomic_flag_wait( const volatile atomic_flag* object, bool old ) noexcept;

• (3) (since C++20)

void atomic_flag_wait_explicit( const atomic_flag* object, bool old, std::memory_order order ) noexcept;

• (4) (since C++20)

void atomic_flag_wait_explicit( const volatile atomic_flag* object, bool old, std::memory_order order ) noexcept;

These perform atomic waiting operations. No cap.

Here's the actual mechanic: it compares object->test(std::memory_order_seq_cst) or object->test(order) with old, and if they are equal then it blocks until *object is notified by std::atomic_flag::notify_one() or std::atomic_flag::notify_all() (or the thread is unblocked spuriously). This is repeated until the values compare unequal. The way that loop just keeps checking? Iconic.

• 1,2) the memory synchronization order is std::memory_order_seq_cst.
• 3,4) the memory synchronization order is order.

If order is one of std::memory_order_release and std::memory_order_acq_rel, the behavior is undefined. So do not do that, bestie. It's giving UB 💀.

These functions are guaranteed to return only if value has changed, even if underlying implementation unblocks spuriously. Slay for correctness ✨.

🎀 Parameters 🎀

• object — pointer to the atomic flag to check and wait on.
• old — the value to check the atomic flag no longer contains.
• order — the memory synchronization ordering.

🫶 Return value 🫶

(none) — literally nothing comes back, bestie. It's a void function moment.

🌸 Notes 🌸

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

ABA problem warning: due to the ABA problem, transient changes from old to another value and back to old might be missed, and not unblock. So yeah, it can get ghosted by a sneaky ABA cycle 😭.

🦋 Example 🦋

This section is incomplete.

Reason: no example.

👑 See also 👑

• notify_one — notifies at least one thread waiting on the atomic object (C++20) (public member function of std::atomic_flag).
• notify_all — notifies all threads blocked waiting on the atomic object (C++20) (public member function of std::atomic_flag).
• atomic_flag_notify_one — notifies a thread blocked in atomic_flag_wait (C++20) (function).
• atomic_flag_notify_all — notifies all threads blocked in atomic_flag_wait (C++20) (function).

💀 Category 💀

• * Todo no example

---

Sign-off szn 🌈: source/version http://cppreference.com, date 2024.06.10, page std::atomic...it_explicit(3). Love u, bye bestie 💖