30 Thread support library [thread]

30.5 Condition variables [thread.condition]

30.5.3 Class condition_­variable [thread.condition.condvar]

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);

    using native_handle_type = implementation-defined;          // see [thread.req.native]
    native_handle_type native_handle();                         // see [thread.req.native]
  };
}
1
#
The class condition_­variable shall be a standard-layout class ([class]).
🔗
condition_variable();
2
#
Effects: Constructs an object of type condition_­variable.
3
#
Throws: system_­error when an exception is required ([thread.req.exception]).
4
#
Error conditions:
  • (4.1)
    resource_­unavailable_­try_­again — if some non-memory resource limitation prevents initialization.
🔗
~condition_variable();
5
#
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 needs to happen before destruction.
The user should 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
 ]
6
#
Effects: Destroys the object.
🔗
void notify_one() noexcept;
7
#
Effects: If any threads are blocked waiting for *this, unblocks one of those threads.
🔗
void notify_all() noexcept;
8
#
Effects: Unblocks all threads that are blocked waiting for *this.
🔗
void wait(unique_lock<mutex>& lock);
9
#
Requires: lock.owns_­lock() is true and lock.mutex() is locked by the calling thread, and either
  • (9.1)
    no other thread is waiting on this condition_­variable object or
  • (9.2)
    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.
10
#
Effects:
  • (10.1)
    Atomically calls lock.unlock() and blocks on *this.
  • (10.2)
    When unblocked, calls lock.lock() (possibly blocking on the lock), then returns.
  • (10.3)
    The function will unblock when signaled by a call to notify_­one() or a call to notify_­all(), or spuriously.
11
#
Remarks: If the function fails to meet the postcondition, terminate() shall be called ([except.terminate]).
[ Note
:
This can happen if the re-locking of the mutex throws an exception.
— end note
 ]
12
#
Ensures: lock.owns_­lock() is true and lock.mutex() is locked by the calling thread.
13
#
Throws: Nothing.
🔗
template<class Predicate> void wait(unique_lock<mutex>& lock, Predicate pred);
14
#
Requires: lock.owns_­lock() is true and lock.mutex() is locked by the calling thread, and either
  • (14.1)
    no other thread is waiting on this condition_­variable object or
  • (14.2)
    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.
15
#
Effects: Equivalent to: 
while (!pred())
  wait(lock);
16
#
Remarks: If the function fails to meet the postcondition, terminate() shall be called ([except.terminate]).
[ Note
:
This can happen if the re-locking of the mutex throws an exception.
— end note
 ]
17
#
Ensures: lock.owns_­lock() is true and lock.mutex() is locked by the calling thread.
18
#
Throws: Any exception thrown by pred.
🔗
template<class Clock, class Duration> cv_status wait_until(unique_lock<mutex>& lock, const chrono::time_point<Clock, Duration>& abs_time);
19
#
Requires: lock.owns_­lock() is true and lock.mutex() is locked by the calling thread, and either
  • (19.1)
    no other thread is waiting on this condition_­variable object or
  • (19.2)
    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.
20
#
Effects:
  • (20.1)
    Atomically calls lock.unlock() and blocks on *this.
  • (20.2)
    When unblocked, calls lock.lock() (possibly blocking on the lock), then returns.
  • (20.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.
  • (20.4)
    If the function exits via an exception, lock.lock() shall be called prior to exiting the function.
21
#
Remarks: If the function fails to meet the postcondition, terminate() shall be called ([except.terminate]).
[ Note
:
This can happen if the re-locking of the mutex throws an exception.
— end note
 ]
22
#
Ensures: lock.owns_­lock() is true and lock.mutex() is locked by the calling thread.
23
#
Returns: cv_­status​::​timeout if the absolute timeout ([thread.req.timing]) specified by abs_­time expired, otherwise cv_­status​::​no_­timeout.
24
#
Throws: Timeout-related exceptions ([thread.req.timing]).
🔗
template<class Rep, class Period> cv_status wait_for(unique_lock<mutex>& lock, const chrono::duration<Rep, Period>& rel_time);
25
#
Requires: lock.owns_­lock() is true and lock.mutex() is locked by the calling thread, and either
  • (25.1)
    no other thread is waiting on this condition_­variable object or
  • (25.2)
    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.
26
#
Effects: Equivalent to: 
return wait_until(lock, chrono::steady_clock::now() + rel_time);
27
#
Returns: cv_­status​::​timeout if the relative timeout ([thread.req.timing]) specified by rel_­time expired, otherwise cv_­status​::​no_­timeout.
28
#
Remarks: If the function fails to meet the postcondition, terminate() shall be called ([except.terminate]).
[ Note
:
This can happen if the re-locking of the mutex throws an exception.
— end note
 ]
29
#
Ensures: lock.owns_­lock() is true and lock.mutex() is locked by the calling thread.
30
#
Throws: Timeout-related exceptions ([thread.req.timing]).
🔗
template<class Clock, class Duration, class Predicate> bool wait_until(unique_lock<mutex>& lock, const chrono::time_point<Clock, Duration>& abs_time, Predicate pred);
31
#
Requires: lock.owns_­lock() is true and lock.mutex() is locked by the calling thread, and either
  • (31.1)
    no other thread is waiting on this condition_­variable object or
  • (31.2)
    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.
32
#
Effects: Equivalent to: 
while (!pred())
  if (wait_until(lock, abs_time) == cv_status::timeout)
    return pred();
return true;
33
#
Remarks: If the function fails to meet the postcondition, terminate() shall be called ([except.terminate]).
[ Note
:
This can happen if the re-locking of the mutex throws an exception.
— end note
 ]
34
#
Ensures: lock.owns_­lock() is true and lock.mutex() is locked by the calling thread.
35
#
[ Note
:
The returned value indicates whether the predicate evaluated to true regardless of whether the timeout was triggered.
— end note
 ]
36
#
Throws: Timeout-related exceptions ([thread.req.timing]) or any exception thrown by pred.
🔗
template<class Rep, class Period, class Predicate> bool wait_for(unique_lock<mutex>& lock, const chrono::duration<Rep, Period>& rel_time, Predicate pred);
37
#
Requires: lock.owns_­lock() is true and lock.mutex() is locked by the calling thread, and either
  • (37.1)
    no other thread is waiting on this condition_­variable object or
  • (37.2)
    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.
38
#
Effects: Equivalent to: 
return wait_until(lock, chrono::steady_clock::now() + rel_time, std::move(pred));
39
#
[ Note
:
There is no blocking if pred() is initially true, even if the timeout has already expired.
— end note
 ]
40
#
Remarks: If the function fails to meet the postcondition, terminate() shall be called ([except.terminate]).
[ Note
:
This can happen if the re-locking of the mutex throws an exception.
— end note
 ]
41
#
Ensures: lock.owns_­lock() is true and lock.mutex() is locked by the calling thread.
42
#
[ Note
:
The returned value indicates whether the predicate evaluates to true regardless of whether the timeout was triggered.
— end note
 ]
43
#
Throws: Timeout-related exceptions ([thread.req.timing]) or any exception thrown by pred.