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:
    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
    }

    bool TimedLock(Timeout timeout_ticks);

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

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

    void Unlock() override;

    TId GetOwner() const { return m_owner_tid; }
 
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_ticks)
{
    IKernelService *const svc = IKernelService::GetInstance();
    const TId current_tid = svc->GetTid();
 
    ScopedCriticalSection cs_;
 
    const TId owner_tid = m_owner_tid;
    bool success = false;
 
    // 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);
        success = true;
    }
    // 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();
 
        success = true;
    }
    // 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)
        if (svc->Wait(this, &cs_, timeout_ticks) == WAIT_RESULT_TIMEOUT)
        {
            // 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);
            }
 
            success = false;
        }
        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);
            }
 
            success = true;
        }
    }
    // try-lock variant: owned by someone else, but no-wait requested
    else
    {
        // success is false already, noop
    }
 
    return success;
}    
 
// ---------------------------------------------------------------------------
// Unlock
// ---------------------------------------------------------------------------
 
inline void Mutex::Unlock()
{
    const ScopedCriticalSection cs_;
 
    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()
 
    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
        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 currently in wait list,
            // noop if the list is empty or if ISwitchStrategy::PRIORITY_INHERITANCE_API = 0
            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_ */