stk_sync_spinlock.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_SPINLOCK_H_
#define STK_SYNC_SPINLOCK_H_
 
#include "stk_helper.h"

 
namespace stk {
namespace sync {

class SpinLock final : public IMutex
{
public:
    explicit SpinLock() : m_owner_tid(TID_NONE), m_recursion_count(0U)
    {}

    STK_VIRT_DTOR ~SpinLock()
    {
        STK_ASSERT(m_owner_tid == TID_NONE); // API contract: lock must not be destroyed while held
    }

    void Lock();

    bool TryLock();

    void Unlock();
 
private:
    STK_NONCOPYABLE_CLASS(SpinLock);
 
    bool LockRecursively(TId locking_tid);
    void MakeLocked(TId locking_tid);
 
    static const uint16_t RECURSION_MAX = 0xFFFEU; 
 
    TId          m_owner_tid;       
    uint16_t     m_recursion_count; 
    hw::SpinLock m_lock;            
};
 
// ---------------------------------------------------------------------------
// Lock
// ---------------------------------------------------------------------------
 
inline void SpinLock::Lock()
{
    const TId current_tid = GetTid();
 
    // increase recursion if this thread already owns the lock
    if (!LockRecursively(current_tid))
    {
        m_lock.Lock();
        MakeLocked(current_tid);
    }
}
 
// ---------------------------------------------------------------------------
// TryLock
// ---------------------------------------------------------------------------
 
inline bool SpinLock::TryLock()
{
    const TId current_tid = GetTid();
    bool success = true;
 
    // increase recursion if this thread already owns the lock
    if (!LockRecursively(current_tid))
    {
        if (!m_lock.TryLock())
        {
            success = false;
        }
        else
        {
            MakeLocked(current_tid);
        }
    }
 
    return success;
}
 
// ---------------------------------------------------------------------------
// Unlock
// ---------------------------------------------------------------------------
 
inline void SpinLock::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()
 
    if (--m_recursion_count == 0U)
    {
        m_owner_tid = TID_NONE;
        __stk_full_memfence();
 
        m_lock.Unlock();
    }
}
 
// ---------------------------------------------------------------------------
// LockRecursively
// ---------------------------------------------------------------------------
 
inline bool SpinLock::LockRecursively(TId locking_tid)
{
    bool success = false;
  
    if ((m_owner_tid == locking_tid) && (m_recursion_count != 0U))
    {
        STK_ASSERT(m_recursion_count < RECURSION_MAX); // API contract: caller must not exceed max recursion depth
 
        ++m_recursion_count;
        success = true;
    }
 
    return success;
}
 
// ---------------------------------------------------------------------------
// MakeLocked
// ---------------------------------------------------------------------------
 
inline void SpinLock::MakeLocked(TId locking_tid)
{
    // 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 != TID_NONE) || (m_recursion_count != 0U))
    {
        STK_KERNEL_PANIC(KERNEL_PANIC_ASSERT);
    }
 
    m_owner_tid       = locking_tid;
    m_recursion_count = 1U;
    __stk_full_memfence();
}
 
} // namespace sync
} // namespace stk
 
#endif /* STK_SYNC_SPINLOCK_H_ */