hpx::condition_variable, hpx::condition_variable_any, hpx::cv_status#

Defined in header hpx/condition_variable.hpp.

See Public API for a list of names and headers that are part of the public HPX API.

namespace hpx

Enums

enum class cv_status#

The scoped enumeration hpx::cv_status describes whether a timed wait returned because of timeout or not. hpx::cv_status is used by the wait_for and wait_until member functions of hpx::condition_variable and hpx::condition_variable_any.

Values:

enumerator no_timeout#: The condition variable was awakened with notify_all, notify_one, or spuriously

enumerator timeout#: the condition variable was awakened by timeout expiration

enumerator error#: there was an error

class condition_variable#

#include <condition_variable.hpp>

The condition_variable class is a synchronization primitive that can be used to block a thread, or multiple threads at the same time, until another thread both modifies a shared variable (the condition), and notifies the condition_variable.

The thread that intends to modify the shared variable has to

acquire a hpx::mutex (typically via std::lock_guard)
perform the modification while the lock is held
execute notify_one or notify_all on the condition_variable (the lock does not need to be held for notification)

Even if the shared variable is atomic, it must be modified under the mutex in order to correctly publish the modification to the waiting thread. Any thread that intends to wait on condition_variable has to

acquire a std::unique_lock<hpx::mutex>, on the same mutex as used to protect the shared variable
either
1. check the condition, in case it was already updated and notified
2. execute wait, await_for, or wait_until. The wait operations atomically release the mutex and suspend the execution of the thread.
3. When the condition variable is notified, a timeout expires, or a spurious wakeup occurs, the thread is awakened, and the mutex is atomically reacquired. The thread should then check the condition and resume waiting if the wake up was spurious. or
1. use the predicated overload of wait, wait_for, and wait_until, which takes care of the three steps above.

hpx::condition_variable works only with std::unique_lock<hpx::mutex>. This restriction allows for maximal efficiency on some platforms. hpx::condition_variable_any provides a condition variable that works with any BasicLockable object, such as std::shared_lock.

Condition variables permit concurrent invocation of the wait, wait_for, wait_until, notify_one and notify_all member functions.

The class hpx::condition_variable is a StandardLayoutType. It is not CopyConstructible, MoveConstructible, CopyAssignable, or MoveAssignable.

Public Functions

inline condition_variable()#: Construct an object of type hpx::condition_variable.

~condition_variable() = default#

Destroys the object of type hpx::condition_variable.

IOW, ~condition_variable() can execute before a signaled thread returns from a wait. If this happens with condition_variable, that waiting thread will attempt to lock the destructed mutex. To fix this, there must be shared ownership of the data members between the condition_variable object and the member functions wait (wait_for, etc.).

Note

Preconditions: There is no thread blocked on *this. [Note: That is, all threads have been notified; they could 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]

condition_variable(condition_variable const&) = delete#

condition_variable(condition_variable&&) = delete#

condition_variable &operator=(condition_variable const&) = delete#

condition_variable &operator=(condition_variable&&) = delete#

inline void notify_one(error_code &ec = throws) const#

If any threads are waiting on *this, calling notify_one unblocks one of the waiting threads.

Parameters: ec – Used to hold error code value originated during the operation. Defaults to throws — A special ‘throw on error’ error_code.
Returns: notify_one returns void.

inline void notify_all(error_code &ec = throws) const#

Unblocks all threads currently waiting for *this.

Parameters: ec – Used to hold error code value originated during the operation. Defaults to throws — A special ‘throw on error’ error_code.
Returns: notify_all returns void.

template<typename Mutex> inline void wait(std::unique_lock<Mutex> &lock, error_code &ec = throws)#

wait causes the current thread to block until the condition variable is notified or a spurious wakeup occurs, optionally looping until some predicate is satisfied (bool(pred())==true).

