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_common.h"
#include "stk_sync_cs.h"
#include "stk_sync_cv.h"

 
namespace stk {
namespace sync {

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

    ~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 = WAIT_INFINITE)
            : m_rw(rw), m_locked(rw.TimedLock(timeout))
        {}
 
        ~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 = WAIT_INFINITE)
            : m_rw(rw), m_locked(rw.TimedReadLock(timeout))
        {}
 
        ~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);

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

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

    void ReadUnlock();

    bool TimedLock(Timeout timeout);

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

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

    void Unlock();
 
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)
{
    STK_ASSERT(!hw::IsInsideISR()); // API contract: caller must not be in ISR
 
    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))
            return false; // timeout
 
        // re-check on wake: another writer may have queued up while this task was sleeping
    }
 
    STK_ASSERT(m_readers < READERS_MAX); // API contract: reader count must not exceed maximum
 
    m_readers = static_cast<uint16_t>(m_readers + 1U);
    return true;
}
 
// ---------------------------------------------------------------------------
// ReadUnlock
// ---------------------------------------------------------------------------
 
inline void RWMutex::ReadUnlock()
{
    STK_ASSERT(!hw::IsInsideISR()); // API contract: caller must not be in ISR
 
    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();
}
 
// ---------------------------------------------------------------------------
// TimedLock
// ---------------------------------------------------------------------------
 
inline bool RWMutex::TimedLock(Timeout timeout)
{
    STK_ASSERT(!hw::IsInsideISR());              // API contract: caller must not be in ISR
    STK_ASSERT(m_writers_waiting < WRITERS_MAX); // API contract: waiting writer count must not exceed maximum
 
    ScopedCriticalSection cs_;
 
    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))
        {
            // timed out: withdraw from the waiting writers queue
            m_writers_waiting = static_cast<uint16_t>(m_writers_waiting - 1U);
            return false;
        }
    }
 
    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 true;
}
 
// ---------------------------------------------------------------------------
// Unlock
// ---------------------------------------------------------------------------
 
inline void RWMutex::Unlock()
{
    STK_ASSERT(!hw::IsInsideISR()); // API contract: caller must not be in ISR
    STK_ASSERT(m_writer_active);    // API contract: caller must hold the write lock
 
    ScopedCriticalSection cs_;
 
    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();
    else
        m_cv_readers.NotifyAll();
}
 
} // namespace sync
} // namespace stk
 
#endif /* STK_SYNC_RWMUTEX_H_ */