33 Concurrency support library [thread]

33.7 Condition variables [thread.condition]

33.7.5 Class condition_variable_any [thread.condition.condvarany]

33.7.5.1 General [thread.condition.condvarany.general]

In this subclause [thread.condition.condvarany], template arguments for template parameters named Lock shall meet the Cpp17BasicLockable requirements ([thread.req.lockable.basic]).

[Note 1:

All of the standard mutex types meet this requirement.

If a 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, any necessary synchronization is assumed to be 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; // [thread.condvarany.wait], noninterruptible waits 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); // [thread.condvarany.intwait], interruptible waits template<class Lock, class Predicate> bool wait(Lock& lock, stop_token stoken, Predicate pred); template<class Lock, class Clock, class Duration, class Predicate> bool wait_until(Lock& lock, stop_token stoken, const chrono::time_point<Clock, Duration>& abs_time, Predicate pred); template<class Lock, class Rep, class Period, class Predicate> bool wait_for(Lock& lock, stop_token stoken, const chrono::duration<Rep, Period>& rel_time, Predicate pred); }; }

🔗

condition_variable_any();

Throws: bad_alloc or system_error when an exception is required ([thread.req.exception]).

Error conditions:

(3.1)
resource_unavailable_try_again — if some non-memory resource limitation prevents initialization.
(3.2)
operation_not_permitted — if the thread does not have the privilege to perform the operation.

🔗

~condition_variable_any();

Preconditions: There is no thread blocked on *this.

[Note 2:

That is, all threads have been notified; they can 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 needs to happen before destruction.

Undefined behavior ensues if a thread waits 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]

🔗

void notify_one() noexcept;

Effects: If any threads are blocked waiting for *this, unblocks one of those threads.

🔗

void notify_all() noexcept;

Effects: Unblocks all threads that are blocked waiting for *this.

33.7.5.2 Noninterruptible waits [thread.condvarany.wait]

🔗

template<class Lock>
  void wait(Lock& lock);

Effects:

(1.1)
Atomically calls lock.unlock() and blocks on *this.
(1.2)
When unblocked, calls lock.lock() (possibly blocking on the lock) and returns.
(1.3)
The function will unblock when signaled by a call to notify_one(), a call to notify_all(), or spuriously.

Postconditions: lock is locked by the calling thread.

Throws: Nothing.

Remarks: If the function fails to meet the postcondition, terminate() is invoked ([except.terminate]).

[Note 1:

This can happen if the re-locking of the mutex throws an exception.

— end note]

🔗

template<class Lock, class Predicate>
  void wait(Lock& lock, Predicate pred);

Effects: Equivalent to: 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:

(6.1)
Atomically calls lock.unlock() and blocks on *this.
(6.2)
When unblocked, calls lock.lock() (possibly blocking on the lock) and returns.
(6.3)
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.
(6.4)
If the function exits via an exception, lock.lock() is called prior to exiting the function.

Postconditions: 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: Timeout-related exceptions ([thread.req.timing]).

Remarks: If the function fails to meet the postcondition, terminate() is invoked ([except.terminate]).

[Note 2:

This can happen if the re-locking of the mutex throws an exception.

— end note]

🔗

template<class Lock, class Rep, class Period>
  cv_status wait_for(Lock& lock, const chrono::duration<Rep, Period>& rel_time);

Effects: Equivalent to: return wait_until(lock, chrono::steady_clock::now() + rel_time);

Postconditions: lock is locked by the calling thread.

Returns: cv_status::timeout if the relative timeout ([thread.req.timing]) specified by rel_time expired, otherwise cv_status::no_timeout.

Throws: Timeout-related exceptions ([thread.req.timing]).

Remarks: If the function fails to meet the postcondition, terminate is invoked ([except.terminate]).

[Note 3:

This can happen if the re-locking of the mutex throws an exception.

— end note]

🔗

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: Equivalent to: while (!pred()) if (wait_until(lock, abs_time) == cv_status::timeout) return pred(); return true;

[Note 4:

There is no blocking if pred() is initially true, or if the timeout has already expired.

— end note]

[Note 5:

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: Equivalent to: return wait_until(lock, chrono::steady_clock::now() + rel_time, std::move(pred));

33.7.5.3 Interruptible waits [thread.condvarany.intwait]

The following wait functions will be notified when there is a stop request on the passed stop_token.

In that case the functions return immediately, returning false if the predicate evaluates to false.

🔗

template<class Lock, class Predicate>
  bool wait(Lock& lock, stop_token stoken, Predicate pred);

Effects: Registers for the duration of this call *this to get notified on a stop request on stoken during this call and then equivalent to: while (!stoken.stop_requested()) { if (pred()) return true; wait(lock); } return pred();

[Note 1:

The returned value indicates whether the predicate evaluated to true regardless of whether there was a stop request.

— end note]

Postconditions: lock is locked by the calling thread.

Throws: Any exception thrown by pred.

Remarks: If the function fails to meet the postcondition, terminate is called ([except.terminate]).

[Note 2:

This can happen if the re-locking of the mutex throws an exception.

— end note]

🔗

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

[Note 3:

There is no blocking if pred() is initially true, stoken.stop_requested() was already true or the timeout has already expired.

— end note]

[Note 4:

The returned value indicates whether the predicate evaluated to true regardless of whether the timeout was triggered or a stop request was made.

— end note]

Postconditions: lock is locked by the calling thread.

Throws: Timeout-related exceptions ([thread.req.timing]), or any exception thrown by pred.

Remarks: If the function fails to meet the postcondition, terminate is called ([except.terminate]).

[Note 5:

This can happen if the re-locking of the mutex throws an exception.

— end note]

🔗

template<class Lock, class Rep, class Period, class Predicate>
  bool wait_for(Lock& lock, stop_token stoken,
                const chrono::duration<Rep, Period>& rel_time, Predicate pred);

Effects: Equivalent to: return wait_until(lock, std::move(stoken), chrono::steady_clock::now() + rel_time, std::move(pred));