OS_FLAGS Struct Reference

A 32-bit event flag group that allows tasks to pend on multiple events. More...

#include <nbrtos.h>

Public Member Functions
	OS_FLAGS ()
	Construct and initialize the OS_FLAGS object with all flags cleared.
void	Init ()
	Reset the OS_FLAGS object to its initial state (all flags cleared).
void	Set (uint32_t bits_to_set)
	Set one or more flag bits.
void	Clear (uint32_t bits_to_clr)
	Clear one or more flag bits.
void	Write (uint32_t bits_to_force)
	Overwrite all 32 flag bits with the specified value.
uint32_t	State ()
	Get the current 32-bit flag state.
uint8_t	PendAny (uint32_t bit_mask, uint16_t timeout=WAIT_FOREVER)
	Wait for any of the specified flag bits to be set.
uint8_t	PendAny (uint32_t bit_mask, TickTimeout &timeout)
	Wait for any of the specified flag bits to be set, using a TickTimeout.
uint8_t	PendAnyUntil (uint32_t bit_mask, uint32_t end_time)
	Wait for any of the specified flag bits to be set until an absolute TimeTick value.
uint8_t	PendAnyNoWait (uint32_t bit_mask)
	Check if any of the specified flag bits are set without waiting.
uint8_t	PendAll (uint32_t bit_mask, uint16_t timeout=WAIT_FOREVER)
	Wait for all of the specified flag bits to be set.
uint8_t	PendAll (uint32_t bit_mask, TickTimeout &timeout)
	Wait for all of the specified flag bits to be set, using a TickTimeout.
uint8_t	PendAllUntil (uint32_t bit_mask, uint32_t end_time)
	Wait for all of the specified flag bits to be set until an absolute TimeTick value.
uint8_t	PendAllNoWait (uint32_t bit_mask)
	Check if all of the specified flag bits are set without waiting.

Detailed Description

A 32-bit event flag group that allows tasks to pend on multiple events.

Unlike an OS_SEM (which tracks a single event), OS_FLAGS provides a 32-bit bitmap where each bit represents an independent event flag. Tasks can wait for any combination of flags to be set using PendAny() or PendAll(). Other tasks or ISRs can signal events by calling Set(), Clear(), or Write().

See also

OS_SEM

---

Expand for Example Usage

Examples

Wait for Any of Several Events

#define FLAG_BUTTON  0x01
#define FLAG_TIMER   0x02
#define FLAG_SERIAL  0x04
 
OS_FLAGS gEventFlags;
 
void EventTask(void *pd)
{
    while (1)
    {
        // Wait for any event, up to 5 seconds
        uint8_t err = gEventFlags.PendAny(FLAG_BUTTON | FLAG_TIMER | FLAG_SERIAL,
                                          5 * TICKS_PER_SECOND);
        if (err == OS_NO_ERR)
        {
            uint32_t state = gEventFlags.State();
            // Process whichever flags are set...
            gEventFlags.Clear(state);   // Clear handled flags
        }
    }
}

---

Constructor & Destructor Documentation

OS_FLAGS()

OS_FLAGS::OS_FLAGS

(

)

Construct and initialize the OS_FLAGS object with all flags cleared.

See also

Init()

Member Function Documentation

Clear()

void OS_FLAGS::Clear

(

uint32_t

bits_to_clr

)

Clear one or more flag bits.

Parameters

bits_to_clr

Bitmask of flags to clear.

See also

Set(), Write(), State()

Init()

void OS_FLAGS::Init

(

)

Reset the OS_FLAGS object to its initial state (all flags cleared).

See also

OS_FLAGS()

PendAll() [1/2]

uint8_t OS_FLAGS::PendAll	(	uint32_t	bit_mask,
		TickTimeout &	timeout )

Wait for all of the specified flag bits to be set, using a TickTimeout.

Parameters

bit_mask	Bitmask of flags that must all be set.
timeout	TickTimeout controlling the maximum wait duration.

Return values

OS_NO_ERR	All flags in bit_mask were set before the timeout.
OS_TIMEOUT	The timeout expired before all flags were set.

See also

PendAllNoWait(), PendAny(), NBRTOS Error Codes

PendAll() [2/2]

uint8_t OS_FLAGS::PendAll ( uint32_t bit_mask, uint16_t timeout = WAIT_FOREVER )

inline

Wait for all of the specified flag bits to be set.

Parameters

