32-bit event flags group for multi-flag synchronization between tasks. More...

#include <stk_sync_eventflags.h>

Inheritance diagram for stk::sync::EventFlags:

Collaboration diagram for stk::sync::EventFlags:

Public Member Functions
	EventFlags (uint32_t initial_flags=0U)
	Constructor.
	~EventFlags ()
	Destructor.
uint32_t	Set (uint32_t flags)
	Set one or more flags.
uint32_t	Clear (uint32_t flags)
	Clear one or more flags.
uint32_t	Get () const
	Read the current flags word without modifying it.
uint32_t	Wait (uint32_t flags, uint32_t options=OPT_WAIT_ANY, Timeout timeout=WAIT_INFINITE)
	Wait for one or more flags to be set.
uint32_t	TryWait (uint32_t flags, uint32_t options=OPT_WAIT_ANY)
	Non-blocking flag poll.
void	SetTraceName (const char *name)
	Set name.
const char *	GetTraceName () const
	Get name.

Static Public Member Functions
static bool	IsError (uint32_t result)
	Checks if a return value from Set(), Clear(), or Wait() is an error.

Static Public Attributes
static const uint32_t	OPT_WAIT_ANY = 0x00000000U
	Wait for ANY of the specified flags to be set (OR semantics, default).
static const uint32_t	OPT_WAIT_ALL = 0x00000001U
	Wait for ALL of the specified flags to be set simultaneously (AND semantics).
static const uint32_t	OPT_NO_CLEAR = 0x00000002U
	Do not clear matched flags after a successful wait.
static const uint32_t	ERROR_PARAMETER = 0x80000001U
	Return sentinel: invalid flags argument (bit 31 set).
static const uint32_t	ERROR_TIMEOUT = 0x80000002U
	Return sentinel: wait timed out before the flags condition was met.
static const uint32_t	ERROR_ISR = 0x80000004U
	Return sentinel: called from an ISR with a blocking timeout.
static const uint32_t	ERROR_MASK = 0x80000000U
	Reserved error mask. Any return value with bit 31 set is an error.

Private Member Functions
	STK_NONCOPYABLE_CLASS (EventFlags)
bool	IsSatisfied (uint32_t flags, uint32_t options) const

Private Attributes
volatile uint32_t	m_flags
	32-bit flags word (bit 31 is reserved for errors)
ConditionVariable	m_cv
	woken by Set() to re-evaluate waiting tasks

Detailed Description

32-bit event flags group for multi-flag synchronization between tasks.

EventFlags maintains a 32-bit word where each bit represents an independent boolean event. Tasks can set or clear any combination of flags, and wait for any subset to become set — either requiring all requested flags (AND semantics) or any one of them (OR semantics).

Unlike Event, which models a single binary signal, EventFlags allows fine-grained coordination across up to 32 independent conditions in a single object.

Note: Wait semantics: the caller selects the mode via the options parameter using WAIT_ANY (default) or WAIT_ALL.; Auto-clear: by default the matched flags are atomically cleared upon a successful Wait(). Pass NO_CLEAR to suppress this.; Direct Handover: Set() notifies all waiters so that every task re-evaluates its own predicate after waking. Each waiter clears only the flags it matched, so concurrent waiters with disjoint flag masks do not interfere with each other.; Maximum flag bit index is 30 (bits 0..30). Bit 31 is reserved for future error reporting and must never be set by the caller.

// Example: sensor fusion — wait for GPS and IMU data to both arrive
stk::sync::EventFlags g_SensorFlags;
 
static const uint32_t FLAG_GPS = (1U << 0);
static const uint32_t FLAG_IMU = (1U << 1);
 
void ISR_GPS() {
    g_SensorFlags.Set(FLAG_GPS);   // ISR-safe
}
 
void ISR_IMU() {
    g_SensorFlags.Set(FLAG_IMU);   // ISR-safe
}
 
void Task_Fusion() {
    // block until BOTH flags are set simultaneously; clears them on return
    uint32_t raised = g_SensorFlags.Wait(FLAG_GPS | FLAG_IMU,
                                         EventFlags::WAIT_ALL, 5000);
    if (raised & EventFlags::ERROR_TIMEOUT) {
        // handle timeout
    } else {
        // process fused sensor data
    }
}

