std::condition_variable::wait_until
template< class Clock, class Duration > std::cv_status |
(1) | (since C++11) |
template< class Clock, class Duration, class Predicate > bool wait_until( std::unique_lock<std::mutex>& lock, |
(2) | (since C++11) |
wait_until
causes the current thread to block until the condition variable is notified, the given time point has been reached, or a spurious wakeup occurs. pred can be optionally provided to detect spurious wakeup.
if (wait_until(lock, abs_time) == std::cv_status::timeout)
return pred();
return true;.
Right after wait_until
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.
- ↑ This can happen if the re-locking of the mutex throws an exception.
Contents |
[edit] Parameters
lock | - | an lock which must be locked by the calling thread |
abs_time | - | the time point where waiting expires |
pred | - | the predicate to check whether the waiting can be completed |
Type requirements | ||
-Predicate must meet the requirements of FunctionObject.
| ||
-pred() must be a valid expression, and its type and value category must meet the BooleanTestable requirements. |
[edit] Return value
[edit] Exceptions
[edit] Notes
The standard recommends that the clock tied to abs_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 abs_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 abs_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.
[edit] 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(); }
Possible output:
Waiting... Waiting... Waiting... Notifying... Notifying again... ...finished waiting. i == 1 ...finished waiting. i == 1 ...finished waiting. i == 1
[edit] Defect reports
The following behavior-changing defect reports were applied retroactively to previously published C++ standards.
DR | Applied to | Behavior as published | Correct behavior |
---|---|---|---|
LWG 2093 | C++11 | timeout-related exceptions were missing in the specification | mentions these exceptions |
LWG 2114 (P2167R3) |
C++11 | convertibility to bool was too weak to reflect the expectation of implementations | requirements strengthened |
LWG 2135 | C++11 | the behavior was unclear if lock.lock() throws an exception | calls std::terminate in this case |
[edit] See also
blocks the current thread until the condition variable is awakened (public member function) | |
blocks the current thread until the condition variable is awakened or after the specified timeout duration (public member function) |