std::condit...::notify_one(3)

💅 std::condition_variable::notify_one(3) 💅

okay bestie, welcome to the std::condition_variable::notify_one page from the C++ Standard Libary manual. This is the vibe: condition variable, notify call, and a bunch of thread girlies waiting for their moment. ✨

---

💖 NAME 💖

std::condition_variable::notify_one — std::condition_variable::notify_one. That’s the name, bestie. It said itself twice and honestly? It ate. 💅

---

✨ Synopsis ✨

Here’s the signature, no cap:

void notify_one() noexcept;  (since C++11)

Since C++11, bestie. And here’s the actual behavior: if any threads are waiting on *this, calling notify_one unblocks one of the waiting threads. One. Not all — that’s notify_all’s whole thing, see below. 🫶

---

🎀 Parameters 🎀

(none) — literally no parameters. It’s giving self-care: the condition variable does all the work. 💅

---

🌸 Return value 🌸

(none) — nothing comes back. No return value, no drama, just vibes. 🎀

---

🦋 Notes 🦋

okay so this part is the main character lore, and it’s important.

The effects of notify_one()/notify_all() and each of the three atomic parts of wait()/wait_for()/wait_until() (unlock+wait, wakeup, and lock) take place in a single total order that can be viewed as modification order of an atomic variable: the order is specific to this individual condition variable. This makes it impossible for notify_one() to, for example, be delayed and unblock a thread that started waiting just after the call to notify_one() was made. Periodt. 🌈

The notifying thread does not need to hold the lock on the same mutex as the one held by the waiting thread(s); in fact doing so is a pessimization, since the notified thread would immediately block again, waiting for the notifying thread to release the lock. Lowkey a trap. However, some implementations (in particular many implementations of pthreads) recognize this situation and avoid this "hurry up and wait" scenario by transferring the waiting thread from the condition variable's queue directly to the queue of the mutex within the notify call, without waking it up. Iconic behavior, honestly. 👑

Notifying while under the lock may nevertheless be necessary when precise scheduling of events is required, e.g. if the waiting thread would exit the program if the condition is satisfied, causing destruction of the notifying thread's condition variable. A spurious wakeup after mutex unlock but before notify would result in notify called on a destroyed object. So yeah — this is the dangerous little corner, bestie. Do not play with destroyed objects. 💀

---

🔥 Example 🔥

// Run this code — fr fr, run it 👇

#include <chrono>
#include <condition_variable>
#include <iostream>
#include <thread>
using namespace std::chrono_literals;

std::condition_variable cv;
std::mutex cv_m;
int i = 0;
bool done = false;

void waits()
{
    std::unique_lock<std::mutex> lk(cv_m);
    std::cout << "Waiting... \n";
    cv.wait(lk, []{ return i == 1; });
    std::cout << "...finished waiting; i == " << i << '\n';
    done = true;
}

void signals()
{
    std::this_thread::sleep_for(200ms);
    std::cout << "Notifying falsely...\n";
    cv.notify_one(); // waiting thread is notified with i == 0.
                     // cv.wait wakes up, checks i, and goes back to waiting

    std::unique_lock<std::mutex> lk(cv_m);
    i = 1;
    while (!done)
    {
        std::cout << "Notifying true change...\n";
        lk.unlock();
        cv.notify_one(); // waiting thread is notified with i == 1, cv.wait returns
        std::this_thread::sleep_for(300ms);
        lk.lock();
    }
}

int main()
{
    std::thread t1(waits), t2(signals);
    t1.join();
    t2.join();
}

👀 Possible output 👀

Waiting...
Notifying falsely...
Notifying true change...
...finished waiting; i == 1

---

💖 See also 💖

Go look at these too, bestie:

• notify_all — notifies all waiting threads (public member function). It’s the group-chat announcement to notify_one’s private DM. 💌
• C documentation for cnd_signal — yes, the C cousin. 🌀

---

🫶 Hidden category 🫶

• Pages with unreviewed LWG DR marker — it’s literally the hidden category, no cap. 🙈

---

okay that’s the whole page, bestie! 🫶 Source/version: http://cppreference.com. Date: 2024.06.10. Page: std::condit...::notify_one(3). mwah 💋✨