See also: Event, Semaphore, ConditionVariable

Note: Only available when kernel is compiled with KERNEL_SYNC mode enabled.

Definition at line 75 of file stk_sync_eventflags.h.

Constructor & Destructor Documentation

◆ EventFlags()

stk::sync::EventFlags::EventFlags ( uint32_t initial_flags = 0U )

inlineexplicit

Constructor.

Parameters

[in] initial_flags Initial value of the 32-bit flags word. Only bits 0..30 are meaningful; bit 31 is reserved.

Definition at line 125 of file stk_sync_eventflags.h.

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

References ERROR_MASK, m_flags, and STK_ASSERT.

Referenced by STK_NONCOPYABLE_CLASS().

Here is the caller graph for this function:

◆ ~EventFlags()

stk::sync::EventFlags::~EventFlags ( )

inline

Destructor.

Note: If tasks are still waiting at destruction time it is a logical error (dangling waiters). An assertion is triggered in debug builds.; MISRA deviation: [STK-DEV-005] Rule 10-3-2.

Definition at line 135 of file stk_sync_eventflags.h.

    {
        // API contract: must not be destroyed while tasks are waiting
        // (checked inside Mutex/ConditionVariable destructors via their own assertions)
    }

Member Function Documentation

◆ Clear()

uint32_t stk::sync::EventFlags::Clear ( uint32_t flags )

inline

Clear one or more flags.

Atomically clears the specified flags from the internal word.

Parameters

[in] flags Bitmask of flags to clear. Must not have bit 31 set.

Returns: The flags word value before clearing, or ERROR_PARAMETER if flags is 0 or has bit 31 set.

Note: ISR-safe.

Definition at line 255 of file stk_sync_eventflags.h.

{
    if ((flags == 0U) || ((flags & ERROR_MASK) != 0U))
        return ERROR_PARAMETER;
 
    ScopedCriticalSection cs_;
 
    const uint32_t prev = m_flags;
    m_flags &= ~flags;
 
    return prev;
}

References ERROR_MASK, ERROR_PARAMETER, and m_flags.

Referenced by stk_ef_clear().

Here is the caller graph for this function:

◆ Get()

uint32_t stk::sync::EventFlags::Get ( ) const

inline

Read the current flags word without modifying it.

Returns: Snapshot of the current 32-bit flags word.

Note: The returned value is a point-in-time snapshot; it may be stale by the time the caller acts on it.; ISR-safe.

Definition at line 272 of file stk_sync_eventflags.h.

{
    // 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;
}

References m_flags.

Referenced by stk_ef_get().

Here is the caller graph for this function:

◆ GetTraceName()

const char * stk::ITraceable::GetTraceName ( ) const

inlineinherited

Get name.

Returns: Name string, or NULL if not set or if STK_SYNC_DEBUG_NAMES is 0.

Definition at line 278 of file stk_common.h.

    {
    #if STK_SYNC_DEBUG_NAMES
        return m_trace_name;
    #else
        return nullptr;
    #endif
    }

◆ IsError()

bool stk::sync::EventFlags::IsError ( uint32_t result )

inlinestatic

Checks if a return value from Set(), Clear(), or Wait() is an error.

Returns: true when the value carries an error sentinel (bit 31 set).

Definition at line 115 of file stk_sync_eventflags.h.

115{ return ((result & ERROR_MASK) != 0U); }

References ERROR_MASK.

Here is the caller graph for this function:

◆ IsSatisfied()

bool stk::sync::EventFlags::IsSatisfied	(	uint32_t	flags,
		uint32_t	options ) const

inlineprivate

Definition at line 219 of file stk_sync_eventflags.h.

    {
        if (options & OPT_WAIT_ALL)
            return ((m_flags & flags) == flags);
        else
            return ((m_flags & flags) != 0U);
    }

References m_flags, and OPT_WAIT_ALL.

Referenced by Wait().

Here is the caller graph for this function:

◆ Set()

uint32_t stk::sync::EventFlags::Set ( uint32_t flags )

inline

Set one or more flags.

