condition_variable.hpp

Go to the documentation of this file.

#pragma once
 
/// @file userver/engine/condition_variable.hpp
/// @brief @copybrief engine::ConditionVariable
 
#include <chrono>
#include <memory>
 
#include <userver/engine/condition_variable_status.hpp>
#include <userver/engine/deadline.hpp>
#include <userver/engine/impl/condition_variable_any.hpp>
#include <userver/engine/mutex.hpp>
 
USERVER_NAMESPACE_BEGIN
 
namespace engine {
 
/// @ingroup userver_concurrency
///
/// @brief std::condition_variable replacement for asynchronous tasks
///
/// ## Example usage:
///
/// @snippet engine/condition_variable_test.cpp  Sample ConditionVariable usage
///
/// @see @ref scripts/docs/en/userver/synchronization.md
class ConditionVariable final {
public:
    ConditionVariable();
    ~ConditionVariable();
 
    ConditionVariable(const ConditionVariable&) = delete;
    ConditionVariable(ConditionVariable&&) = delete;
    ConditionVariable& operator=(const ConditionVariable&) = delete;
    ConditionVariable& operator=(ConditionVariable&&) = delete;
 
    /// Suspends execution until notified or cancelled
    /// @returns `CvStatus::kNoTimeout` if variable was notified
    /// @returns `CvStatus::kCancelled` if current task is being cancelled
    [[nodiscard]] CvStatus Wait(std::unique_lock<Mutex>& lock);
 
    /// @brief Suspends execution until the predicate is `true` when notification
    /// is received or the task is cancelled
    /// @returns the value of the predicate
    template <typename Predicate>
    [[nodiscard]] bool Wait(std::unique_lock<Mutex>& lock, Predicate&& predicate);
 
    /// @brief Suspends execution until notified or until the timeout expires or
    /// until the task is cancelled.
    /// @returns `CvStatus::kNoTimeout` if variable was notified
    /// @returns `CvStatus::kTimeout` if `timeout` has expired
    /// @returns `CvStatus::kCancelled` if current task is being cancelled
    template <typename Rep, typename Period>
    CvStatus WaitFor(std::unique_lock<Mutex>& lock, std::chrono::duration<Rep, Period> timeout);
 
    /// @brief Suspends execution until the predicate is `true` when notified
    /// or the timeout expires or the task is cancelled.
    /// @returns the value of the predicate
    template <typename Rep, typename Period, typename Predicate>
    bool WaitFor(std::unique_lock<Mutex>& lock, std::chrono::duration<Rep, Period> timeout, Predicate&& predicate);
 
    /// @brief Suspends execution until notified or the time point is reached or
    /// the task is cancelled.
    /// @returns `CvStatus::kNoTimeout` if variable was notified
    /// @returns `CvStatus::kTimeout` if `until` time point was reached
    /// @returns `CvStatus::kCancelled` if current task is being cancelled
    template <typename Clock, typename Duration>
    CvStatus WaitUntil(std::unique_lock<Mutex>& lock, std::chrono::time_point<Clock, Duration> until);
 
    /// @brief Suspends execution until notified or the deadline is reached or the
    /// task is cancelled.
    /// @returns `CvStatus::kNoTimeout` if variable was notified
    /// @returns `CvStatus::kTimeout` if deadline was reached
    /// @returns `CvStatus::kCancelled` if current task is being cancelled
    CvStatus WaitUntil(std::unique_lock<Mutex>& lock, Deadline deadline);
 
    /// @brief Suspends execution until the predicate is `true` when notified
    /// or the time point is reached or the task is cancelled.
    /// @returns the value of the predicate
    template <typename Clock, typename Duration, typename Predicate>
    bool
    WaitUntil(std::unique_lock<Mutex>& lock, std::chrono::time_point<Clock, Duration> until, Predicate&& predicate);
 
    /// @brief Suspends execution until the predicate is `true` when notified
    /// or the deadline is reached or the task is cancelled.
    /// @returns the value of the predicate
    template <typename Predicate>
    bool WaitUntil(std::unique_lock<Mutex>& lock, Deadline deadline, Predicate&& predicate);
 
    /// Notifies one of the waiting tasks
    void NotifyOne();
 
    /// Notifies all waiting tasks
    void NotifyAll();
 
private:
    impl::ConditionVariableAny<Mutex> impl_;
};
 
template <typename Predicate>
bool ConditionVariable::Wait(std::unique_lock<Mutex>& lock, Predicate&& predicate) {
    return WaitUntil(lock, {}, std::forward<Predicate>(predicate));
}
 
template <typename Rep, typename Period>
CvStatus ConditionVariable::WaitFor(std::unique_lock<Mutex>& lock, std::chrono::duration<Rep, Period> timeout) {
    return WaitUntil(lock, Deadline::FromDuration(timeout));
}
 
template <typename Rep, typename Period, typename Predicate>
bool ConditionVariable::WaitFor(
    std::unique_lock<Mutex>& lock,
    std::chrono::duration<Rep, Period> timeout,
    Predicate&& predicate
) {
    return WaitUntil(lock, Deadline::FromDuration(timeout), std::forward<Predicate>(predicate));
}
 
template <typename Clock, typename Duration>
CvStatus ConditionVariable::WaitUntil(std::unique_lock<Mutex>& lock, std::chrono::time_point<Clock, Duration> until) {
    return WaitUntil(lock, Deadline::FromTimePoint(until));
}
 
template <typename Clock, typename Duration, typename Predicate>
bool ConditionVariable::WaitUntil(
    std::unique_lock<Mutex>& lock,
    std::chrono::time_point<Clock, Duration> until,
    Predicate&& predicate
) {
    return WaitUntil(lock, Deadline::FromTimePoint(until), std::forward<Predicate>(predicate));
}
 
template <typename Predicate>
bool ConditionVariable::WaitUntil(std::unique_lock<Mutex>& lock, Deadline deadline, Predicate&& predicate) {
    return impl_.WaitUntil(lock, deadline, std::forward<Predicate>(predicate));
}
 
}  // namespace engine
 
USERVER_NAMESPACE_END