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 : 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_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
    }

    ~EventFlags()
    {
        // API contract: must not be destroyed while tasks are waiting
        // (checked inside Mutex/ConditionVariable destructors via their own assertions)
    }
 
    // -----------------------------------------------------------------------
    // 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 = WAIT_INFINITE);

    uint32_t TryWait(uint32_t flags, uint32_t options = OPT_WAIT_ANY)
    {
        return Wait(flags, options, NO_WAIT);
    }
 
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
    {
        if (options & OPT_WAIT_ALL)
            return ((m_flags & flags) == flags);
        else
            return ((m_flags & flags) != 0U);
    }
 
    volatile uint32_t m_flags; 
    ConditionVariable m_cv;    
};
 
// ---------------------------------------------------------------------------
// Set
// ---------------------------------------------------------------------------
 
inline uint32_t EventFlags::Set(uint32_t flags)
{
    if ((flags == 0U) || ((flags & ERROR_MASK) != 0U))
        return ERROR_PARAMETER;
 
    ScopedCriticalSection cs_;
 
    m_flags |= flags;
    const uint32_t result = m_flags;
 
    // wake all waiters: each task will re-evaluate its own predicate
    m_cv.NotifyAll();
 
    return result;
}
 
// ---------------------------------------------------------------------------
// Clear
// ---------------------------------------------------------------------------
 
inline uint32_t EventFlags::Clear(uint32_t flags)
{
    if ((flags == 0U) || ((flags & ERROR_MASK) != 0U))
        return ERROR_PARAMETER;
 
    ScopedCriticalSection cs_;
 
    const uint32_t prev = m_flags;
    m_flags &= ~flags;
 
    return prev;
}
 
// ---------------------------------------------------------------------------
// 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)
{
    // validate: flags must be non-zero and must not have the error sentinel bit set
    if ((flags == 0U) || ((flags & ERROR_MASK) != 0U))
        return ERROR_PARAMETER;
 
    // ISR check: only NO_WAIT is permitted inside an ISR
    if (hw::IsInsideISR() && (timeout != NO_WAIT))
        return ERROR_ISR;
 
    const bool timed_wait = (timeout != WAIT_INFINITE) && (timeout != 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) : timeout);
 
    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));
        }
 
        if (!m_cv.Wait(cs_, remaining))
        {
            // timeout: release the mutex and report failure
            return ERROR_TIMEOUT;
        }
    }
 
    // predicate satisfied: determine which flags matched
    const uint32_t matched = (options & 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 &= ~matched;
 
    return matched;
}
 
} // namespace sync
} // namespace stk
 
#endif /* STK_SYNC_EVENT_FLAGS_H_ */