Atomically unlocks lock, blocks the current executing thread, and adds it to the list of threads waiting on *this. The thread will be unblocked when notify_all() or notify_one() is executed. It may also be unblocked spuriously. When unblocked, regardless of the reason, lock is reacquired and wait exits.

Note

1. Calling this function if lock.mutex() is not locked by the current thread is undefined behavior.

Calling this function if lock.mutex() is not the same mutex as the one used by all other threads that are currently waiting on the same condition variable is undefined behavior.

Template Parameters

Mutex – Type of mutex to wait on.

Parameters

lock – unique_lock that must be locked by the current thread
ec – Used to hold error code value originated during the operation. Defaults to throws — A special ‘throw on error’ error_code.

Returns

wait returns void.

template<typename Mutex, typename Predicate> inline void wait(std::unique_lock<Mutex> &lock, Predicate pred, error_code& = throws)#

wait causes the current thread to block until the condition variable is notified or a spurious wakeup occurs, optionally looping until some predicate is satisfied (bool(pred())==true).

Equivalent to

while (!pred()) {
    wait(lock);
}

This overload may be used to ignore spurious awakenings while waiting for a specific condition to become true. Note that lock must be acquired before entering this method, and it is reacquired after wait(lock) exits, which means that lock can be used to guard access to pred().

Note

1. Calling this function if lock.mutex() is not locked by the current thread is undefined behavior.

Calling this function if lock.mutex() is not the same mutex as the one used by all other threads that are currently waiting on the same condition variable is undefined behavior.

Template Parameters

Mutex – Type of mutex to wait on.
Predicate – Type of predicate pred function.

Parameters

lock – unique_lock that must be locked by the current thread
pred – Predicate which returns false if the waiting should be continued (bool(pred())==false). The signature of the predicate function should be equivalent to the following: bool pred();

Returns

wait returns void.

template<typename Mutex> inline cv_status wait_until(std::unique_lock<Mutex> &lock, hpx::chrono::steady_time_point const &abs_time, error_code &ec = throws)#

wait_until causes the current thread to block until the condition variable is notified, a specific time is reached, or a spurious wakeup occurs, optionally looping until some predicate is satisfied (bool(pred())==true).

Atomically releases lock, blocks the current executing thread, and adds it to the list of threads waiting on *this. The thread will be unblocked when notify_all() or notify_one() is executed, or when the absolute time point abs_time is reached. It may also be unblocked spuriously. When unblocked, regardless of the reason, lock is reacquired and wait_until exits.

Note

1. Calling this function if lock.mutex() is not locked by the current thread is undefined behavior.

Calling this function if lock.mutex() is not the same mutex as the one used by all other threads that are currently waiting on the same condition variable is undefined behavior.

Template Parameters

Mutex – Type of mutex to wait on.

Parameters

lock – unique_lock that must be locked by the current thread
abs_time – Represents the time when waiting should be stopped
ec – Used to hold error code value originated during the operation. Defaults to throws — A special ‘throw on error’ error_code.

Returns

cv_status wait_until returns hpx::cv_status::timeout if the absolute timeout specified by abs_time was reached and hpx::cv_status::no_timeout otherwise.

template<typename Mutex, typename Predicate> inline bool wait_until(std::unique_lock<Mutex> &lock, hpx::chrono::steady_time_point const &abs_time, Predicate pred, error_code &ec = throws)#

Equivalent to

while (!pred()) {
    if (wait_until(lock, abs_time) == hpx::cv_status::timeout) {
        return pred();
    }
}
return true;

This overload may be used to ignore spurious wakeups.

Note

1. Calling this function if lock.mutex() is not locked by the current thread is undefined behavior.

Calling this function if lock.mutex() is not the same mutex as the one used by all other threads that are currently waiting on the same condition variable is undefined behavior.

Template Parameters

Mutex – Type of mutex to wait on.
Predicate – Type of predicate pred function.

Parameters

