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 final : private SyncObjectBase, public IMutex, public ITraceable
{
public:
    static const uint16_t RECURSION_MAX = 0xFFFEU; 

    explicit Mutex() : m_owner_tid(TID_NONE), m_recursion_count(0U)
    {}

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

    EWaitResult TimedLockEx(Timeout timeout_ticks);

    bool TimedLock(Timeout timeout_ticks) { return (TimedLockEx(timeout_ticks) == WAIT_RESULT_SIGNAL); }

    void Lock() override;

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

    void Unlock() override;

    TId GetOwner() const { return m_owner_tid; }

    bool IsLocked() const { return (m_owner_tid != TID_NONE); }

    uint16_t GetRecursionCount() const { return m_recursion_count; }
 
private:
    STK_NONCOPYABLE_CLASS(Mutex);
 
    TId      m_owner_tid;       
    uint16_t m_recursion_count; 
};
 
// ---------------------------------------------------------------------------
// TimedLock
// ---------------------------------------------------------------------------
 
inline EWaitResult Mutex::TimedLockEx(Timeout timeout_ticks)
{
    IKernelService *const svc = IKernelService::GetInstance();
    const TId current_tid = svc->GetTid();
 
    ScopedCriticalSection cs_;
 
    const TId owner_tid = m_owner_tid;
 
    // NO_WAIT on a busy mutex is reported as an immediately-expired timeout
    EWaitResult result = WAIT_RESULT_TIMEOUT;
 
    STK_ASSERT(current_tid != TID_NONE); // API contract: must be called inside STK task
 
    // recursive path: already owned by the calling thread
    if ((m_recursion_count != 0U) && (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);
        result = WAIT_RESULT_SIGNAL;
    }
    // fast path: mutex is free
    else if (m_recursion_count == 0U)
    {
        // kernel invariant: counter is zero so owner must be TID_NONE
        if (owner_tid != TID_NONE)
        {
            STK_KERNEL_PANIC(KERNEL_PANIC_ASSERT);
        }
 
        m_recursion_count = 1U;
        m_owner_tid       = current_tid;
        __stk_full_memfence();
 
        result = WAIT_RESULT_SIGNAL;
    }
    // slow path: block until available or timeout expires
    else if (timeout_ticks != NO_WAIT)
    {
        STK_ASSERT(!hw::IsInsideISR()); // API contract: caller must not be in ISR for a blocking call
 
        // boost priority of the owner to avoid priority inversion (in case of SwitchStrategyFixedPriority,
        // otherwise ignored by the kernel), noop if ISwitchStrategy::PRIORITY_INHERITANCE_API = 0
        svc->InheritWeight(owner_tid, GetUserTaskFromTid(current_tid)->GetWeight());
 
        // mutex owned by another thread (slow path/blocking)
        result = svc->Wait(this, &cs_, timeout_ticks);
 
        if (result != WAIT_RESULT_SIGNAL)
        {
            // kernel invariant: a wait that did not end in a signal must not leave this thread as the
            // owner (Unlock() hands over ownership only together with a signal), otherwise the caller
            // would be told it failed while owning a lock nobody will release
            STK_ASSERT(m_owner_tid != current_tid);
 
            // if owner did not change, undo priority boost to avoid stuck elevated priority: lookup for a
            // higher weight within existing wait objects, noop if ISwitchStrategy::PRIORITY_INHERITANCE_API = 0
            if (owner_tid == m_owner_tid)
            {
                svc->RestoreWeight(owner_tid, this);
            }
        }
        else
        {
            // 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);
            }
        }
    }
    // try-lock variant: owned by someone else, but no-wait requested
    else
    {
        // result is WAIT_RESULT_TIMEOUT already, noop
    }
 
    return result;
}
 
// ---------------------------------------------------------------------------
// Lock
// ---------------------------------------------------------------------------
 
inline void Mutex::Lock()
{
    EWaitResult result;
 
    do
    {
        result = TimedLockEx(WAIT_INFINITE);
    }
    while (result == WAIT_RESULT_CANCELED);
 
    if (result != WAIT_RESULT_SIGNAL)
    {
        STK_KERNEL_PANIC(KERNEL_PANIC_ASSERT);
    }
}
 
// ---------------------------------------------------------------------------
// Unlock
// ---------------------------------------------------------------------------
 
inline void Mutex::Unlock()
{
    const ScopedCriticalSection cs_;
 
    STK_ASSERT((m_owner_tid == IKernelService::GetInstance()->GetTid()) &&
               (m_owner_tid != TID_NONE)); // API contract: caller must own the lock
    STK_ASSERT(m_recursion_count != 0U);   // API contract: must have matching Lock()
 
    m_recursion_count = static_cast<uint16_t>(m_recursion_count - 1U);
 
    if (m_recursion_count == 0U)
    {
        IKernelService *const svc = IKernelService::GetInstance();
 
        // restore priority of the owner, noop if ISwitchStrategy::PRIORITY_INHERITANCE_API = 0
        if (m_owner_tid != TID_NONE)
        {
            svc->RestoreWeight(m_owner_tid);
        }
 
        if (!m_wait_list.IsEmpty())
        {
            // pass ownership directly to the first waiter (FIFO order)
            IWaitObject *const waiter = util::DListCast::ListEntryToParent<IWaitObject>(m_wait_list.GetFirst());
 
            // transfer ownership to the waiter
            m_recursion_count = 1U;
            m_owner_tid       = waiter->GetTid();
            __stk_full_memfence();
 
            // wake up
            waiter->Wake(false);
 
            // boost priority from the highest-priority task still in wait list, skip the lookup if none left,
            // noop if ISwitchStrategy::PRIORITY_INHERITANCE_API = 0
            if (!m_wait_list.IsEmpty())
            {
                svc->InheritWeight(m_owner_tid,
                    FindWeightHigherThan(GetUserTaskFromTid(m_owner_tid)->GetWeight()));
            }
        }
        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_ */