Documentation Home >> Headers >> <condition_variable> Header >> std::condition_variable >> std::condition_variable::wait_until Member function

Wait until the std::condition_variable is notified by a call to notify_one() or notify_all(), or until a specified time has been reached or the thread is woken spuriously.

template<typename Clock,typename Duration>
cv_status wait_until(
    std::unique_lock<std::mutex>& lock,
    std::chrono::time_point<Clock,Duration> const&
    absolute_time);

Preconditions:

lock.owns_lock() is true, and the lock is owned by the calling thread.

Effects:

Atomically unlock the supplied lock object and block until the the thread is woken by a call to notify_one() or notify_all() by another thread, or Clock::now() returns a time equal to or later than absolute_time or the thread is woken spuriously. The lock object is locked again before the call to wait_until() returns.

Returns:

std::cv_status::no_timeout if the thread was woken by a call to notify_one() or notify_all() or a spurious wake-up, std::cv_status::timeout otherwise.

Throws:

std::system_error if the effects cannot be achieved. If the lock object is unlocked during the call to wait_until(), it is locked again on exit, even if the function exits via an exception.

Note:

The spurious wake ups mean that a thread calling wait_until() may wake even though no thread has called notify_one() or notify_all(). It is therefore recommended that the overload of wait_until() that takes a predicate is used in preference where possible. Otherwise, it is recommended that wait_until() be called in a loop which tests the predicate associated with the condition variable. There is no guarantee as to how long the calling thread will be blocked for, only that if the function returns false then Clock::now() returned a time equal to or later than absolute_time at the point at which the thread became unblocked.

Synchronization:

Calls to notify_one(), notify_all(), wait(), wait_for() and wait_until() on a single std::condition_variable instance are serialized. A call to notify_one() or notify_all() will only wake threads that started waiting prior to that call.

Header

#include <condition_variable>

See Also