lock – unique_lock that must be locked by the current thread
abs_time – Represents the time when waiting should be stopped
pred – Predicate which returns false if the waiting should be continued (bool(pred())==false). The signature of the predicate function should be equivalent to the following: bool pred();
ec – Used to hold error code value originated during the operation. Defaults to throws — A special ‘throw on error’ error_code.

Returns

bool wait_until returns false if the predicate pred still evaluates to false after the abs_time timeout has expired, otherwise true. If the timeout had already expired, evaluates and returns the result of pred.

template<typename Mutex> inline cv_status wait_for(std::unique_lock<Mutex> &lock, hpx::chrono::steady_duration const &rel_time, error_code &ec = throws)#

Atomically releases lock, blocks the current executing thread, and adds it to the list of threads waiting on *this. The thread will be unblocked when notify_all() or notify_one() is executed, or when the relative timeout rel_time expires. It may also be unblocked spuriously. When unblocked, regardless of the reason, lock is reacquired and wait_for() exits.

The standard recommends that a steady clock be used to measure the duration. This function may block for longer than rel_time due to scheduling or resource contention delays.

Note

1. Calling this function if lock.mutex() is not locked by the current thread is undefined behavior.

Calling this function if lock.mutex() is not the same mutex as the one used by all other threads that are currently waiting on the same condition variable is undefined behavior.
Even if notified under lock, this overload makes no guarantees about the state of the associated predicate when returning due to timeout.

Template Parameters

Mutex – Type of mutex to wait on.

Parameters

lock – unique_lock that must be locked by the current thread
rel_time – represents the maximum time to spend waiting. Note that rel_time must be small enough not to overflow when added to hpx::chrono::steady_clock::now().
ec – Used to hold error code value originated during the operation. Defaults to throws — A special ‘throw on error’ error_code.

Returns

cv_status hpx::cv_status::timeout if the relative timeout specified by rel_time expired, hpx::cv_status::no_timeout otherwise.

template<typename Mutex, typename Predicate> inline bool wait_for(std::unique_lock<Mutex> &lock, hpx::chrono::steady_duration const &rel_time, Predicate pred, error_code &ec = throws)#

Equivalent to.

return wait_until(lock,
           hpx::chrono::steady_clock::now() + rel_time,
           hpx::move(pred));

This overload may be used to ignore spurious awakenings by looping until some predicate is satisfied (bool(pred())==true).

The standard recommends that a steady clock be used to measure the duration. This function may block for longer than rel_time due to scheduling or resource contention delays.

Note

1. Calling this function if lock.mutex() is not locked by the current thread is undefined behavior.

Calling this function if lock.mutex() is not the same mutex as the one used by all other threads that are currently waiting on the same condition variable is undefined behavior.

Template Parameters

Mutex – Type of mutex to wait on.
Predicate – Type of predicate pred function.

Parameters

lock – unique_lock that must be locked by the current thread
rel_time – represents the maximum time to spend waiting. Note that rel_time must be small enough not to overflow when added to hpx::chrono::steady_clock::now().
pred – Predicate which returns false if the waiting should be continued (bool(pred())==false). The signature of the predicate function should be equivalent to the following: bool pred();
ec – Used to hold error code value originated during the operation. Defaults to throws — A special ‘throw on error’ error_code.

Returns

bool wait_for returns false if the predicate pred still evaluates to false after the rel_time timeout expired, otherwise true.

Private Types

using mutex_type = lcos::local::detail::condition_variable_data::mutex_type#

using data_type = hpx::intrusive_ptr<lcos::local::detail::condition_variable_data>#

Private Members

hpx::util::cache_aligned_data_derived<data_type> data_#

class condition_variable_any#

#include <condition_variable.hpp>

The condition_variable_any class is a generalization of hpx::condition_variable. Whereas hpx::condition_variable works only on std::unique_lock<std::mutex>, a condition_variable_any can operate on any lock that meets the BasicLockable requirements.

