stk_sync_eventflags.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_FLAGS_H_
#define STK_SYNC_EVENT_FLAGS_H_
 
#include "stk_sync_cv.h"

 
namespace stk {
namespace sync {

class EventFlags final : public ITraceable
{
public:
 
    // -----------------------------------------------------------------------
    // Options constants (bitmask, passed to Wait())
    // -----------------------------------------------------------------------

    static const uint32_t OPT_WAIT_ANY = 0x00000000U;

    static const uint32_t OPT_WAIT_ALL = 0x00000001U;

    static const uint32_t OPT_NO_CLEAR = 0x00000002U;
 
    // -----------------------------------------------------------------------
    // Return-value error sentinels (bit 31 is the error indicator)
    // -----------------------------------------------------------------------

    static const uint32_t ERROR_PARAMETER = 0x80000001U;

    static const uint32_t ERROR_TIMEOUT   = 0x80000002U;

    static const uint32_t ERROR_ISR       = 0x80000004U;

    static const uint32_t ERROR_CANCELED  = 0x80000008U;

    static const uint32_t ERROR_FAIL      = 0x80000010U;

    static const uint32_t ERROR_MASK      = 0x80000000U;
 
    // -----------------------------------------------------------------------
    // Validation helpers
    // -----------------------------------------------------------------------

    static bool IsError(uint32_t result) { return ((result & ERROR_MASK) != 0U); }
 
    // -----------------------------------------------------------------------
    // Construction / destruction
    // -----------------------------------------------------------------------

    explicit EventFlags(uint32_t initial_flags = 0U) : m_flags(initial_flags)
    {
        STK_ASSERT((initial_flags & ERROR_MASK) == 0U); // API contract: bit 31 must not be set
    }

    STK_VIRT_DTOR ~EventFlags() = default;
 
    // -----------------------------------------------------------------------
    // Flag manipulation
    // -----------------------------------------------------------------------

    uint32_t Set(uint32_t flags);

    uint32_t Clear(uint32_t flags);

    uint32_t Get() const;
 
    // -----------------------------------------------------------------------
    // Waiting
    // -----------------------------------------------------------------------

    uint32_t Wait(uint32_t flags, uint32_t options = OPT_WAIT_ANY, Timeout timeout_ticks = WAIT_INFINITE);

    uint32_t TryWait(uint32_t flags, uint32_t options = OPT_WAIT_ANY)
    {
        return Wait(flags, options, NO_WAIT);
    }

    const IWaitObject::ListHeadType &GetWaitList() const
    {
        return m_cv.GetWaitList();
    }

    TId GetFirstWaiterTid() const
    {
        return m_cv.GetFirstWaiterTid();
    }
 
private:
    STK_NONCOPYABLE_CLASS(EventFlags);
 
    // Predicate: returns true when the wait condition for 'flags'/'options' is met.
    // Must be called with m_mutex held.
    bool IsSatisfied(uint32_t flags, uint32_t options) const
    {
        return ((options & OPT_WAIT_ALL) == OPT_WAIT_ALL) ? ((m_flags & flags) == flags) :
            ((m_flags & flags) != 0U);
    }
 
