stk_sync_event.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_EVENT_H_
#define STK_SYNC_EVENT_H_
 
#include "stk_sync_cs.h"

 
namespace stk {
namespace sync {

class Event final : private SyncObjectBase, public ITraceable
{
public:
    explicit Event(bool manual_reset = false, bool initial_state = false)
        : m_manual_reset(manual_reset), m_signaled(initial_state)
    {}

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

    bool Set();

    bool Reset();

    EWaitResult WaitEx(Timeout timeout_ticks = WAIT_INFINITE);

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

    bool TryWait();

    void Pulse();
 
private:
    STK_NONCOPYABLE_CLASS(Event);
 
    void RemoveWaitObject(IWaitObject *wobj) override;
 
    bool m_manual_reset; 
    bool m_signaled;     
};
 
// ---------------------------------------------------------------------------
// Set
// ---------------------------------------------------------------------------
 
inline bool Event::Set()
{
    const ScopedCriticalSection cs_;
    bool status = true;
 
    if (m_signaled)
    {
        status = false;
    }
    else
    {
        m_signaled = true;
        __stk_full_memfence();
 
        if (m_manual_reset)
        {
            WakeAll();
        }
        else
        {
            WakeOne(); // auto-reset is applied in RemoveWaitObject when the waiter is removed
        }
    }
 
    return status;
}
 
// ---------------------------------------------------------------------------
// Reset
// ---------------------------------------------------------------------------
 
inline bool Event::Reset()
{
    const ScopedCriticalSection cs_;
 
    const bool prev = m_signaled;
 
    m_signaled = false;
    __stk_full_memfence();
 
    return prev;
}
 
// ---------------------------------------------------------------------------
// Pulse
// ---------------------------------------------------------------------------
 
inline void Event::Pulse()
{
    const ScopedCriticalSection cs_;
 
    // transition to signaled so that WakeOne/WakeAll can release waiters:
    // m_signaled is only visible as true while this critical section is held —
    // any woken task will have the event auto-reset in RemoveWaitObject before
    // it can observe m_signaled via Wait() or TryWait()
    m_signaled = true;
    __stk_full_memfence();
 
    if (!m_wait_list.IsEmpty())
    {
        if (m_manual_reset)
        {
            WakeAll();
        }
        else
        {
            WakeOne(); // auto-reset applied in RemoveWaitObject
        }
    }
 
    // force return to non-signaled regardless of whether anyone was waiting
    m_signaled = false;
    __stk_full_memfence();
}
 
// ---------------------------------------------------------------------------
// Wait
// ---------------------------------------------------------------------------
 
inline EWaitResult Event::WaitEx(Timeout timeout_ticks)
{
    ScopedCriticalSection cs_;
 
    // NO_WAIT on a non-signaled event is reported as an immediately-expired timeout
    EWaitResult result = WAIT_RESULT_TIMEOUT;
 
    // fast path: already signaled
    if (m_signaled)
    {
        if (!m_manual_reset)
        {
            m_signaled = false;
            __stk_full_memfence();
        }
 
        result = WAIT_RESULT_SIGNAL;
    }
    // slow path: block until Set() signals the event or timeout expires
    else if (timeout_ticks != NO_WAIT)
    {
        STK_ASSERT(!hw::IsInsideISR()); // API contract: caller must not be in ISR if timeout_ticks!=NO_WAIT
 
        result = IKernelService::GetInstance()->Wait(this, &cs_, timeout_ticks);
    }
    else
    {
        // non-blocking poll: event not signaled, return immediately
        // result is WAIT_RESULT_TIMEOUT already, so noop
    }
 
    return result;
}
 
// ---------------------------------------------------------------------------
// TryWait
// ---------------------------------------------------------------------------
 
inline bool Event::TryWait()
{
    const ScopedCriticalSection cs_;
    bool result = false;
 
    if (m_signaled)
    {
        if (!m_manual_reset)
        {
            m_signaled = false;
            __stk_full_memfence();
        }
 
        result = true;
    }
 
    return result;
}
 
// ---------------------------------------------------------------------------
// RemoveWaitObject
// ---------------------------------------------------------------------------
 
inline void Event::RemoveWaitObject(IWaitObject *wobj)
{
    SyncObjectBase::RemoveWaitObject(wobj);
 
    // kernel invariant: auto-reset is applied here, not at the Set()/Pulse() call site,
    // when a task wakes due to a signal (not a timeout), the event transitions back to
    // non-signaled so that subsequent Wait() calls block until the next Set()
    if (!m_manual_reset && m_signaled)
    {
        if (wobj->GetState() == IWaitObject::STATE_SIGNALED)
        {
            m_signaled = false;
            __stk_full_memfence();
        }
    }
}
 
} // namespace sync
} // namespace stk
 
#endif /* STK_SYNC_EVENT_H_ */