See hpx::condition_variable for the description of the semantics of condition variables. It is not CopyConstructible, MoveConstructible, CopyAssignable, or MoveAssignable.

Public Functions

inline condition_variable_any()#: Constructs an object of type hpx::condition_variable_any.

~condition_variable_any() = default#

Destroys the object of type hpx::condition_variable_any.

It is only safe to invoke the destructor if all threads have been notified. It is not required that they have exited their respective wait functions: some threads may still be waiting to reacquire the associated lock, or may be waiting to be scheduled to run after reacquiring it.

The programmer must ensure that no threads attempt to wait on *this once the destructor has been started, especially when the waiting threads are calling the wait functions in a loop or are using the overloads of the wait functions that take a predicate.

Preconditions: There is no thread blocked on *this. [Note: That is, all threads have been notified; they could 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]

IOW, ~condition_variable_any() can execute before a signaled thread returns from a wait. If this happens with condition_variable_any, that waiting thread will attempt to lock the destructed mutex. To fix this, there must be shared ownership of the data members between the condition_variable_any object and the member functions wait (wait_for, etc.).

condition_variable_any(condition_variable_any const&) = delete#

condition_variable_any(condition_variable_any&&) = delete#

condition_variable_any &operator=(condition_variable_any const&) = delete#

condition_variable_any &operator=(condition_variable_any&&) = delete#

inline void notify_one(error_code &ec = throws) const#

If any threads are waiting on *this, calling notify_one unblocks one of the waiting threads.

The notifying thread does not need to hold the lock on the same mutex as the one held by the waiting thread(s); in fact doing so is a pessimization, since the notified thread would immediately block again, waiting for the notifying thread to release the lock. However, some implementations (in particular many implementations of pthreads) recognize this situation and avoid this “hurry up and wait” scenario by transferring the waiting thread from the condition variable’s queue directly to the queue of the mutex within the notify call, without waking it up.

Notifying while under the lock may nevertheless be necessary when precise scheduling of events is required, e.g. if the waiting thread would exit the program if the condition is satisfied, causing destruction of the notifying thread’s condition variable. A spurious wakeup after mutex unlock but before notify would result in notify called on a destroyed object.

Note

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.

Parameters: ec – Used to hold error code value originated during the operation. Defaults to throws — A special ‘throw on error’ error_code.
Returns: notify_one returns void.

inline void notify_all(error_code &ec = throws) const#

Unblocks all threads currently waiting for *this.

Note

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.

Parameters: ec – Used to hold error code value originated during the operation. Defaults to throws — A special ‘throw on error’ error_code.
Returns: notify_all returns void.

template<typename Lock> inline void wait(Lock &lock, error_code &ec = throws)#

wait causes the current thread to block until the condition variable is notified or a spurious wakeup occurs, optionally looping until some predicate is satisfied (bool(pred())==true).

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.

Note

If these functions fail to meet the postconditions (lock is locked by the calling thread), std::terminate is called. For example, this could happen if re-locking the mutex throws an exception.

Template Parameters

Lock – Type of lock.

Parameters

lock – An object of type Lock that meets the BasicLockable requirements, which must be locked by the current thread
ec – Used to hold error code value originated during the operation. Defaults to throws — A special’throw on error’ error_code.

Returns

wait returns void.

template<typename Lock, typename Predicate> inline void wait(Lock &lock, Predicate pred, error_code& = throws)#

wait causes the current thread to block until the condition variable is notified or a spurious wakeup occurs, optionally looping until some predicate is satisfied (bool(pred())==true).

Equivalent to

while (!pred()) {
    wait(lock);
}

Note

If these functions fail to meet the postconditions (lock is locked by the calling thread), std::terminate is called. For example, this could happen if re-locking the mutex throws an exception.

Template Parameters

Lock – Type of lock.
Predicate – Type of pred.

Parameters

lock – an object of type Lock that meets the BasicLockable requirements, which must be locked by the current thread
pred – predicate which returns false if the waiting should be continued (bool(pred()) == false). The signature of the predicate function should be equivalent to the following: bool pred().

