Condition variables provide synchronization primitives used to block a thread until notified by some other thread that some condition is met or until a system time is reached. Class condition_variable provides a condition variable that can only wait on an object of type unique_lock<mutex>, allowing maximum efficiency on some platforms. Class condition_variable_any provides a general condition variable that can wait on objects of user-supplied lock types.
Condition variables permit concurrent invocation of the wait, wait_for, wait_until, notify_one and notify_all member functions.
The execution of notify_one and notify_all shall be atomic. The execution of wait, wait_for, and wait_until shall be performed in three atomic parts:
the release of the mutex and entry into the waiting state;
the unblocking of the wait; and
the reacquisition of the lock.
The implementation shall behave as if notify_one, notify_all, and each part of the wait, wait_for, and wait_until executions are executed in some unspecified total order.
Condition variable construction and destruction need not be synchronized.
Header condition_variable synopsis
namespace std {
class condition_variable;
class condition_variable_any;
void notify_all_at_thread_exit(condition_variable& cond, unique_lock<mutex> lk);
enum class cv_status { no_timeout, timeout };
}
void notify_all_at_thread_exit(condition_variable& cond, unique_lock<mutex> lk);
Effects: transfers ownership of the lock associated with lk into internal storage and schedules cond to be notified when the current thread exits, after all objects of thread storage duration associated with the current thread have been destroyed. This notification shall be as if
lk.unlock(); cond.notify_all();
Synchronization: The call to notify_all_at_thread_exit and the completion of the destructors for all the current thread's variables of thread storage duration synchronize with ([intro.multithread]) calls to functions waiting on cond.
Note: The supplied lock will be held until the thread exits, and care must be taken to ensure that this does not cause deadlock due to lock ordering issues. After calling notify_all_at_thread_exit it is recommended that the thread should be exited as soon as possible, and that no blocking or time-consuming tasks are run on that thread.
Note: It is the user's responsibility to ensure that waiting threads do not erroneously assume that the thread has finished if they experience spurious wakeups. This typically requires that the condition being waited for is satisfied while holding the lock on lk, and that this lock is not released and reacquired prior to calling notify_all_at_thread_exit.
namespace std {
class condition_variable {
public:
condition_variable();
~condition_variable();
condition_variable(const condition_variable&) = delete;
condition_variable& operator=(const condition_variable&) = delete;
void notify_one() noexcept;
void notify_all() noexcept;
void wait(unique_lock<mutex>& lock);
template <class Predicate>
void wait(unique_lock<mutex>& lock, Predicate pred);
template <class Clock, class Duration>
cv_status wait_until(unique_lock<mutex>& lock,
const chrono::time_point<Clock, Duration>& abs_time);
template <class Clock, class Duration, class Predicate>
bool wait_until(unique_lock<mutex>& lock,
const chrono::time_point<Clock, Duration>& abs_time,
Predicate pred);
template <class Rep, class Period>
cv_status wait_for(unique_lock<mutex>& lock,
const chrono::duration<Rep, Period>& rel_time);
template <class Rep, class Period, class Predicate>
bool wait_for(unique_lock<mutex>& lock,
const chrono::duration<Rep, Period>& rel_time,
Predicate pred);
typedef implementation-defined native_handle_type; // See [thread.req.native]
native_handle_type native_handle(); // See [thread.req.native]
};
}
The class condition_variable shall be a standard-layout class (Clause [class]).
Effects: Constructs an object of type condition_variable.
Throws: system_error when an exception is required ([thread.req.exception]).
Error conditions:
resource_unavailable_try_again — if some non-memory resource limitation prevents initialization.
Requires: There shall be no thread blocked on *this. [ Note: That is, all threads shall have been notified; they may subsequently block on the lock specified in the wait. This relaxes the usual rules, which would have required all wait calls to happen before destruction. Only the notification to unblock the wait must happen before destruction. The user must take care to ensure that no threads wait on *this once the destructor has been started, especially when the waiting threads are calling the wait functions in a loop or using the overloads of wait, wait_for, or wait_until that take a predicate. — end note ]
Effects: Destroys the object.
Effects: If any threads are blocked waiting for *this, unblocks one of those threads.
Effects: Unblocks all threads that are blocked waiting for *this.
void wait(unique_lock<mutex>& lock);
Requires: lock.owns_lock() is true and lock.mutex() is locked by the calling thread, and either
no other thread is waiting on this condition_variable object or
lock.mutex() returns the same value for each of the lock arguments supplied by all concurrently waiting (via wait or timed_wait) threads.
Effects:
Atomically calls lock.unlock() and blocks on *this.
When unblocked, calls lock.lock() (possibly blocking on the lock), then returns.
The function will unblock when signaled by a call to notify_one() or a call to notify_all(), or spuriously.
If the function exits via an exception, lock.lock() shall be called prior to exiting the function scope.
Postcondition: lock.owns_lock() is true and lock.mutex() is locked by the calling thread.
Throws: system_error when an exception is required ([thread.req.exception]).
template <class Predicate>
void wait(unique_lock<mutex>& lock, Predicate pred);
Requires: lock.owns_lock() is true and lock.mutex() is locked by the calling thread, and either
no other thread is waiting on this condition_variable object or
lock.mutex() returns the same value for each of the lock arguments supplied by all concurrently waiting (via wait or timed_wait) threads.
Effects:
while (!pred()) wait(lock);
Postcondition: lock.owns_lock() is true and lock.mutex() is locked by the calling thread.
Throws: std::system_error when an exception is required ([thread.req.exception]).
template <class Clock, class Duration>
cv_status wait_until(unique_lock<mutex>& lock,
const chrono::time_point<Clock, Duration>& abs_time);
Requires: lock.owns_lock() is true and lock.mutex() is locked by the calling thread, and either
no other thread is waiting on this condition_variable object or
lock.mutex() returns the same value for each of the lock arguments supplied by all concurrently waiting (via wait, wait_for, or wait_until) threads.
Effects:
Atomically calls lock.unlock() and blocks on *this.
When unblocked, calls lock.lock() (possibly blocking on the lock), then returns.
The function will unblock when signaled by a call to notify_one(), a call to notify_all(), expiration of the absolute timeout ([thread.req.timing]) specified by abs_time, or spuriously.
If the function exits via an exception, lock.lock() shall be called prior to exiting the function scope.
Postcondition: lock.owns_lock() is true and lock.mutex() is locked by the calling thread.
Returns: cv_status::timeout if the absolute timeout ([thread.req.timing]) specified by abs_time expired, otherwise cv_status::no_timeout.
Throws: system_error when an exception is required ([thread.req.exception]).
template <class Rep, class Period>
cv_status wait_for(unique_lock<mutex>& lock,
const chrono::duration<Rep, Period>& rel_time);
Requires: lock.owns_lock() is true and lock.mutex() is locked by the calling thread, and either
no other thread is waiting on this condition_variable object or
lock.mutex() returns the same value for each of the lock arguments supplied by all concurrently waiting (via wait, wait_for, or wait_until) threads.
Effects: as if
return wait_until(lock, chrono::steady_clock::now() + rel_time);
Returns: cv_status::timeout if the relative timeout ([thread.req.timing]) specified by rel_time expired, otherwise cv_status::no_timeout.
Postcondition: lock.owns_lock() is true and lock.mutex() is locked by the calling thread.
Throws: system_error when an exception is required ([thread.req.exception]).
template <class Clock, class Duration, class Predicate>
bool wait_until(unique_lock<mutex>& lock,
const chrono::time_point<Clock, Duration>& abs_time,
Predicate pred);
Requires: lock.owns_lock() is true and lock.mutex() is locked by the calling thread, and either
no other thread is waiting on this condition_variable object or
lock.mutex() returns the same value for each of the lock arguments supplied by all concurrently waiting (via wait or timed_wait) threads.
Effects:
while (!pred())
if (wait_until(lock, abs_time) == cv_status::timeout)
return pred();
return true;
Returns: pred()
Postcondition: lock.owns_lock() is true and lock.mutex() is locked by the calling thread.
[ Note: The returned value indicates whether the predicate evaluated to true regardless of whether the timeout was triggered. — end note ]
Throws: std::system_error when an exception is required ([thread.req.exception]).
template <class Rep, class Period, class Predicate>
bool wait_for(unique_lock<mutex>& lock,
const chrono::duration<Rep, Period>& rel_time,
Predicate pred);
Requires: lock.owns_lock() is true and lock.mutex() is locked by the calling thread, and either
no other thread is waiting on this condition_variable object or
lock.mutex() returns the same value for each of the lock arguments supplied by all concurrently waiting (via wait, wait_for, or wait_until) threads.
Effects: as if
return wait_until(lock, chrono::steady_clock::now() + rel_time, std::move(pred));
[ Note: There is no blocking if pred() is initially true, even if the timeout has already expired. — end note ]
Postcondition: lock.owns_lock() is true and lock.mutex() is locked by the calling thread.
Returns: pred()
[ Note: The returned value indicates whether the predicate evaluates to true regardless of whether the timeout was triggered. — end note ]
Throws: system_error when an exception is required ([thread.req.exception]).
A Lock type shall meet the BasicLockable requirements ([thread.req.lockable.basic]). [ Note: All of the standard mutex types meet this requirement. If a Lock type other than one of the standard mutex types or a unique_lock wrapper for a standard mutex type is used with condition_variable_any, the user must ensure that any necessary synchronization is in place with respect to the predicate associated with the condition_variable_any instance. — end note ]
namespace std {
class condition_variable_any {
public:
condition_variable_any();
~condition_variable_any();
condition_variable_any(const condition_variable_any&) = delete;
condition_variable_any& operator=(const condition_variable_any&) = delete;
void notify_one() noexcept;
void notify_all() noexcept;
template <class Lock>
void wait(Lock& lock);
template <class Lock, class Predicate>
void wait(Lock& lock, Predicate pred);
template <class Lock, class Clock, class Duration>
cv_status wait_until(Lock& lock, const chrono::time_point<Clock, Duration>& abs_time);
template <class Lock, class Clock, class Duration, class Predicate>
bool wait_until(Lock& lock, const chrono::time_point<Clock, Duration>& abs_time,
Predicate pred);
template <class Lock, class Rep, class Period>
cv_status wait_for(Lock& lock, const chrono::duration<Rep, Period>& rel_time);
template <class Lock, class Rep, class Period, class Predicate>
bool wait_for(Lock& lock, const chrono::duration<Rep, Period>& rel_time,
Predicate pred);
};
}
Effects: Constructs an object of type condition_variable_any.
Throws: bad_alloc or system_error when an exception is required ([thread.req.exception]).
Requires: There shall be no thread blocked on *this. [ Note: That is, all threads shall have been notified; they may subsequently block on the lock specified in the wait. This relaxes the usual rules, which would have required all wait calls to happen before destruction. Only the notification to unblock the wait must happen before destruction. The user must take care to ensure that no threads wait on *this once the destructor has been started, especially when the waiting threads are calling the wait functions in a loop or using the overloads of wait, wait_for, or wait_until that take a predicate. — end note ]
Effects: Destroys the object.
Effects: If any threads are blocked waiting for *this, unblocks one of those threads.
Effects: Unblocks all threads that are blocked waiting for *this.
template <class Lock>
void wait(Lock& lock);
Note: if any of the wait functions exits via an exception, it is unspecified whether the Lock is held. One can use a Lock type that allows to query that, such as the unique_lock wrapper.
Effects:
Atomically calls lock.unlock() and blocks on *this.
When unblocked, calls lock.lock() (possibly blocking on the lock) and returns.
The function will unblock when signaled by a call to notify_one(), a call to notify_all(), or spuriously.
If the function exits via an exception, lock.lock() shall be called prior to exiting the function scope.
Postcondition: lock is locked by the calling thread.
Throws: system_error when an exception is required ([thread.req.exception]).
template <class Lock, class Predicate>
void wait(Lock& lock, Predicate pred);
Effects:
while (!pred()) wait(lock);
template <class Lock, class Clock, class Duration>
cv_status wait_until(Lock& lock, const chrono::time_point<Clock, Duration>& abs_time);
Effects:
Atomically calls lock.unlock() and blocks on *this.
When unblocked, calls lock.lock() (possibly blocking on the lock) and returns.
The function will unblock when signaled by a call to notify_one(), a call to notify_all(), expiration of the absolute timeout ([thread.req.timing]) specified by abs_time, or spuriously.
If the function exits via an exception, lock.lock() shall be called prior to exiting the function scope.
Postcondition: lock is locked by the calling thread.
Returns: cv_status::timeout if the absolute timeout ([thread.req.timing]) specified by abs_time expired, otherwise cv_status::no_timeout.
Throws: system_error when an exception is required ([thread.req.exception]).
template <class Lock, class Rep, class Period>
cv_status wait_for(Lock& lock, const chrono::duration<Rep, Period>& rel_time);
Effects: as if
return wait_until(lock, chrono::steady_clock::now() + rel_time);
Returns: cv_status::timeout if the relative timeout ([thread.req.timing]) specified by rel_time expired, otherwise cv_status::no_timeout.
Postcondition: lock is locked by the calling thread.
Throws: system_error when an exception is required ([thread.req.exception]).
template <class Lock, class Clock, class Duration, class Predicate>
bool wait_until(Lock& lock, const chrono::time_point<Clock, Duration>& abs_time, Predicate pred);
Effects:
while (!pred())
if (wait_until(lock, abs_time) == cv_status::timeout)
return pred();
return true;
Returns: pred()
[ Note: The returned value indicates whether the predicate evaluates to true regardless of whether the timeout was triggered. — end note ]
template <class Lock, class Rep, class Period, class Predicate>
bool wait_for(Lock& lock, const chrono::duration<Rep, Period>& rel_time, Predicate pred);
Effects: as if
return wait_until(lock, chrono::steady_clock::now() + rel_time, std::move(pred));
[ Note: There is no blocking if pred() is initially true, even if the timeout has already expired. — end note ]
Postcondition: lock is locked by the calling thread.
Returns: pred()
[ Note: The returned value indicates whether the predicate evaluates to true regardless of whether the timeout was triggered. — end note ]
Throws: system_error when an exception is required ([thread.req.exception]).