bit_mask	Bitmask of flags that must all be set.
timeout	Number of system ticks to wait. A value of 0 (default) waits forever.

Return values

OS_NO_ERR	All flags in bit_mask were set before the timeout.
OS_TIMEOUT	The timeout expired before all flags were set.

See also

PendAllNoWait(), PendAny(), NBRTOS Error Codes

PendAllNoWait()

uint8_t OS_FLAGS::PendAllNoWait

(

uint32_t

bit_mask

)

Check if all of the specified flag bits are set without waiting.

Parameters

bit_mask

Bitmask of flags that must all be set.

Return values

OS_NO_ERR	All flags in bit_mask are currently set.
OS_TIMEOUT	Not all flags in bit_mask are set.

See also

PendAll(), PendAnyNoWait(), NBRTOS Error Codes

PendAllUntil()

uint8_t OS_FLAGS::PendAllUntil ( uint32_t bit_mask, uint32_t end_time )

inline

Wait for all of the specified flag bits to be set until an absolute TimeTick value.

Parameters

bit_mask	Bitmask of flags that must all be set.
end_time	Absolute system TimeTick value at which to stop waiting.

Return values

OS_NO_ERR	All flags in bit_mask were set before end_time.
OS_TIMEOUT	The timeout expired before all flags were set.

See also

PendAll(), PendAllNoWait(), NBRTOS Error Codes

PendAny() [1/2]

uint8_t OS_FLAGS::PendAny	(	uint32_t	bit_mask,
		TickTimeout &	timeout )

Wait for any of the specified flag bits to be set, using a TickTimeout.

Parameters

bit_mask	Bitmask of flags to wait on.
timeout	TickTimeout controlling the maximum wait duration.

Return values

OS_NO_ERR	At least one flag in bit_mask was set before the timeout.
OS_TIMEOUT	No flags in bit_mask were set before the timeout expired.

See also

PendAnyNoWait(), PendAll(), NBRTOS Error Codes

PendAny() [2/2]

uint8_t OS_FLAGS::PendAny ( uint32_t bit_mask, uint16_t timeout = WAIT_FOREVER )

inline

Wait for any of the specified flag bits to be set.

Parameters

bit_mask	Bitmask of flags to wait on.
timeout	Number of system ticks to wait. A value of 0 (default) waits forever.

Return values

OS_NO_ERR	At least one flag in bit_mask was set before the timeout.
OS_TIMEOUT	No flags in bit_mask were set before the timeout expired.

See also

PendAnyNoWait(), PendAll(), NBRTOS Error Codes

PendAnyNoWait()

uint8_t OS_FLAGS::PendAnyNoWait

(

uint32_t

bit_mask

)

Check if any of the specified flag bits are set without waiting.

Parameters

bit_mask

Bitmask of flags to check.

Return values

OS_NO_ERR	At least one flag in bit_mask is set.
OS_TIMEOUT	No flags in bit_mask are set.

See also

PendAny(), PendAll(), NBRTOS Error Codes

PendAnyUntil()

uint8_t OS_FLAGS::PendAnyUntil ( uint32_t bit_mask, uint32_t end_time )

inline

Wait for any of the specified flag bits to be set until an absolute TimeTick value.

Parameters

bit_mask	Bitmask of flags to wait on.
end_time	Absolute system TimeTick value at which to stop waiting.

Return values

OS_NO_ERR	At least one flag in bit_mask was set before end_time.
OS_TIMEOUT	No flags in bit_mask were set before end_time.

See also

PendAny(), PendAnyNoWait(), NBRTOS Error Codes

Set()

void OS_FLAGS::Set

(

uint32_t

bits_to_set

)

Set one or more flag bits.

Any tasks waiting on the affected flags (via PendAny() or PendAll()) will be evaluated and released if their wait condition is now satisfied.

Parameters

bits_to_set

Bitmask of flags to set.

See also

Clear(), Write(), State()

State()

uint32_t OS_FLAGS::State

(

)

Get the current 32-bit flag state.

Returns

The current value of all flags in this OS_FLAGS object.

See also

Set(), Clear(), Write()

Write()

void OS_FLAGS::Write

(

uint32_t

bits_to_force

)

Overwrite all 32 flag bits with the specified value.

Unlike Set() and Clear() which modify individual bits, this function replaces the entire flag word.

Parameters

bits_to_force

The new 32-bit flag value.

See also

Set(), Clear(), State()

---

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

• nbrtos.h