Returns

wait returns void.

template<typename Lock> inline cv_status wait_until(Lock &lock, hpx::chrono::steady_time_point const &abs_time, error_code &ec = throws)#

Note

Template Parameters

Lock – Type of lock.

Parameters

lock – an object of type Lock that meets the requirements of BasicLockable, which must be locked by the current thread
abs_time – represents the time when waiting should be stopped.
ec – used to hold error code value originated during the operation. Defaults to throws — A special ‘throw on error’ error_code.

Returns

cv_status hpx::cv_status::timeout if the absolute timeout specified by abs_time was reached, hpx::cv_status::no_timeout otherwise.

template<typename Lock, typename Predicate> inline bool wait_until(Lock &lock, hpx::chrono::steady_time_point const &abs_time, Predicate pred, error_code &ec = throws)#

Equivalent to

while (!pred()) {
    if (wait_until(lock, timeout_time) == hpx::cv_status::timeout) {
       return pred();
    }
}
return true;

This overload may be used to ignore spurious wakeups.

Note

Template Parameters

Lock – Type of lock.
Predicate – Type of pred.

Parameters

lock – an object of type Lock that meets the requirements of BasicLockable, which must be locked by the current thread
abs_time – represents the time when waiting should be stopped.
pred – predicate which returns false if the waiting should be continued (bool(pred()) == false). The signature of the predicate function should be equivalent to the following: bool pred();.
ec – Used to hold error code value originated during the operation. Defaults to throws — A special ‘throw on error’ error_code.

Returns

bool false if the predicate pred still evaluates to false after the abs_time timeout expired, otherwise true. If the timeout had already expired, evaluates and returns the result of pred.

template<typename Lock> inline cv_status wait_for(Lock &lock, hpx::chrono::steady_duration const &rel_time, error_code &ec = throws)#

Atomically releases lock, blocks the current executing thread, and adds it to the list of threads waiting on *this. The thread will be unblocked when notify_all() or notify_one() is executed, or when the relative timeout rel_time expires. It may also be unblocked spuriously. When unblocked, regardless of the reason, lock is reacquired and wait_for() exits.

Note

Even if notified under lock, this overload makes no guarantees about the state of the associated predicate when returning due to timeout.

Template Parameters

Lock – Type of lock.

Parameters

lock – an object of type Lock that meets the BasicLockable requirements, which must be locked by the current thread.
rel_time – an object of type hpx::chrono::duration representing the maximum time to spend waiting. Note that rel_time must be small enough not to overflow when added to hpx::chrono::steady_clock::now().
ec – Used to hold error code value originated during the operation. Defaults to throws — A special ‘throw on error’ error_code.

Returns

cv_status hpx::cv_status::timeout if the relative timeout specified by rel_time expired, hpx::cv_status::no_timeout otherwise.

template<typename Lock, typename Predicate> inline bool wait_for(Lock &lock, hpx::chrono::steady_duration const &rel_time, Predicate pred, error_code &ec = throws)#

Equivalent to.

return wait_until(lock,
    hpx::chrono::steady_clock::now() + rel_time,
    std::move(pred));

This overload may be used to ignore spurious awakenings by looping until some predicate is satisfied (bool(pred()) == true).

Note

Template Parameters

Lock – Type of lock.
Predicate – Type of pred.

Parameters

lock – an object of type Lock that meets the BasicLockable requirements,which must be locked by the current thread.
rel_time – an object of type hpx::chrono::duration representing the maximum time to spend waiting. Note that rel_time must be small enough not to overflow when added to hpx::chrono::steady_clock::now().
pred – predicate which returns false if the waiting should be continued (bool(pred()) == false). The signature of the predicate function should be equivalent to the following: bool pred();.
ec – Used to hold error code value originated during the operation. Defaults to throws — A special ‘throw on error’ error_code.

