stk_sync_semaphore.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_SEMAPHORE_H_
#define STK_SYNC_SEMAPHORE_H_
 
#include "stk_sync_cs.h"

 
namespace stk {
namespace sync {

class Semaphore final : private SyncObjectBase, public ITraceable
{
public:
    static const uint16_t COUNT_MAX = 0xFFFEU;

    explicit Semaphore(uint16_t initial_count = 0U, uint16_t max_count = COUNT_MAX)
        : m_count(initial_count), m_count_max(max_count)
    {
        STK_ASSERT(initial_count <= max_count); // API contract: initial count must not exceed maximum
    }

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

    EWaitResult WaitEx(Timeout timeout_ticks = WAIT_INFINITE);

    bool Wait(Timeout timeout_ticks = WAIT_INFINITE) { return (WaitEx(timeout_ticks) == WAIT_RESULT_SIGNAL); }

    bool TryWait() { return Wait(NO_WAIT); }

    void Signal();

    bool TrySignal();

    uint16_t GetCount() const { return m_count; }
 
private:
    STK_NONCOPYABLE_CLASS(Semaphore);
 
    uint16_t m_count;     
    uint16_t m_count_max; 
};
 
// ---------------------------------------------------------------------------
// Wait
// ---------------------------------------------------------------------------
 
inline EWaitResult Semaphore::WaitEx(Timeout timeout_ticks)
{
    ScopedCriticalSection cs_;
 
    // NO_WAIT with no token available is reported as an immediately-expired timeout
    EWaitResult result = WAIT_RESULT_TIMEOUT;
 
    // fast path: resource is available
    if (m_count != 0U)
    {
        m_count = static_cast<uint16_t>(m_count - 1U);
        __stk_full_memfence();
        result = WAIT_RESULT_SIGNAL;
    }
    // slow path: block until Signal() or timeout
    else if (timeout_ticks != NO_WAIT)
    {
        STK_ASSERT(!hw::IsInsideISR()); // API contract: caller must not be in ISR if timeout_ticks!=NO_WAIT
 
        // note: after waking, if not a timeout, we effectively own the resource that Signal() produced
        // but didn't put into m_count (see logic of if (m_wait_list.IsEmpty()) in Signal())
        result = IKernelService::GetInstance()->Wait(this, &cs_, timeout_ticks);
    }
    // try lock behavior (timeout_ticks=NO_WAIT)
    else
    {
        // result is WAIT_RESULT_TIMEOUT already, noop
    }
 
    return result;
}
 
// ---------------------------------------------------------------------------
// Signal
// ---------------------------------------------------------------------------
 
inline void Semaphore::Signal()
{
    const bool success = TrySignal();
    STK_UNUSED(success);
    STK_ASSERT(success); // API contract: the count must not exceed maximum
}
 
// ---------------------------------------------------------------------------
// TrySignal
// ---------------------------------------------------------------------------
 
inline bool Semaphore::TrySignal()
{
    const ScopedCriticalSection cs_;
    bool success = true;
 
    if (m_wait_list.IsEmpty())
    {
        if (m_count >= m_count_max)
        {
            // counter already saturated and no one is waiting to hand the token to directly
            success = false;
        }
        else
        {
            // no one is waiting, save signal for later
            m_count = static_cast<uint16_t>(m_count + 1U);
            __stk_full_memfence();
        }
    }
    else
    {
        // give signal directly to the first waiting task
        WakeOne();
    }
 
    return success;
}
 
} // namespace sync
} // namespace stk
 
#endif /* STK_SYNC_SEMAPHORE_H_ */