Performs an atomic OR of flags into the internal flags word, then wakes all tasks currently waiting on this object so that each can re-evaluate its own wait condition.

Parameters

[in] flags Bitmask of flags to set. Must not have bit 31 set.

Returns: The flags word value after setting, or ERROR_PARAMETER if flags is 0 or has bit 31 set.

Note: ISR-safe.

Definition at line 235 of file stk_sync_eventflags.h.

{
    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;
}

References ERROR_MASK, ERROR_PARAMETER, m_cv, and m_flags.

Referenced by stk_ef_set().

Here is the caller graph for this function:

◆ SetTraceName()

void stk::ITraceable::SetTraceName ( const char * name )

inlineinherited

Set name.

Parameters

[in] name Null-terminated string or NULL.

Note: If STK_SYNC_DEBUG_NAMES is 0 then calling this function has no effect.

Definition at line 266 of file stk_common.h.

    {
    #if STK_SYNC_DEBUG_NAMES
        m_trace_name = name;
    #else
        (void)name;
    #endif
    }

◆ STK_NONCOPYABLE_CLASS()

stk::sync::EventFlags::STK_NONCOPYABLE_CLASS ( EventFlags )

private

References EventFlags().

Here is the call graph for this function:

◆ TryWait()

uint32_t stk::sync::EventFlags::TryWait	(	uint32_t	flags,
		uint32_t	options = OPT_WAIT_ANY )

inline

Non-blocking flag poll.

Checks immediately whether the flag condition is satisfied. Clears matched flags on success unless NO_CLEAR is set.

Parameters

[in]	flags	Bitmask of flag bits to watch.
[in]	options	`WAIT_ANY` (default) or `WAIT_ALL`, optionally `NO_CLEAR`.

Returns: Matched flags bitmask, or an ERROR_* sentinel.

Note: ISR-safe.

Definition at line 209 of file stk_sync_eventflags.h.

    {
        return Wait(flags, options, NO_WAIT);
    }

References stk::NO_WAIT, OPT_WAIT_ANY, and Wait().

Referenced by stk_ef_trywait().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ Wait()

uint32_t stk::sync::EventFlags::Wait	(	uint32_t	flags,
		uint32_t	options = OPT_WAIT_ANY,
		Timeout	timeout = WAIT_INFINITE )

inline

Wait for one or more flags to be set.

Suspends the calling task until the requested flag condition is satisfied or the timeout expires.

On success the matched flags are atomically cleared (unless NO_CLEAR is passed in options).

Parameters

[in]	flags	Bitmask of flag bits to watch. Must not be 0 and must not have bit 31 set.
[in]	options	Combination of `WAIT_ANY` / `WAIT_ALL` and optionally `NO_CLEAR`. Default: `WAIT_ANY` (clear on success).
[in]	timeout	Maximum time to wait (ticks). Use `WAIT_INFINITE` to block indefinitely, `NO_WAIT` for a non-blocking poll.

Returns: Bitmask of the flags that caused the wakeup (the matched subset), or one of the ERROR_* sentinels on failure. Always check IsError() before using the return value as a flags mask.

Note: If the predicate becomes satisfied in the same tick that the deadline expires, the wait succeeds and returns the matched flags. The timeout is only reported when the condition is not met at deadline time.

Warning: ISR-safe only with timeout = NO_WAIT, ISR-unsafe otherwise.

Definition at line 283 of file stk_sync_eventflags.h.

{
    // 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;
}

References ERROR_ISR, ERROR_MASK, ERROR_PARAMETER, ERROR_TIMEOUT, stk::GetTicks(), stk::hw::IsInsideISR(), IsSatisfied(), m_cv, m_flags, stk::NO_WAIT, OPT_NO_CLEAR, OPT_WAIT_ALL, and stk::WAIT_INFINITE.

Referenced by stk_ef_wait(), and TryWait().

Here is the call graph for this function:

Here is the caller graph for this function:

Member Data Documentation

◆ ERROR_ISR

const uint32_t stk::sync::EventFlags::ERROR_ISR = 0x80000004U

static

Return sentinel: called from an ISR with a blocking timeout.

