std::condition_variable::notify_one

 

C++

Language

Standard library headers

Concepts

Utilities library

Strings library

Containers library

Algorithms library

Iterators library

Numerics library

Input/output library

Localizations library

Regular expressions library (C++11)

Atomic operations library (C++11)

Thread support library (C++11)

Technical Specifications

 

Thread support library

Threads
thread (C++11)
this_thread namespace
get_id (C++11) yield (C++11)	sleep_for (C++11) sleep_until (C++11)
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_guard (C++11) unique_lock (C++11) shared_lock (C++14) defer_lock_ttry_to_lock_tadopt_lock_t (C++11)(C++11)(C++11)	lock (C++11) try_lock (C++11) defer_locktry_to_lockadopt_lock (C++11)(C++11)(C++11) once_flag (C++11) call_once (C++11)
Condition variables
condition_variable (C++11)
condition_variable_any (C++11)
notify_all_at_thread_exit (C++11)
cv_status (C++11)
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)

 

std::condition_variable

Member functions

condition_variable::condition_variable

condition_variable::~condition_variable

Notification

condition_variable::notify_one

condition_variable::notify_all

Waiting

condition_variable::wait

condition_variable::wait_for

condition_variable::wait_until

Native handle

condition_variable::native handle

 

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

If any threads are waiting on *this, calling notify_one unblocks one of the waiting threads.

Parameters

(none)

Return value

(none)

Exceptions

noexcept specification:  

noexcept

  

Notes

The effects of notify_one()/notify_all() and wait()/wait_for()/wait_until() take place in a single total order, so it's 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.

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

Example

Run this code

#include <iostream>
#include <condition_variable>
#include <thread>
#include <chrono>
 
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 == 1\n";
    done = true;
}
 
void signals()
{
    std::this_thread::sleep_for(std::chrono::seconds(1));
    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(std::chrono::seconds(1));
        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

notify_all

notifies all waiting threads (public member function)