public member function
template <class Clock, class Duration> cv_status wait_until (unique_lock<mutex>& lck, const chrono::time_point<Clock,Duration>& abs_time);
template <class Clock, class Duration, class Predicate> bool wait_until (unique_lock<mutex>& lck, const chrono::time_point<Clock,Duration>& abs_time, Predicate pred);
Wait until notified or time point
The execution of the current thread (which shall have locked lck's mutex) is blocked either until notified or until abs_time, whichever happens first.
At the moment of blocking the thread, the function automatically calls
lck.unlock(), allowing other locked threads to continue.
Once notified or once it is abs_time, the function unblocks and calls
lck.lock(), leaving lck in the same state as when the function was called. Then the function returns (notice that this last mutex locking may block again the thread before returning).
Generally, the function is notified to wake up by a call in another thread either to member notify_one or to member notify_all. But certain implementations may produce spurious wake-up calls without any of these functions being called. Therefore, users of this function shall ensure their condition for resumption is met.
If pred is specified (2), the function only blocks if pred returns
false, and notifications can only unblock the thread when it becomes
true (which is especially useful to check against spurious wake-up calls). It behaves as if implemented as:
if ( wait_until(lck,abs_time) == cv_status::timeout)
- A unique_lock object whose mutex object is currently locked by this thread.
All concurrent calls to wait member functions of this object shall use the same underlying mutex object (as returned by
- A point in time at which the thread will stop blocking, allowing the function to return.
time_point is an object that represents a specific absolute time.
- A callable object or function that takes no arguments and returns a value that can be evaluated as a
This is called repeatedly until it evaluates to
The unconditional version (1) returns cv_status::timeout if the function returns because abs_time has been reached, or cv_status::no_timeout otherwise.
The predicate version (2) returns
pred(), regardless of whether the timeout was triggered (although it can only be
false if triggered).
The function performs three atomic operations:
Atomic operations on the object are ordered according to a single total order, with the three atomic operations in this function happening in the same relative as above.
- The initial unlocking of lck and simultaneous entry into the waiting state.
- The unblocking of the waiting state.
- The locking of lck before returning.
If any parameter has a value that is not valid for this function (such as if lck's mutex object is not locked by the calling thread), it causes undefined behavior.
Otherwise, if an exception is thrown, both the
condition_variable object and the arguments are in a valid state (basic guarantee).
It may throw system_error
in case of failure (transmitting any error condition from the respective call to lock
The predicate version (2)
may also throw any exception thrown by pred
On exception, the state of lck
is attempted to be restored before exiting the function scope (by calling
It may throw if an operation related to abs_time
throws (note that operations on the standard clock
types provided in
The predicate version (2)
may also throw exceptions thrown by pred
If the function is not able to restore the lock and return at some point (such as if some attempt to lock or unlock throws), std::terminate