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 ()=default
	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_ticks=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_CANCELED = 0x80000008U
	Return sentinel: the wait was cancelled via IKernel::CancelTaskWait() before the flag condition was met (independent of the deadline).
static const uint32_t	ERROR_MASK = 0x80000000U
	Reserved error mask. Any return value with bit 31 set is an error.

Private Member Functions
	EventFlags (const EventFlags &)=delete
EventFlags &	operator= (const EventFlags &)=delete
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.

Examples: D:/SVN/private/stk/interop/c/include/stk_c.h.

Definition at line 75 of file stk_sync_eventflags.h.

Constructor & Destructor Documentation

◆ EventFlags() [1/2]

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 129 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 EventFlags().

Here is the caller graph for this function:

◆ ~EventFlags()

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

default

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.

References OPT_WAIT_ANY, STK_VIRT_DTOR, and stk::WAIT_INFINITE.

◆ EventFlags() [2/2]

stk::sync::EventFlags::EventFlags ( const EventFlags & )

privatedelete

References EventFlags().

Here is the call graph for this function:

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 258 of file stk_sync_eventflags.h.

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

References ERROR_MASK, ERROR_PARAMETER, and m_flags.

Referenced by osThreadFlagsClear(), and 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 277 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(), xEventGroupGetBits(), and xEventGroupWaitBits().

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 548 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 119 of file stk_sync_eventflags.h.

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

References ERROR_MASK.

Referenced by StkFlagsResultToCmsis(), StkFlagsToFrtos(), xEventGroupSetBitsFromISR(), and xEventGroupSync().

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 222 of file stk_sync_eventflags.h.

    {
        return ((options & OPT_WAIT_ALL) == OPT_WAIT_ALL) ? ((m_flags & flags) == flags) :
            ((m_flags & flags) != 0U);
    }

References m_flags, and OPT_WAIT_ALL.

Referenced by Wait().

Here is the caller graph for this function:

◆ operator=()

EventFlags & stk::sync::EventFlags::operator= ( const EventFlags & )

privatedelete

◆ 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 236 of file stk_sync_eventflags.h.

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

References ERROR_MASK, ERROR_PARAMETER, m_cv, and m_flags.

Referenced by osThreadFlagsSet(), stk_ef_set(), and xEventGroupSync().

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 536 of file stk_common.h.

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

References STK_UNUSED.

Referenced by stk::memory::BlockMemoryPool::BlockMemoryPool(), and stk::memory::BlockMemoryPool::BlockMemoryPool().

Here is the caller 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 212 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_ticks = 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_ticks	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.; Returns ERROR_CANCELED, not ERROR_TIMEOUT, if the wait was interrupted via IKernel::CancelTaskWait() before either the flag condition was met or the deadline expired.

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

Definition at line 288 of file stk_sync_eventflags.h.

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

References ERROR_CANCELED, 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, stk::WAIT_INFINITE, stk::WAIT_RESULT_CANCELED, and stk::WAIT_RESULT_SIGNAL.

Referenced by osThreadFlagsWait(), stk_ef_wait(), TryWait(), xEventGroupSync(), and xEventGroupWaitBits().

Here is the call graph for this function:

Here is the caller graph for this function:

Member Data Documentation

◆ ERROR_CANCELED

const uint32_t stk::sync::EventFlags::ERROR_CANCELED = 0x80000008U

static

Return sentinel: the wait was cancelled via IKernel::CancelTaskWait() before the flag condition was met (independent of the deadline).

Definition at line 107 of file stk_sync_eventflags.h.

Referenced by Wait().

◆ 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 StkFlagsResultToCmsis(), and 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 110 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(), StkFlagsResultToCmsis(), 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 StkFlagsResultToCmsis(), and Wait().

◆ m_cv

ConditionVariable stk::sync::EventFlags::m_cv

private

woken by Set() to re-evaluate waiting tasks

Definition at line 229 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 228 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 BuildStkFlagsOpts(), CmsisFlagsOptionsToStk(), 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 BuildStkFlagsOpts(), CmsisFlagsOptionsToStk(), IsSatisfied(), Wait(), and xEventGroupSync().

◆ 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 BuildStkFlagsOpts(), CmsisFlagsOptionsToStk(), TryWait(), and ~EventFlags().

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() [1/2]

◆ ~EventFlags()

◆ EventFlags() [2/2]

Member Function Documentation

◆ Clear()

◆ Get()

◆ GetTraceName()

◆ IsError()

◆ IsSatisfied()

◆ operator=()

◆ Set()

◆ SetTraceName()

◆ TryWait()

◆ Wait()

Member Data Documentation

◆ ERROR_CANCELED

◆ ERROR_ISR

◆ ERROR_MASK

◆ ERROR_PARAMETER

◆ ERROR_TIMEOUT

◆ m_cv

◆ m_flags

◆ OPT_NO_CLEAR

◆ OPT_WAIT_ALL

◆ OPT_WAIT_ANY