shared_mutex.hpp

Go to the documentation of this file.

#pragma once
 
/// @file userver/engine/shared_mutex.hpp
/// @brief @copybrief engine::SharedMutex
 
#include <userver/engine/condition_variable.hpp>
#include <userver/engine/mutex.hpp>
#include <userver/engine/semaphore.hpp>
 
USERVER_NAMESPACE_BEGIN
 
namespace engine {
 
/// @ingroup userver_concurrency
///
/// @brief std::shared_mutex replacement for asynchronous tasks.
///
/// Ignores task cancellations (succeeds even if the current task is cancelled).
///
/// Writers (unique locks) have priority over readers (shared locks),
/// thus new shared lock waits for the pending writes to finish, which in turn
/// waits for existing existing shared locks to unlock first.
///
/// ## Example usage:
///
/// @snippet engine/shared_mutex_test.cpp  Sample engine::SharedMutex usage
///
/// @see @ref scripts/docs/en/userver/synchronization.md
class SharedMutex final {
public:
    SharedMutex();
    ~SharedMutex() = default;
 
    SharedMutex(const SharedMutex&) = delete;
    SharedMutex(SharedMutex&&) = delete;
    SharedMutex& operator=(const SharedMutex&) = delete;
    SharedMutex& operator=(SharedMutex&&) = delete;
 
    /// Locks the mutex for unique ownership. Blocks current coroutine if the
    /// mutex is locked by another coroutine for reading or writing.
    ///
    /// @note The method waits for the mutex even if the current task is
    /// cancelled.
    void lock();
 
    /// Unlocks the mutex for unique ownership. Before calling this method the
    /// the mutex should be locked for unique ownership by current coroutine.
    ///
    /// @note the order of coroutines to unblock is unspecified. Any code assuming
    /// any specific order (e.g. FIFO) is incorrect and should be fixed.
    void unlock();
 
    /// Tries to lock the mutex for unique ownership without blocking the
    /// coroutine, returns true if succeeded.
    [[nodiscard]] bool try_lock();
 
    /// Tries to lock the mutex for unique ownership in specified duration.
    /// Blocks current coroutine if
    /// the mutex is locked by another coroutine up to the provided duration.
    ///
    /// @returns true if the locking succeeded
    template <typename Rep, typename Period>
    [[nodiscard]] bool try_lock_for(const std::chrono::duration<Rep, Period>&);
 
    /// Tries to lock the mutex for unique ownership till specified time point.
    /// Blocks current coroutine if
    /// the mutex is locked by another coroutine up to the provided duration.
    ///
    /// @returns true if the locking succeeded
    template <typename Clock, typename Duration>
    [[nodiscard]] bool try_lock_until(const std::chrono::time_point<Clock, Duration>&);
 
    /// @overload
    [[nodiscard]] bool try_lock_until(Deadline deadline);
 
    /// Locks the mutex for shared ownership. Blocks current coroutine if the
    /// mutex is locked by another coroutine for reading or writing.
    ///
    /// @note The method waits for the mutex even if the current task is
    /// cancelled.
    void lock_shared();
 
    /// Unlocks the mutex for shared ownership. Before calling this method the
    /// mutex should be locked for shared ownership by current coroutine.
    ///
    /// @note the order of coroutines to unblock is unspecified. Any code assuming
    /// any specific order (e.g. FIFO) is incorrect and should be fixed.
    void unlock_shared();
 
    /// Tries to lock the mutex for shared ownership without blocking the
    /// coroutine, returns true if succeeded.
    [[nodiscard]] bool try_lock_shared();
 
    /// Tries to lock the mutex for shared ownership in specified duration.
    /// Blocks current coroutine if
    /// the mutex is locked by another coroutine up to the provided duration.
    ///
    /// @returns true if the locking succeeded
    template <typename Rep, typename Period>
    [[nodiscard]] bool try_lock_shared_for(const std::chrono::duration<Rep, Period>&);
 
    /// Tries to lock the mutex for shared ownership till specified time point.
    /// Blocks current coroutine if
    /// the mutex is locked by another coroutine up to the provided duration.
    ///
    /// @returns true if the locking succeeded
    template <typename Clock, typename Duration>
    [[nodiscard]] bool try_lock_shared_until(const std::chrono::time_point<Clock, Duration>&);
 
    /// @overload
    [[nodiscard]] bool try_lock_shared_until(Deadline deadline);
 
private:
    bool HasWaitingWriter() const noexcept;
 
    bool WaitForNoWaitingWriters(Deadline deadline);
 
    void DecWaitingWriters();
 
    /* Semaphore can be get by 1 or by SIZE_MAX.
     * 1 = reader, SIZE_MAX = writer.
     *
     * Three possible cases:
     * 1) semaphore is free
     * 2) there are readers in critical section (any count)
     * 3) there is a single writer in critical section
     */
    Semaphore semaphore_;
 
    /* Readers don't try to hold semaphore_ if there is at least one
     * waiting writer => writers don't starve.
     */
    std::atomic_size_t waiting_writers_count_;
    Mutex waiting_writers_count_mutex_;
    ConditionVariable waiting_writers_count_cv_;
};
 
template <typename Rep, typename Period>
bool SharedMutex::try_lock_for(const std::chrono::duration<Rep, Period>& duration) {
    return try_lock_until(Deadline::FromDuration(duration));
}
 
template <typename Rep, typename Period>
bool SharedMutex::try_lock_shared_for(const std::chrono::duration<Rep, Period>& duration) {
    return try_lock_shared_until(Deadline::FromDuration(duration));
}
 
template <typename Clock, typename Duration>
bool SharedMutex::try_lock_until(const std::chrono::time_point<Clock, Duration>& until) {
    return try_lock_until(Deadline::FromTimePoint(until));
}
 
template <typename Clock, typename Duration>
bool SharedMutex::try_lock_shared_until(const std::chrono::time_point<Clock, Duration>& until) {
    return try_lock_shared_until(Deadline::FromTimePoint(until));
}
 
}  // namespace engine
 
USERVER_NAMESPACE_END