stk_sync_rwmutex.h

Go to the documentation of this file.

/*
 * SuperTinyKernel(TM) RTOS: Lightweight High-Performance Deterministic C++ RTOS for Embedded Systems.
 *
 * Source: https://github.com/SuperTinyKernel-RTOS
 *
 * Copyright (c) 2022-2026 Neutron Code Limited <stk@neutroncode.com>. All Rights Reserved.
 * License: MIT License, see LICENSE for a full text.
 */
 
#ifndef STK_SYNC_RWMUTEX_H_
#define STK_SYNC_RWMUTEX_H_
 
#include "stk_sync_cv.h"

 
namespace stk {
namespace sync {

class RWMutex final : public IMutex, public ITraceable
{
public:
    explicit RWMutex() : m_readers(0U), m_writers_waiting(0U), m_writer_active(false)
    {}

    STK_VIRT_DTOR ~RWMutex()
    {
        // API contract: must not be destroyed while readers are active, writers are waiting,
        // or a writer holds the lock
        STK_ASSERT((m_readers == 0U) && (m_writers_waiting == 0U) && !m_writer_active);
    }

    class ScopedTimedLock
    {
    public:
        explicit ScopedTimedLock(RWMutex &rw, Timeout timeout_ticks = WAIT_INFINITE)
            : m_rw(rw), m_locked(rw.TimedLock(timeout_ticks))
        {}
 
        ~ScopedTimedLock() { if (m_locked) { m_rw.Unlock(); } }
 
        bool IsLocked() const { return m_locked; }
 
    private:
        STK_NONCOPYABLE_CLASS(ScopedTimedLock);
 
        RWMutex &m_rw;
        bool     m_locked;
    };

    class ScopedTimedReadMutex
    {
    public:
        explicit ScopedTimedReadMutex(RWMutex &rw, Timeout timeout_ticks = WAIT_INFINITE)
            : m_rw(rw), m_locked(rw.TimedReadLock(timeout_ticks))
        {}
 
        ~ScopedTimedReadMutex() { if (m_locked) { m_rw.ReadUnlock(); } }
 
        bool IsLocked() const { return m_locked; }
 
    private:
        STK_NONCOPYABLE_CLASS(ScopedTimedReadMutex);
 
        RWMutex &m_rw;
        bool     m_locked;
    };

    bool TimedReadLock(Timeout timeout_ticks);

    void ReadLock() { STK_UNUSED(TimedReadLock(WAIT_INFINITE)); }

    bool TryReadLock() { return TimedReadLock(NO_WAIT); }

    void ReadUnlock();

    bool TimedLock(Timeout timeout_ticks);

    void Lock() override { STK_UNUSED(TimedLock(WAIT_INFINITE)); }

    bool TryLock() { return TimedLock(NO_WAIT); }

    void Unlock() override;
 
private:
    STK_NONCOPYABLE_CLASS(RWMutex);
 
    static const uint16_t READERS_MAX = 0xFFFEU; 
    static const uint16_t WRITERS_MAX = 0xFFFEU; 
 
    ConditionVariable m_cv_readers;      
    ConditionVariable m_cv_writers;      
    uint16_t          m_readers;         
    uint16_t          m_writers_waiting; 
    bool              m_writer_active;   
};
 
// ---------------------------------------------------------------------------
// TimedReadLock
// ---------------------------------------------------------------------------
 
inline bool RWMutex::TimedReadLock(Timeout timeout_ticks)
{
    bool success = true;
    ScopedCriticalSection cs_;
 
    // wait if there is an active writer or if writers are waiting (Writer Preference)
    while (m_writer_active || (m_writers_waiting != 0U))
    {
        if (!m_cv_readers.Wait(cs_, timeout_ticks))
        {
            success = false; // timeout
            break;
        }
 
        // re-check on wake: another writer may have queued up while this task was sleeping
    }
 
    // only increment reader count if the lock was successfully acquired without timing out
    if (success)
    {
        STK_ASSERT(m_readers < READERS_MAX); // API contract: reader count must not exceed maximum
 
        m_readers = static_cast<uint16_t>(m_readers + 1U);
    }
 
    return success;
}
 
// ---------------------------------------------------------------------------
// ReadUnlock
// ---------------------------------------------------------------------------
 
inline void RWMutex::ReadUnlock()
{
    const ScopedCriticalSection cs_;
 
    STK_ASSERT(m_readers != 0U); // API contract: must have a matching ReadLock()
 
    m_readers = static_cast<uint16_t>(m_readers - 1U);
 
    // wake a waiting writer when the last reader exits
    if (m_readers == 0U)
    {
        m_cv_writers.NotifyOne_CS();
    }
}
 
// ---------------------------------------------------------------------------
// TimedLock
// ---------------------------------------------------------------------------
 
inline bool RWMutex::TimedLock(Timeout timeout_ticks)
{
    bool success = true;
    ScopedCriticalSection cs_;
 
    STK_ASSERT(m_writers_waiting < WRITERS_MAX); // API contract: waiting writer count must not exceed maximum
 
    m_writers_waiting = static_cast<uint16_t>(m_writers_waiting + 1U);
 
    // wait until there are no active readers and no active writer
    while (m_writer_active || (m_readers != 0U))
    {
        if (!m_cv_writers.Wait(cs_, timeout_ticks))
        {
            // timed out: withdraw from the waiting writers queue
            m_writers_waiting = static_cast<uint16_t>(m_writers_waiting - 1U);
            success = false;
            break;
        }
    }
 
    // only finalize state if the wait didn't time out
    if (success)
    {
        m_writers_waiting = static_cast<uint16_t>(m_writers_waiting - 1U);
 
        // kernel invariant: no readers and no active writer when lock is granted
        if ((m_readers != 0U) || m_writer_active)
        {
            STK_KERNEL_PANIC(KERNEL_PANIC_ASSERT);
        }
 
        m_writer_active = true;
    }
 
    return success;
}
 
// ---------------------------------------------------------------------------
// Unlock
// ---------------------------------------------------------------------------
 
inline void RWMutex::Unlock()
{
    const ScopedCriticalSection cs_;
 
    STK_ASSERT(m_writer_active); // API contract: caller must hold the write lock
 
    m_writer_active = false;
 
    // prioritize waking waiting writers to prevent writer starvation;
    // only wake readers if no writers are queued
    if (m_writers_waiting != 0U)
    {
        m_cv_writers.NotifyOne_CS();
    }
    else
    {
        m_cv_readers.NotifyAll_CS();
    }
}
 
} // namespace sync
} // namespace stk
 
#endif /* STK_SYNC_RWMUTEX_H_ */