std::condition_variable_any::wait_until

template< class Lock, class Clock, class Duration >
std::cv_status 
    wait_until( Lock& lock,
                const std::chrono::time_point<Clock, Duration>& timeout_time );

template< class Lock, class Clock, class Duration, class Predicate >
bool wait_until( Lock& lock,
                 const std::chrono::time_point<Clock, Duration>& timeout_time,
                 Predicate stop_waiting );

template< class Lock, class Clock, class Duration, class Predicate >
bool wait_until( Lock& lock,
                 std::stop_token stoken,
                 const std::chrono::time_point<Clock, Duration>& timeout_time,
                 Predicate stop_waiting );

wait_until causes the current thread to block until the condition variable is notified, a specific time is reached, or a spurious wakeup occurs, optionally looping until some predicate is satisfied (bool(stop_waiting()) == true).

while (!stop_waiting()) {
    if (wait_until(lock, timeout_time) == std::cv_status::timeout) {
        return stop_waiting();
    }
}
return true;

while (!stoken.stop_requested()) {
    if (stop_waiting())
        return true;
    if (wait_until(lock, timeout_time) == std::cv_status::timeout)
        return stop_waiting();
}
return stop_waiting();

If these functions fail to meet the postcondition (lock is locked by the calling thread), std::terminate is called. For example, this could happen if relocking the mutex throws an exception.

Clock must meet the Clock requirements. The program is ill-formed if std::chrono::is_clock_v<Clock> is false. (since C++20).

Parameters

Return value

Exceptions

Notes

The standard recommends that the clock tied to timeout_time be used to measure time; that clock is not required to be a monotonic clock. There are no guarantees regarding the behavior of this function if the clock is adjusted discontinuously, but the existing implementations convert timeout_time from Clock to std::chrono::system_clock and delegate to POSIX pthread_cond_timedwait so that the wait honors adjustments to the system clock, but not to the user-provided Clock. In any case, the function also may wait for longer than until after timeout_time has been reached due to scheduling or resource contention delays.

Even if the clock in use is std::chrono::steady_clock or another monotonic clock, a system clock adjustment may induce a spurious wakeup.

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 <iostream>
#include <atomic>
#include <condition_variable>
#include <thread>
#include <chrono>
using namespace std::chrono_literals;
 
std::condition_variable cv;
std::mutex cv_m;
std::atomic<int> i{0};
 
void waits(int idx)
{
    std::unique_lock<std::mutex> lk(cv_m);
    auto now = std::chrono::system_clock::now();
    if(cv.wait_until(lk, now + idx*100ms, [](){return i == 1;}))
        std::cerr << "Thread " << idx << " finished waiting. i == " << i << '\n';
    else
        std::cerr << "Thread " << idx << " timed out. i == " << i << '\n';
}
 
void signals()
{
    std::this_thread::sleep_for(120ms);
    std::cerr << "Notifying...\n";
    cv.notify_all();
    std::this_thread::sleep_for(100ms);
    i = 1;
    std::cerr << "Notifying again...\n";
    cv.notify_all();
}
 
int main()
{
    std::thread t1(waits, 1), t2(waits, 2), t3(waits, 3), t4(signals);
    t1.join(); 
    t2.join();
    t3.join();
    t4.join();
}

Thread 1 timed out. i == 0
Notifying...
Thread 2 timed out. i == 0
Notifying again...
Thread 3 finished waiting. i == 1

Defect reports

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

See also