stk_sync_fastmutex.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_FASTMUTEX_H_
#define STK_SYNC_FASTMUTEX_H_
 
#include "stk_sync_cs.h"

 
namespace stk {
namespace sync {

class FastMutex final : public SyncObjectBase, public IMutex, public ITraceable
{
public:
    explicit FastMutex() : m_owner_tid(TID_NONE)
    {}

    STK_VIRT_DTOR ~FastMutex()
    {
        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); }
 
private:
    STK_NONCOPYABLE_CLASS(FastMutex);
 
    TId m_owner_tid; 
};
 
// ---------------------------------------------------------------------------
// TimedLock
// ---------------------------------------------------------------------------
 
inline EWaitResult FastMutex::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
 
    // fast path: mutex is free
    if (owner_tid == TID_NONE)
    {
        m_owner_tid = current_tid;
        __stk_full_memfence();
 
        result = WAIT_RESULT_SIGNAL;
    }
    // self-lock: non-recursive mutex, the caller would dead-lock on itself (or silently continue without
    // owning a fresh lock): unrecoverable API contract violation, FastMutex is not recursive
    else if (owner_tid == current_tid)
    {
        STK_KERNEL_PANIC(KERNEL_PANIC_SYNC_DEADLOCK);
    }
    // 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: ownership must have been transferred to this thread by Unlock(),
            // otherwise this is an internal defect, not a caller error
            if (m_owner_tid != current_tid)
            {
                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 FastMutex::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 FastMutex::Unlock()
{
    const ScopedCriticalSection cs_;
 
    STK_ASSERT((m_owner_tid == IKernelService::GetInstance()->GetTid()) &&
               (m_owner_tid != TID_NONE)); // API contract: caller must own the lock
 
    if (!m_wait_list.IsEmpty())
    {
        // slow path: contended unlock, hand over to the first waiter
        IKernelService *const svc = IKernelService::GetInstance();
 
        // restore priority of the owner (it could have been boosted by waiters of this mutex),
        // noop if ISwitchStrategy::PRIORITY_INHERITANCE_API = 0; not needed if there are no waiters
        // because a boost is undone by the waiter itself on timeout/cancellation
        if (m_owner_tid != TID_NONE)
        {
            svc->RestoreWeight(m_owner_tid);
        }
 
        // 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_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
    {
        // fast path: free completely if there are no waiters
        m_owner_tid = TID_NONE;
        __stk_full_memfence();
    }
}
 
} // namespace sync
} // namespace stk
 
#endif /* STK_SYNC_FASTMUTEX_H_ */