semaphore.hpp

Go to the documentation of this file.

#pragma once
 
/// @file userver/engine/semaphore.hpp
/// @brief @copybrief engine::Semaphore
 
#include <atomic>
#include <chrono>
#include <shared_mutex>  // for std locks
#include <stdexcept>
 
#include <userver/engine/deadline.hpp>
#include <userver/engine/impl/wait_list_fwd.hpp>
 
USERVER_NAMESPACE_BEGIN
 
namespace engine {
 
/// Thrown by engine::Semaphore when an amount of locks greater than its current
/// capacity is requested.
class UnreachableSemaphoreLockError final : public std::runtime_error {
public:
    using std::runtime_error::runtime_error;
};
 
/// Thrown by engine::CancellableSemaphore on current task cancellation
class SemaphoreLockCancelledError final : public std::runtime_error {
public:
    using std::runtime_error::runtime_error;
};
 
/// @ingroup userver_concurrency
///
/// @brief Class that allows up to `max_simultaneous_locks` concurrent accesses
/// to the critical section. It honours task cancellation, unlike Semaphore.
///
/// ## Example usage:
///
/// @snippet engine/semaphore_test.cpp  Sample engine::Semaphore usage
///
/// @see @ref scripts/docs/en/userver/synchronization.md
class CancellableSemaphore final {
public:
    using Counter = std::size_t;
 
    /// Creates a semaphore with predefined number of available locks
    /// @param capacity initial number of available locks
    explicit CancellableSemaphore(Counter capacity);
 
    ~CancellableSemaphore();
 
    CancellableSemaphore(CancellableSemaphore&&) = delete;
    CancellableSemaphore(const CancellableSemaphore&) = delete;
    CancellableSemaphore& operator=(CancellableSemaphore&&) = delete;
    CancellableSemaphore& operator=(const CancellableSemaphore&) = delete;
 
    /// Sets the total number of available locks. If the lock count decreases, the
    /// current acquired lock count may temporarily go above the limit.
    void SetCapacity(Counter capacity);
 
    /// Gets the total number of available locks.
    [[nodiscard]] Counter GetCapacity() const noexcept;
 
    /// Returns an approximate number of available locks, use only for statistics.
    [[nodiscard]] std::size_t RemainingApprox() const;
 
    /// Returns an approximate number of used locks, use only for statistics.
    [[nodiscard]] std::size_t UsedApprox() const;
 
    /// Decrements internal semaphore lock counter. Blocks if current counter is
    /// zero until the subsequent call to unlock_shared() by another coroutine.
    ///
    /// @note the user should eventually call unlock_shared() to increment the
    /// lock counter.
    ///
    /// @note the method doesn't wait for the semaphore if the current task is
    /// cancelled. If a task waits on CancellableSemaphore and the cancellation
    /// is requested, the waiting is aborted with an exception.
    ///
    /// @throws UnreachableSemaphoreLockError if `capacity == 0`
    /// @throws SemaphoreLockCancelledError if the current task is cancelled
    void lock_shared();
 
    /// Increments internal semaphore lock counter. If there is a user waiting in
    /// lock_shared() on the same semaphore, it is woken up.
    ///
    /// @note the order of coroutines to unblock is unspecified. Any code assuming
    /// any specific order (e.g. FIFO) is incorrect and must be fixed.
    ///
    /// @note it is allowed to call lock_shared() in one coroutine and
    /// subsequently call unlock_shared() in another coroutine. In particular, it
    /// is allowed to pass std::shared_lock<engine::Semaphore> across coroutines.
    void unlock_shared();
 
    [[nodiscard]] bool try_lock_shared();
 
    template <typename Rep, typename Period>
    [[nodiscard]] bool try_lock_shared_for(std::chrono::duration<Rep, Period>);
 
    template <typename Clock, typename Duration>
    [[nodiscard]] bool try_lock_shared_until(std::chrono::time_point<Clock, Duration>);
 
    [[nodiscard]] bool try_lock_shared_until(Deadline deadline);
 
    void lock_shared_count(Counter count);
 
    void unlock_shared_count(Counter count);
 
    [[nodiscard]] bool try_lock_shared_count(Counter count);
 
    [[nodiscard]] bool try_lock_shared_until_count(Deadline deadline, Counter count);
 
private:
    enum class TryLockStatus { kSuccess, kTransientFailure, kPermanentFailure };
    class SemaphoreWaitStrategy;
 
    TryLockStatus DoTryLock(Counter count);
    TryLockStatus LockFastPath(Counter count);
    bool LockSlowPath(Deadline, Counter count);
 
    impl::FastPimplWaitList lock_waiters_;
    std::atomic<Counter> acquired_locks_;
    std::atomic<Counter> capacity_;
};
 
/// @ingroup userver_concurrency
///
/// @brief Class that allows up to `max_simultaneous_locks` concurrent accesses
/// to the critical section. It ignores task cancellation, unlike
/// CancellableSemaphore.
///
/// ## Example usage:
///
/// @snippet engine/semaphore_test.cpp  Sample engine::Semaphore usage
///
/// @see @ref scripts/docs/en/userver/synchronization.md
class Semaphore final {
public:
    using Counter = std::size_t;
 
    /// Creates a semaphore with predefined number of available locks
    /// @param capacity initial number of available locks
    explicit Semaphore(Counter capacity);
 
    ~Semaphore();
 
    Semaphore(Semaphore&&) = delete;
    Semaphore(const Semaphore&) = delete;
    Semaphore& operator=(Semaphore&&) = delete;
    Semaphore& operator=(const Semaphore&) = delete;
 
    /// Sets the total number of available locks. If the lock count decreases, the
    /// current acquired lock count may temporarily go above the limit.
    void SetCapacity(Counter capacity);
 