Definition at line 103 of file stk_sync_eventflags.h.

Referenced by Wait().

◆ ERROR_MASK

const uint32_t stk::sync::EventFlags::ERROR_MASK = 0x80000000U

static

Reserved error mask. Any return value with bit 31 set is an error.

Definition at line 106 of file stk_sync_eventflags.h.

Referenced by Clear(), EventFlags(), IsError(), Set(), and Wait().

◆ ERROR_PARAMETER

const uint32_t stk::sync::EventFlags::ERROR_PARAMETER = 0x80000001U

static

Return sentinel: invalid flags argument (bit 31 set).

Definition at line 97 of file stk_sync_eventflags.h.

Referenced by Clear(), Set(), and Wait().

◆ ERROR_TIMEOUT

const uint32_t stk::sync::EventFlags::ERROR_TIMEOUT = 0x80000002U

static

Return sentinel: wait timed out before the flags condition was met.

Definition at line 100 of file stk_sync_eventflags.h.

Referenced by stk::test::eventflags::InitialFlagsTask< _AccessMode >::Run(), stk::test::eventflags::TimeoutTask< _AccessMode >::Run(), and Wait().

◆ m_cv

ConditionVariable stk::sync::EventFlags::m_cv

private

woken by Set() to re-evaluate waiting tasks

Definition at line 228 of file stk_sync_eventflags.h.

Referenced by Set(), and Wait().

◆ m_flags

volatile uint32_t stk::sync::EventFlags::m_flags

private

32-bit flags word (bit 31 is reserved for errors)

Definition at line 227 of file stk_sync_eventflags.h.

Referenced by Clear(), EventFlags(), Get(), IsSatisfied(), Set(), and Wait().

◆ OPT_NO_CLEAR

const uint32_t stk::sync::EventFlags::OPT_NO_CLEAR = 0x00000002U

static

Do not clear matched flags after a successful wait.

Definition at line 90 of file stk_sync_eventflags.h.

Referenced by stk::test::eventflags::NoClearTask< _AccessMode >::Run(), and Wait().

◆ OPT_WAIT_ALL

const uint32_t stk::sync::EventFlags::OPT_WAIT_ALL = 0x00000001U

static

Wait for ALL of the specified flags to be set simultaneously (AND semantics).

Definition at line 87 of file stk_sync_eventflags.h.

Referenced by IsSatisfied(), stk::test::eventflags::MultiWaiterAllTask< _AccessMode >::Run(), stk::test::eventflags::SetWaitAllTask< _AccessMode >::Run(), and Wait().

◆ OPT_WAIT_ANY

const uint32_t stk::sync::EventFlags::OPT_WAIT_ANY = 0x00000000U

static

Wait for ANY of the specified flags to be set (OR semantics, default).

Definition at line 84 of file stk_sync_eventflags.h.

Referenced by stk::test::eventflags::ClearTask< _AccessMode >::Run(), stk::test::eventflags::GetTask< _AccessMode >::Run(), stk::test::eventflags::InitialFlagsTask< _AccessMode >::Run(), stk::test::eventflags::MultiWaiterAnyTask< _AccessMode >::Run(), stk::test::eventflags::NoClearTask< _AccessMode >::Run(), stk::test::eventflags::SetWaitAnyTask< _AccessMode >::Run(), stk::test::eventflags::TimeoutTask< _AccessMode >::Run(), and TryWait().

The documentation for this class was generated from the following file:

stk_sync_eventflags.h

Public Member Functions

Static Public Member Functions

Static Public Attributes

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ EventFlags()

◆ ~EventFlags()

Member Function Documentation

◆ Clear()

◆ Get()

◆ GetTraceName()

◆ IsError()

◆ IsSatisfied()

◆ Set()

◆ SetTraceName()

◆ STK_NONCOPYABLE_CLASS()

◆ TryWait()

◆ Wait()

Member Data Documentation

◆ ERROR_ISR

◆ ERROR_MASK

◆ ERROR_PARAMETER

◆ ERROR_TIMEOUT

◆ m_cv

◆ m_flags

◆ OPT_NO_CLEAR

◆ OPT_WAIT_ALL

◆ OPT_WAIT_ANY