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
    }

    bool Wait(Timeout timeout_ticks = WAIT_INFINITE);

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

    void Signal();

    uint16_t GetCount() const { return m_count; }
 
private:
    STK_NONCOPYABLE_CLASS(Semaphore);
 
    uint16_t m_count;     
    uint16_t m_count_max; 
};
 
// ---------------------------------------------------------------------------
// Wait
// ---------------------------------------------------------------------------
 
inline bool Semaphore::Wait(Timeout timeout_ticks)
{
    ScopedCriticalSection cs_;
    bool success = false;
 
    // fast path: resource is available
    if (m_count != 0U)
    {
        m_count = static_cast<uint16_t>(m_count - 1U);
        __stk_full_memfence();
        success = true;
    }
    // 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())
        success = (IKernelService::GetInstance()->Wait(this, &cs_, timeout_ticks) == WAIT_RESULT_SIGNAL);
    }
    // try lock behavior (timeout_ticks=NO_WAIT)
    else
    {
        // success is false already, noop
    }
 
    return success;
}
 
// ---------------------------------------------------------------------------
// Signal
// ---------------------------------------------------------------------------
 
inline void Semaphore::Signal()
{
    const ScopedCriticalSection cs_;
 
    if (m_wait_list.IsEmpty())
    {
        STK_ASSERT(m_count < m_count_max); // API contract: the count must not exceed maximum
 
        // 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();
    }
}
 
} // namespace sync
} // namespace stk
 
#endif /* STK_SYNC_SEMAPHORE_H_ */