    /// Gets the total number of available locks.
    [[nodiscard]] Counter GetCapacity() const noexcept;
 
    /// Returns an approximate number of available locks, use only for statistics.
    [[nodiscard]] std::size_t RemainingApprox() const;
 
    /// Returns an approximate number of used locks, use only for statistics.
    [[nodiscard]] std::size_t UsedApprox() const;
 
    /// Decrements internal semaphore lock counter. Blocks if current counter is
    /// zero until the subsequent call to unlock_shared() by another coroutine.
    /// @note the user must eventually call unlock_shared() to increment the lock
    /// counter.
    /// @note the method waits for the semaphore even if the current task is
    /// cancelled.
    /// @throws UnreachableSemaphoreLockError if `capacity == 0`
    void lock_shared();
 
    /// Increments internal semaphore lock counter. If there is a user waiting in
    /// lock_shared() on the same semaphore, it is woken up.
    /// @note the order of coroutines to unblock is unspecified. Any code assuming
    /// any specific order (e.g. FIFO) is incorrect and must be fixed.
    /// @note it is allowed to call lock_shared() in one coroutine and
    /// subsequently call unlock_shared() in another coroutine. In particular, it
    /// is allowed to pass std::shared_lock<engine::Semaphore> across coroutines.
    void unlock_shared();
 
    /// Decrements internal semaphore lock counter if current counter is
    /// not zero.
    /// @note unlock_shared() should be called later to increment the lock
    /// counter.
    [[nodiscard]] bool try_lock_shared();
 
    template <typename Rep, typename Period>
    [[nodiscard]] bool try_lock_shared_for(std::chrono::duration<Rep, Period>);
 
    template <typename Clock, typename Duration>
    [[nodiscard]] bool try_lock_shared_until(std::chrono::time_point<Clock, Duration>);
 
    [[nodiscard]] bool try_lock_shared_until(Deadline deadline);
 
    void lock_shared_count(Counter count);
 
    void unlock_shared_count(Counter count);
 
    [[nodiscard]] bool try_lock_shared_count(Counter count);
 
    [[nodiscard]] bool try_lock_shared_until_count(Deadline deadline, Counter count);
 
private:
    CancellableSemaphore sem_;
};
 
/// A replacement for std::shared_lock that accepts Deadline arguments
class SemaphoreLock final {
public:
    SemaphoreLock() noexcept = default;
    explicit SemaphoreLock(Semaphore&);
    SemaphoreLock(Semaphore&, std::defer_lock_t) noexcept;
    SemaphoreLock(Semaphore&, std::try_to_lock_t);
    SemaphoreLock(Semaphore&, std::adopt_lock_t) noexcept;
 
    template <typename Rep, typename Period>
    SemaphoreLock(Semaphore&, std::chrono::duration<Rep, Period>);
 
    template <typename Clock, typename Duration>
    SemaphoreLock(Semaphore&, std::chrono::time_point<Clock, Duration>);
 
    SemaphoreLock(Semaphore&, Deadline);
 
    ~SemaphoreLock();
 
    SemaphoreLock(const SemaphoreLock&) = delete;
    SemaphoreLock(SemaphoreLock&&) noexcept;
    SemaphoreLock& operator=(const SemaphoreLock&) = delete;
    SemaphoreLock& operator=(SemaphoreLock&&) noexcept;
 
    [[nodiscard]] bool OwnsLock() const noexcept;
    explicit operator bool() const noexcept { return OwnsLock(); }
 
    void Lock();
    bool TryLock();
 
    template <typename Rep, typename Period>
    bool TryLockFor(std::chrono::duration<Rep, Period>);
 
    template <typename Clock, typename Duration>
    bool TryLockUntil(std::chrono::time_point<Clock, Duration>);
 
    bool TryLockUntil(Deadline);
 
    void Unlock();
    void Release();
 
private:
    Semaphore* sem_{nullptr};
    bool owns_lock_{false};
};
 
template <typename Rep, typename Period>
bool Semaphore::try_lock_shared_for(std::chrono::duration<Rep, Period> duration) {
    return try_lock_shared_until(Deadline::FromDuration(duration));
}
 
template <typename Clock, typename Duration>
bool Semaphore::try_lock_shared_until(std::chrono::time_point<Clock, Duration> until) {
    return try_lock_shared_until(Deadline::FromTimePoint(until));
}
 
template <typename Rep, typename Period>
bool CancellableSemaphore::try_lock_shared_for(std::chrono::duration<Rep, Period> duration) {
    return try_lock_shared_until(Deadline::FromDuration(duration));
}
 
template <typename Clock, typename Duration>
bool CancellableSemaphore::try_lock_shared_until(std::chrono::time_point<Clock, Duration> until) {
    return try_lock_shared_until(Deadline::FromTimePoint(until));
}
 
template <typename Rep, typename Period>
SemaphoreLock::SemaphoreLock(Semaphore& sem, std::chrono::duration<Rep, Period> duration) : sem_(&sem) {
    TryLockFor(duration);
}
 
template <typename Clock, typename Duration>
SemaphoreLock::SemaphoreLock(Semaphore& sem, std::chrono::time_point<Clock, Duration> until) : sem_(&sem) {
    TryLockUntil(until);
}
 
template <typename Rep, typename Period>
bool SemaphoreLock::TryLockFor(std::chrono::duration<Rep, Period> duration) {
    return TryLockUntil(Deadline::FromDuration(duration));
}
 
template <typename Clock, typename Duration>
bool SemaphoreLock::TryLockUntil(std::chrono::time_point<Clock, Duration> until) {
    return TryLockUntil(Deadline::FromTimePoint(until));
}
 
}  // namespace engine
 
USERVER_NAMESPACE_END