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 : public ITraceable, private ISyncObject
{
public:
    explicit Event(bool manual_reset = false, bool initial_state = false)
        : m_manual_reset(manual_reset), m_signaled(initial_state)
    {}

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

    bool Set();

    bool Reset();

    bool Wait(Timeout timeout = WAIT_INFINITE);

    bool TryWait();

    void Pulse();
 
private:
    STK_NONCOPYABLE_CLASS(Event);
 
    void RemoveWaitObject(IWaitObject *wobj);
 
    bool m_manual_reset; 
    bool m_signaled;     
};
 
// ---------------------------------------------------------------------------
// Set
// ---------------------------------------------------------------------------
 
inline bool Event::Set()
{
    ScopedCriticalSection cs_;
 
    if (m_signaled)
        return false;
 
    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 true;
}
 
// ---------------------------------------------------------------------------
// Reset
// ---------------------------------------------------------------------------
 
inline bool Event::Reset()
{
    ScopedCriticalSection cs_;
 
    bool prev = m_signaled;
 
    m_signaled = false;
    __stk_full_memfence();
 
    return prev;
}
 
// ---------------------------------------------------------------------------
// Pulse
// ---------------------------------------------------------------------------
 
inline void Event::Pulse()
{
    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 bool Event::Wait(Timeout timeout)
{
    STK_ASSERT(!hw::IsInsideISR()); // API contract: caller must not be in ISR
 
    ScopedCriticalSection cs_;
 
    // fast path: already signaled
    if (m_signaled)
    {
        if (!m_manual_reset)
        {
            m_signaled = false;
            __stk_full_memfence();
        }
 
        return true;
    }
 
    // non-blocking poll: event not signaled, return immediately
    if (timeout == NO_WAIT)
        return false;
 
    // slow path: block until Set() signals the event or timeout expires
    return !IKernelService::GetInstance()->Wait(this, &cs_, timeout)->IsTimeout();
}
 
// ---------------------------------------------------------------------------
// TryWait
// ---------------------------------------------------------------------------
 
inline bool Event::TryWait()
{
    ScopedCriticalSection cs_;
 
    if (m_signaled)
    {
        if (!m_manual_reset)
        {
            m_signaled = false;
            __stk_full_memfence();
        }
 
        return true;
    }
 
    return false;
}
 
// ---------------------------------------------------------------------------
// RemoveWaitObject
// ---------------------------------------------------------------------------
 
inline void Event::RemoveWaitObject(IWaitObject *wobj)
{
    ISyncObject::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 && !wobj->IsTimeout())
    {
        m_signaled = false;
        __stk_full_memfence();
    }
}
 
} // namespace sync
} // namespace stk
 
#endif /* STK_SYNC_EVENT_H_ */