condition_variable Class
The latest version of this topic can be found at condition_variable Class.
Use the condition_variable class to wait for an event when you have a mutex of type unique_lock<mutex>. Objects of this type may have better performance than objects of type condition_variable_any<unique_lock<mutex>>.
Syntax
class condition_variable;
Members
Public Constructors
| Name | Description |
|---|---|
| condition_variable::condition_variable Constructor | Constructs a condition_variable object. |
Public Methods
| Name | Description |
|---|---|
| condition_variable::native_handle Method | Returns the implementation-specific type representing the condition_variable handle. |
| condition_variable::notify_all Method | Unblocks all threads that are waiting for the condition_variable object. |
| condition_variable::notify_one Method | Unblocks one of the threads that are waiting for the condition_variable object. |
| condition_variable::wait Method | Blocks a thread. |
| condition_variable::wait_for Method | Blocks a thread, and sets a time interval after which the thread unblocks. |
| condition_variable::wait_until Method | Blocks a thread, and sets a maximum point in time at which the thread unblocks. |
Requirements
Header: condition_variable
Namespace: std
condition_variable::condition_variable Constructor
Constructs a condition_variable object.
condition_variable();
Remarks
If not enough memory is available, the constructor throws a system_error object that has a not_enough_memory error code. If the object cannot be constructed because some other resource is not available, the constructor throws a system_error object that has a resource_unavailable_try_again error code.
condition_variable::native_handle Method
Returns the implementation-specific type that represents the condition_variable handle.
native_handle_type native_handle();
Return Value
native_handle_type is defined as a pointer to Concurrency Runtime internal data structures.
condition_variable::notify_all Method
Unblocks all threads that are waiting for the condition_variable object.
void notify_all() noexcept;
condition_variable::notify_one Method
Unblocks one of the threads that are waiting on the condition_variable object.
void notify_one() noexcept;
condition_variable::wait Method
Blocks a thread.
void wait(
unique_lock<mutex>& Lck);
template <class Predicate>
void wait(
unique_lock<mutex>& Lck,
Predicate Pred);
Parameters
Lck
A unique_lock<mutex> object.
Pred
Any expression that returns true or false.
Remarks
The first method blocks until the condition_variable object is signaled by a call to notify_one or notify_all. It can also wake up spuriously.
In effect, the second method executes the following code.
while(!Pred())
wait(Lck);
condition_variable::wait_for Method
Blocks a thread, and sets a time interval after which the thread unblocks.
template <class Rep, class Period>
cv_status wait_for(
unique_lock<mutex>& Lck,
const chrono::duration<Rep, Period>& Rel_time);
template <class Rep, class Period, class Predicate>
bool wait_for(
unique_lock<mutex>& Lck,
const chrono::duration<Rep, Period>& Rel_time, Predicate Pred);
Parameters
Lck
A unique_lock<mutex> object.
Rel_time
A chrono::duration object that specifies the amount of time before the thread wakes up.
Pred
Any expression that returns true or false.
Return Value
The first method returns cv_status::timeout if the wait terminates when Rel_time has elapsed. Otherwise, the method returns cv_status::no_timeout.
The second method returns the value of Pred.
Remarks
The first method blocks until the condition_variable object is signaled by a call to notify_one or notify_all or until the time interval Rel_time has elapsed. It can also wake up spuriously.
In effect, the second method executes the following code.
while(!Pred())
if(wait_for(Lck, Rel_time) == cv_status::timeout)
return Pred();
return true;
condition_variable::wait_until Method
Blocks a thread, and sets a maximum point in time at which the thread unblocks.
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);
cv_status wait_until(
unique_lock<mutex>& Lck,
const xtime* Abs_time);
template <class Predicate>
bool wait_until(
unique_lock<mutex>& Lck,
const xtime* Abs_time, Predicate Pred);
Parameters
Lck
A unique_lock<mutex> object.
Abs_time
A chrono::time_point object.
Pred
Any expression that returns true or false.
Return Value
Methods that return a cv_status type return cv_status::timeout if the wait terminates when Abs_time elapses. Otherwise, the methods return cv_status::no_timeout.
Methods that return a bool return the value of Pred.
Remarks
The first method blocks until the condition_variable object is signaled by a call to notify_one or notify_all or until Abs_time. It can also wake up spuriously.
In effect, the second method executes the following code
while(!Pred())
if(wait_until(Lck, Abs_time) == cv_status::timeout)
return Pred();
return true;
The third and fourth methods use a pointer to an object of type xtime to replace the chrono::time_point object. The xtime object specifies the maximum amount of time to wait for a signal.