std::condition_variable:: wait_for

wait_for causes the current thread to block until the condition variable is notified, the given duration has been elapsed, or a spurious wakeup occurs. pred can be optionally provided to detect spurious wakeup.

Right after wait_for returns, lock. owns_lock ( ) is true , and lock. mutex ( ) is locked by the calling thread. If these postconditions cannot be satisfied ^[1] , calls std::terminate .

If any of the following conditions is satisfied, the behavior is undefined:

• lock. owns_lock ( ) is false .
• lock. mutex ( ) is not locked by the calling thread.
• If some other threads are also waiting on * this , lock. mutex ( ) is different from the mutex unlocked by the waiting functions ( wait , wait_for and wait_until ) called on * this by those threads.

1. ↑ This can happen if the re-locking of the mutex throws an exception.

Parameters

Return value

Exceptions

Notes

Even if notified under lock, overload (1) makes no guarantees about the state of the associated predicate when returning due to timeout.

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.

Example

#include <chrono>
#include <condition_variable>
#include <iostream>
#include <thread>
 
std::condition_variable cv;
std::mutex cv_m; // This mutex is used for three purposes:
                 // 1) to synchronize accesses to i
                 // 2) to synchronize accesses to std::cerr
                 // 3) for the condition variable cv
int i = 0;
 
void waits()
{
    std::unique_lock<std::mutex> lk(cv_m);
    std::cerr << "Waiting... \n";
    cv.wait(lk, []{ return i == 1; });
    std::cerr << "...finished waiting. i == 1\n";
}
 
void signals()
{
    std::this_thread::sleep_for(std::chrono::seconds(1));
    {
        std::lock_guard<std::mutex> lk(cv_m);
        std::cerr << "Notifying...\n";
    }
    cv.notify_all();
 
    std::this_thread::sleep_for(std::chrono::seconds(1));
 
    {
        std::lock_guard<std::mutex> lk(cv_m);
        i = 1;
        std::cerr << "Notifying again...\n";
    }
    cv.notify_all();
}
 
int main()
{
    std::thread t1(waits), t2(waits), t3(waits), t4(signals);
    t1.join(); 
    t2.join(); 
    t3.join();
    t4.join();
}

Waiting...
Waiting...
Waiting...
Notifying...
Notifying again...
...finished waiting. i == 1
...finished waiting. i == 1
...finished waiting. i == 1

Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

See also