Returns

bool false if the predicate pred still evaluates to false after the rel_time timeout expired, otherwise true.

template<typename Lock, typename Predicate> inline bool wait(Lock &lock, stop_token stoken, Predicate pred, error_code &ec = throws)#

wait causes the current thread to block until the condition variable is notified or a spurious wakeup occurs, optionally looping until some predicate is satisfied (bool(pred())==true).

An interruptible wait: registers the condition_variable_any for the duration of wait(), to be notified if a stop request is made on the given stoken’s associated stop-state; it is then equivalent to

while (!stoken.stop_requested()) {
    if (pred()) return true;
    wait(lock);
}
return pred();

Note that the returned value indicates whether pred evaluated to true, regardless of whether there was a stop requested or not.

Note

Template Parameters

Lock – Type of lock.
Predicate – Type of pred.

Parameters

lock – an object of type Lock that meets the BasicLockable requirements, which must be locked by the current thread
stoken – a hpx::stop_token to register interruption for
pred – predicate which returns false if the waiting should be continued (bool(pred()) == false). The signature of the predicate function should be equivalent to the following: bool pred().
ec – Used to hold error code value originated during the operation. Defaults to throws — A special ‘throw on error’ error_code.

Returns

bool result of pred().

template<typename Lock, typename Predicate> inline bool wait_until(Lock &lock, stop_token stoken, hpx::chrono::steady_time_point const &abs_time, Predicate pred, error_code &ec = throws)#

An interruptible wait: registers the condition_variable_any for the duration of wait_until(), to be notified if a stop request is made on the given stoken’s associated stop-state; it is then equivalent to

while (!stoken.stop_requested()) {
    if (pred())
        return true;
    if (wait_until(lock, timeout_time) == hpx::cv_status::timeout)
        return pred();
}
return pred();

Note

Template Parameters

Lock – Type of lock.
Predicate – Type of pred.

Parameters

lock – an object of type Lock that meets the requirements of BasicLockable, which must be locked by the current thread.
stoken – a hpx::stop_token to register interruption for.
abs_time – represents the time when waiting should be stopped.
pred – predicate which returns false if the waiting should be continued (bool(pred()) == false). The signature of the predicate function should be equivalent to the following: bool pred();.
ec – Used to hold error code value originated during the operation. Defaults to throws — A special ‘throw on error’ error_code.

Returns

bool pred(), regardless of whether the timeout was met or stop was requested.

template<typename Lock, typename Predicate> inline bool wait_for(Lock &lock, stop_token stoken, hpx::chrono::steady_duration const &rel_time, Predicate pred, error_code &ec = throws)#

Equivalent to.

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

Note

Template Parameters

Lock – Type of lock.
Predicate – Type of pred.

Parameters

lock – an object of type Lock that meets the BasicLockable requirements, which must be locked by the current thread.
stoken – a hpx::stop_token to register interruption for.
rel_time – an object of type hpx::chrono::duration representing the maximum time to spend waiting. Note that rel_time must be small enough not to overflow when added to hpx::chrono::steady_clock::now().
pred – predicate which returns false if the waiting should be continued (bool(pred()) == false). The signature of the predicate function should be equivalent to the following: bool pred();.
ec – Used to hold error code value originated during the operation. Defaults to throws — A special ‘throw on error’ error_code.

Returns

bool pred(), regardless of whether the timeout was met or stop was requested.

Private Types

using mutex_type = lcos::local::detail::condition_variable_data::mutex_type#

using data_type = hpx::intrusive_ptr<lcos::local::detail::condition_variable_data>#

Private Members

hpx::util::cache_aligned_data_derived<data_type> data_#

namespace lcos

namespace local

Typedefs

typedef hpx::condition_variable instead

HPX master documentation

hpx::condition_variable, hpx::condition_variable_any, hpx::cv_status

hpx::condition_variable, hpx::condition_variable_any, hpx::cv_status#