stk_sync_mutex.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_MUTEX_H_
#define STK_SYNC_MUTEX_H_
 
#include "stk_sync_cs.h"

 
namespace stk {
namespace sync {

class Mutex : public IMutex, public ITraceable, private ISyncObject
{
public:
    explicit Mutex() : m_owner_tid(TID_NONE), m_recursion_count(0U)
    {}

    ~Mutex()
    {
        STK_ASSERT(m_wait_list.IsEmpty()); // API contract: must not be destroyed with waiting tasks
    }

    bool TimedLock(Timeout timeout);

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

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

    void Unlock();
 
private:
    STK_NONCOPYABLE_CLASS(Mutex);
 
    static const uint16_t RECURSION_MAX = 0xFFFEu; 
 
    TId      m_owner_tid;       
    uint16_t m_recursion_count; 
};
 
// ---------------------------------------------------------------------------
// TimedLock
// ---------------------------------------------------------------------------
 
inline bool Mutex::TimedLock(Timeout timeout)
{
    STK_ASSERT(!hw::IsInsideISR()); // API contract: caller must not be in ISR
 
    IKernelService *svc = IKernelService::GetInstance();
    TId current_tid = svc->GetTid();
 
    ScopedCriticalSection cs_;
 
    // already owned by the calling thread (recursive path)
    if ((m_recursion_count != 0U) && (m_owner_tid == current_tid))
    {
        STK_ASSERT(m_recursion_count < RECURSION_MAX); // API contract: caller must not exceed max recursion depth
 
        m_recursion_count = static_cast<uint16_t>(m_recursion_count + 1U);
        return true;
    }
 
    // mutex is free (fast path)
    if (m_recursion_count == 0U)
    {
        // kernel invariant: counter is zero so owner must be TID_NONE
        if (m_owner_tid != TID_NONE)
            STK_KERNEL_PANIC(KERNEL_PANIC_ASSERT);
 
        m_recursion_count = 1U;
        m_owner_tid       = current_tid;
        __stk_full_memfence();
 
        return true;
    }
 
    // try lock behavior
    if (timeout == NO_WAIT)
        return false;
 
    // mutex owned by another thread (slow path/blocking)
    if (svc->Wait(this, &cs_, timeout)->IsTimeout())
        return false;
 
    // kernel invariant: if either condition is false, the low-level lock and the
    // recursion counter are out of sync, this is an internal defect, not a caller error
    if ((m_owner_tid != current_tid) || (m_recursion_count != 1U))
        STK_KERNEL_PANIC(KERNEL_PANIC_ASSERT);
 
    return true;
}
 
// ---------------------------------------------------------------------------
// Unlock
// ---------------------------------------------------------------------------
 
inline void Mutex::Unlock()
{
    STK_ASSERT(!hw::IsInsideISR());      // API contract: caller must not be in ISR
    STK_ASSERT(m_owner_tid == GetTid()); // API contract: caller must own the lock
    STK_ASSERT(m_recursion_count != 0U); // API contract: must have matching Lock()
 
    ScopedCriticalSection cs_;
 
    m_recursion_count = static_cast<uint16_t>(m_recursion_count - 1U);
 
    if (m_recursion_count == 0U)
    {
        if (!m_wait_list.IsEmpty())
        {
            // pass ownership directly to the first waiter (FIFO order)
            IWaitObject *waiter = static_cast<IWaitObject *>(m_wait_list.GetFirst());
 
            // transfer ownership to the waiter
            m_recursion_count = 1U;
            m_owner_tid       = waiter->GetTid();
            __stk_full_memfence();
 
            waiter->Wake(false);
        }
        else
        {
            // free completely if there are no waiters
            m_owner_tid = TID_NONE;
            __stk_full_memfence();
        }
    }
}
 
} // namespace sync
} // namespace stk
 
#endif /* STK_SYNC_MUTEX_H_ */