    volatile uint32_t m_flags; 
    ConditionVariable m_cv;    
};
 
// ---------------------------------------------------------------------------
// Set
// ---------------------------------------------------------------------------
 
inline uint32_t EventFlags::Set(uint32_t flags)
{
    uint32_t final_result = ERROR_PARAMETER;
 
    if ((flags != 0U) && ((flags & ERROR_MASK) == 0U))
    {
        const ScopedCriticalSection cs_;
 
        m_flags |= flags;
        final_result = m_flags;
 
        // wake all waiters: each task will re-evaluate its own predicate
        m_cv.NotifyAll_CS();
    }
 
    return final_result;
}
 
// ---------------------------------------------------------------------------
// Clear
// ---------------------------------------------------------------------------
 
inline uint32_t EventFlags::Clear(uint32_t flags)
{
    uint32_t result = ERROR_PARAMETER;
 
    if ((flags != 0U) && ((flags & ERROR_MASK) == 0U))
    {
        const ScopedCriticalSection cs_;
 
        result = m_flags;
        m_flags &= ~flags;
    }
 
    return result;
}
 
// ---------------------------------------------------------------------------
// Get
// ---------------------------------------------------------------------------
 
inline uint32_t EventFlags::Get() const
{
    // atomic on 32-bit aligned targets, a critical section is not required for
    // a single-word read, matching the approach used by Semaphore::GetCount()
    return m_flags;
}
 
// ---------------------------------------------------------------------------
// Wait
// ---------------------------------------------------------------------------
 
inline uint32_t EventFlags::Wait(uint32_t flags, uint32_t options, Timeout timeout_ticks)
{
    uint32_t final_result = 0U;
 
    // validate: flags must be non-zero and must not have the error sentinel bit set
    if ((flags == 0U) || ((flags & ERROR_MASK) != 0U))
    {
        final_result = ERROR_PARAMETER;
    }
    // ISR check: only NO_WAIT is permitted inside an ISR
    else if (hw::IsInsideISR() && (timeout_ticks != NO_WAIT))
    {
        final_result = ERROR_ISR;
    }
    else
    {
        const bool timed_wait = (timeout_ticks != WAIT_INFINITE) && (timeout_ticks != NO_WAIT);
 
        // capture an absolute deadline once, before entering the wait loop,
        // this prevents the timeout from being silently restarted on each
        // spurious wakeup (e.g. a partial Set() that does not satisfy WAIT_ALL)
        const Timeout deadline = (timed_wait ? 
            static_cast<Timeout>(GetTicks() + timeout_ticks) : timeout_ticks);
 
        ScopedCriticalSection cs_;
 
        // spin (with blocking) until the predicate is satisfied or we time out
        while (!IsSatisfied(flags, options))
        {
            Timeout remaining = deadline;
            if (timed_wait)
            {
                const Timeout now = static_cast<Timeout>(GetTicks());
                remaining = (now >= deadline ? NO_WAIT : (deadline - now));
            }
 
            const EWaitResult wr = m_cv.WaitEx(cs_, remaining);
 
            if (wr == WAIT_RESULT_CANCELED)
            {
                // cancelled by IKernel::CancelTaskWait(): stop immediately, do not
                // reinterpret as a timeout and do not keep spinning on the predicate
                final_result = ERROR_CANCELED;
                break;
            }
            else if (wr == WAIT_RESULT_FAIL)
            {
                // kernel rejected the wait: report it as such, not as a timeout
                final_result = ERROR_FAIL;
                break;
            }
            else if (wr != WAIT_RESULT_SIGNAL)
            {
                // timeout (either a real deadline miss, or NO_WAIT after 'remaining'
                // collapsed to NO_WAIT): mark failure and flag the loop to terminate
                final_result = ERROR_TIMEOUT;
                break;
            }
            // else: WAIT_RESULT_SIGNAL - a Set() woke us for re-evaluation (possibly a
            // spurious/partial match under WAIT_ALL); loop back and re-check IsSatisfied()
        }
 
        // If we didn't time out or get cancelled, the predicate was satisfied successfully
        if ((final_result != ERROR_TIMEOUT) && (final_result != ERROR_CANCELED) &&
            (final_result != ERROR_FAIL))
        {
            // predicate satisfied: determine which flags matched
            final_result = (((options & OPT_WAIT_ALL) == OPT_WAIT_ALL) ? flags : (m_flags & flags));
 
            // atomically clear the matched flags unless the caller opted out
            if ((options & OPT_NO_CLEAR) == 0U)
            {
                m_flags &= ~final_result;
            }
        }
    }
 
    return final_result;
}
 
} // namespace sync
} // namespace stk
 
#endif /* STK_SYNC_EVENT_FLAGS_H_ */