Base class that provides the standard event group interface to FreeRTOS::EventGroup and FreeRTOS::StaticEventGroup. More...

Inheritance diagram for FreeRTOS::EventGroupBase:

[legend]

Public Types
using	EventBits = std::bitset< 8 >

using	EventBits = std::bitset< 24 >

using	EventBits = std::bitset< 56 >

Public Member Functions
	EventGroupBase (const EventGroupBase &)=delete

EventGroupBase &	operator= (const EventGroupBase &)=delete

bool	isValid () const
	Function that checks if the underlying event group handle is not NULL. This should be used to ensure an event group has been created correctly.

EventBits	wait (const EventBits &bitsToWaitFor=0, const bool clearOnExit=false, const bool waitForAllBits=false, const TickType_t ticksToWait=portMAX_DELAY) const
	Function that calls `EventBits_t xEventGroupWaitBits( const EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToWaitFor, const BaseType_t xClearOnExit, const BaseType_t xWaitForAllBits, TickType_t xTicksToWait )`

EventBits	set (const EventBits &bitsToSet) const
	Function that calls `EventBits_t xEventGroupSetBits( EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToSet )`

bool	setFromISR (bool &higherPriorityTaskWoken, const EventBits &bitsToSet) const
	Function that calls `BaseType_t xEventGroupSetBitsFromISR( EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToSet, BaseType_t *pxHigherPriorityTaskWoken )`

bool	setFromISR (const EventBits &bitsToSet) const
	Function that calls `BaseType_t xEventGroupSetBitsFromISR( EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToSet, BaseType_t *pxHigherPriorityTaskWoken )`

EventBits	clear (const EventBits &bitsToClear) const
	Function that calls `EventBits_t xEventGroupClearBits( EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToClear )`

bool	clearFromISR (const EventBits &bitsToClear) const
	Function that calls `BaseType_t xEventGroupClearBitsFromISR( EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToClear )`

EventBits	get () const
	Function that calls `EventBits_t xEventGroupGetBits( EventGroupHandle_t xEventGroup )`

EventBits	getFromISR () const
	Function that calls `EventBits_t xEventGroupGetBitsFromISR( EventGroupHandle_t xEventGroup )`

EventBits	sync (const EventBits &bitsToSet=0, const EventBits &bitsToWaitFor=0, const TickType_t ticksToWait=portMAX_DELAY) const
	Function that calls `EventBits_t xEventGroupSync( EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToSet, const EventBits_t uxBitsToWaitFor, TickType_t xTicksToWait )`

Static Public Member Functions
static void *	operator new (size_t)=delete

static void *	operator new[] (size_t)=delete

static void *	operator new (size_t, void *ptr)

static void *	operator new[] (size_t, void *ptr)

Private Member Functions
	EventGroupBase ()=default
	Construct a new EventGroupBase object.

	~EventGroupBase ()
	Destroy the EventGroupBase object by calling `void vEventGroupDelete( EventGroupHandle_t xEventGroup )`

	EventGroupBase (EventGroupBase &&) noexcept=default

EventGroupBase &	operator= (EventGroupBase &&) noexcept=default

Private Attributes
EventGroupHandle_t	handle = NULL
	Handle used to refer to the event group when using the FreeRTOS interface.

Friends
class	EventGroup

class	StaticEventGroup

Detailed Description

Base class that provides the standard event group interface to FreeRTOS::EventGroup and FreeRTOS::StaticEventGroup.

Note: This class is not intended to be instantiated by the user. Use FreeRTOS::EventGroup or FreeRTOS::StaticEventGroup.

Constructor & Destructor Documentation

◆ EventGroupBase()

FreeRTOS::EventGroupBase::EventGroupBase ( )

privatedefault

Construct a new EventGroupBase object.

EventGroups.hpp

Note: Default constructor is deliberately private as this class is not intended to be instantiated or derived from by the user. Use FreeRTOS::EventGroup or FreeRTOS::StaticEventGroup.

◆ ~EventGroupBase()

FreeRTOS::EventGroupBase::~EventGroupBase ( )

inlineprivate

Destroy the EventGroupBase object by calling void vEventGroupDelete( EventGroupHandle_t xEventGroup )

EventGroup.hpp

See also: https://www.freertos.org/vEventGroupDelete.html

Delete an event group.

Tasks that are blocked on the event group being deleted will be unblocked, and report an event group value of 0.

Member Function Documentation

◆ clear()

EventBits FreeRTOS::EventGroupBase::clear ( const EventBits & bitsToClear ) const

inline

Function that calls EventBits_t xEventGroupClearBits( EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToClear )

EventGroups.hpp

See also: https://www.freertos.org/xEventGroupClearBits.html

Clear bits (flags) within an RTOS event group. This function cannot be called from an interrupt. See clearFromISR() for a version that can be called from an interrupt.

Parameters

bitsToClear A bitwise value that indicates the bit or bits to clear in the event group.

Returns: EventBits The value of the event group before the specified bits were cleared.

Example Usage

#include <FreeRTOS/EventGroups.hpp>
#include <FreeRTOS/Kernel.hpp>
#include <FreeRTOS/Task.hpp>
 
class MyTask : public FreeRTOS::Task {
 public:
  void taskFunction() final;
 
 private:
  FreeRTOS::EventGroup eventGroup;
};
 
MyTask myTask;
 
void MyTask::taskFunction() {
  FreeRTOS::EventGroup::EventBits bitsToClear;
  bitsToClear[0] = true;
  bitsToClear[4] = true;
 
  // Clear bit 0 and bit 4.
  auto bits = eventGroup.clear(bitsToClear);
 
  if (bits[0] && bits[4]) {
    //  Both bit 0 and bit 4 were set before clear() was called.  Both will now
    //  be clear (not set)
  } else if (bits[0]) {
    // Bit 0 was set before clear() was called.  It will now be clear.
  } else if (bits[4]) {
    // Bit 4 was set before clear() was called.  It will now be clear.
  } else {
    // Neither bit 0 nor bit 4 were set in the first place.
  }
}

◆ clearFromISR()

bool FreeRTOS::EventGroupBase::clearFromISR ( const EventBits & bitsToClear ) const

inline

Function that calls BaseType_t xEventGroupClearBitsFromISR( EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToClear )

EventGroups.hpp

See also: https://www.freertos.org/xEventGroupClearBitsFromISR.html

A version of clear() that can be called from an interrupt. The clear operation is deferred to the RTOS daemon task which is also known as the timer service task. The priority of the daemon task is set by the configTIMER_TASK_PRIORITY setting in FreeRTOSConfig.h.

Parameters

bitsToClear A bitwise value that indicates the bit or bits to clear in the event group.

Returns: true If the operation was successfully deferred to the RTOS daemon task.; false If the timer command queue is full.

Example Usage

#include <FreeRTOS/EventGroups.hpp>
#include <FreeRTOS/Kernel.hpp>
 
FreeRTOS::StaticEventGroup eventGroup;
 
void anInterruptHandler() {
  // Set bit 0 and bit 4 in eventGroup.
  if (eventGroup.clearFromISR(0b1001)) {
    // The command was sent to the daemon task.
  } else {
    // The clear bits command was not sent to the daemon task.
  }
}

◆ get()

EventBits FreeRTOS::EventGroupBase::get ( ) const

inline

Function that calls EventBits_t xEventGroupGetBits( EventGroupHandle_t xEventGroup )

EventGroups.hpp

See also: https://www.freertos.org/xEventGroupGetBits.html

Returns the current value of the event bits (event flags) in an RTOS event group. This function cannot be used from an interrupt. See getFromISR() for a version that can be used in an interrupt.

Returns: EventBits The value of the event bits in the event group at the time get() was called.

◆ getFromISR()

EventBits FreeRTOS::EventGroupBase::getFromISR ( ) const

inline

Function that calls EventBits_t xEventGroupGetBitsFromISR( EventGroupHandle_t xEventGroup )

EventGroups.hpp

See also: https://www.freertos.org/xEventGroupGetBitsFromISR.html

A version of get() that can be called from an interrupt.

Returns: EventBits The value of the event bits in the event group at the time getFromISR() was called.

◆ isValid()

bool FreeRTOS::EventGroupBase::isValid ( ) const

inline

Function that checks if the underlying event group handle is not NULL. This should be used to ensure an event group has been created correctly.

EventGroups.hpp

Return values

true	the handle is not NULL.
false	the handle is NULL.

◆ set()

EventBits FreeRTOS::EventGroupBase::set ( const EventBits & bitsToSet ) const

inline

Function that calls EventBits_t xEventGroupSetBits( EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToSet )

EventGroups.hpp

See also: https://www.freertos.org/xEventGroupSetBits.html

Set bits (flags) within an RTOS event group. This function cannot be called from an interrupt. setFromISR() is a version that can be called from an interrupt.

Setting bits in an event group will automatically unblock tasks that are blocked waiting for the bits.

Parameters

bitsToSet A bitwise value that indicates the bit or bits to set in the event group.

Returns

EventBits The value of the event group at the time the call to set() returns. There are two reasons why the returned value might have the bits specified by the uxBitsToSet parameter cleared:

If setting a bit results in a task that was waiting for the bit leaving the blocked state then it is possible the bit will have been cleared automatically (see the clearOnExit parameter of wait()).
Any unblocked (or otherwise Ready state) task that has a priority above that of the task that called set() will execute and may change the event group value before the call to set() returns.

Example Usage

#include <FreeRTOS/EventGroups.hpp>
#include <FreeRTOS/Kernel.hpp>
#include <FreeRTOS/Task.hpp>
 
class MyTask : public FreeRTOS::Task {
 public:
  void taskFunction() final;
 
 private:
  FreeRTOS::EventGroup eventGroup;
};
 
MyTask myTask;
 
void MyTask::taskFunction() {
  FreeRTOS::EventGroup::EventBits bitsToSet;
  bitsToSet[0] = true;
  bitsToSet[4] = true;
 
  // Set bit 0 and bit 4.
  auto bits = eventGroup.set(bitsToSet);
 
  if (bits[0] && bits[4]) {
    // Both bit 0 and bit 4 remained set when the function returned.
  } else if (bits[0]) {
    // Bit 0 remained set when the function returned, but bit 4 was cleared.  It
    // might be that bit 4 was cleared automatically as a task that was waiting
    // for bit 4 was removed from the Blocked state.
  } else if (bits[4]) {
    // Bit 4 remained set when the function returned, but bit 0 was cleared.  It
    // might be that bit 0 was cleared automatically as a task that was waiting
    // for bit 0 was removed from the Blocked state.
  } else {
    // Neither bit 0 nor bit 4 remained set.  It might be that a task was
    // waiting for both of the bits to be set, and the bits were cleared as the
    // task left the Blocked state.
  }
}

◆ setFromISR() [1/2]

bool FreeRTOS::EventGroupBase::setFromISR	(	bool &	higherPriorityTaskWoken,
		const EventBits &	bitsToSet
	)		const

inline

Function that calls BaseType_t xEventGroupSetBitsFromISR( EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToSet, BaseType_t *pxHigherPriorityTaskWoken )

EventGroups.hpp

See also: https://www.freertos.org/xEventGroupSetBitsFromISR.html

Set bits (flags) within an RTOS event group. A version of set() that can be called from an interrupt service routine (ISR).

Setting bits in an event group will automatically unblock tasks that are blocked waiting for the bits.

Setting bits in an event group is not a deterministic operation because there are an unknown number of tasks that may be waiting for the bit or bits being set. FreeRTOS does not allow non-deterministic operations to be performed in interrupts or from critical sections. Therefore xEventGroupSetBitFromISR() sends a message to the RTOS daemon task to have the set operation performed in the context of the daemon task - where a scheduler lock is used in place of a critical section.

Note: As mentioned in the paragraph above, setting bits from an ISR will defer the set operation to the RTOS daemon task (also known as the timer service task). The RTOS daemon task is scheduled according to its priority, just like any other RTOS task. Therefore, if it is essential the set operation completes immediately (before a task created by the application executes) then the priority of the RTOS daemon task must be higher than the priority of any application task that uses the event group. The priority of the RTOS daemon task is set by the configTIMER_TASK_PRIORITY definition in FreeRTOSConfig.h.

Parameters

higherPriorityTaskWoken As mentioned above, calling this function will result in a message being sent to the RTOS daemon task. If the priority of the daemon task is higher than the priority of the currently running task (the task the interrupt interrupted) then higherPriorityTaskWoken will be set to true by setFromISR(), indicating that a context switch should be requested before the interrupt exits. For that reason higherPriorityTaskWoken must be initialised to false. See the example code below.

bitsToSet A bitwise value that indicates the bit or bits to set in the event group.

Return values

true	If the message was sent to the RTOS daemon task.
false	Otherwise or if the timer service queue was full

Example Usage

#include <FreeRTOS/EventGroups.hpp>
#include <FreeRTOS/Kernel.hpp>
 
FreeRTOS::StaticEventGroup eventGroup;
 
void anInterruptHandler() {
  // higherPriorityTaskWoken must be initialised to false.
  bool higherPriorityTaskWoken = false;
 
  // Set bit 0 and bit 4 in eventGroup.
  auto result = eventGroup.setFromISR(higherPriorityTaskWoken, 0b1001);
 
  // Was the message posted successfully?
  if (result) {
  }
 
  if (higherPriorityTaskWoken) {
    // If higherPriorityTaskWoken is now set to true then a context switch
    // should be requested.
    FreeRTOS::Kernel::yield();
  }
}

◆ setFromISR() [2/2]

bool FreeRTOS::EventGroupBase::setFromISR ( const EventBits & bitsToSet ) const

inline

Function that calls BaseType_t xEventGroupSetBitsFromISR( EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToSet, BaseType_t *pxHigherPriorityTaskWoken )

EventGroups.hpp

See also: https://www.freertos.org/xEventGroupSetBitsFromISR.html

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

◆ sync()

EventBits FreeRTOS::EventGroupBase::sync	(	const EventBits &	bitsToSet = `0`,
		const EventBits &	bitsToWaitFor = `0`,
		const TickType_t	ticksToWait = `portMAX_DELAY`
	)		const

inline

Function that calls EventBits_t xEventGroupSync( EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToSet, const EventBits_t uxBitsToWaitFor, TickType_t xTicksToWait )

EventGroups.hpp

See also: https://www.freertos.org/xEventGroupSync.html

Atomically set bits (flags) within an RTOS event group, then wait for a combination of bits to be set within the same event group. This functionality is typically used to synchronize multiple tasks (often called a task rendezvous), where each task has to wait for the other tasks to reach a synchronization point before proceeding.

This function cannot be used from an interrupt.

The function will return before its block time expires if the bits specified by the bitsToWait parameter are set, or become set within that time. In this case all the bits specified by bitsToWait will be automatically cleared before the function returns.

Parameters

bitsToSet	The bit or bits to set in the event group before determining if (and possibly waiting for), all the bits specified by the bitsToWait parameter are set.
bitsToWaitFor	A bitwise value that indicates the bit or bits to test inside the event group.
ticksToWait	The maximum amount of time (specified in 'ticks') to wait for all the bits specified by the uxBitsToWaitFor parameter value to become set.

Returns: EventBits

Example Usage

#include <FreeRTOS/EventGroups.hpp>
#include <FreeRTOS/Kernel.hpp>
#include <FreeRTOS/Task.hpp>
 
class MyTask0 : public FreeRTOS::Task {
 public:
  void taskFunction() final;
};
 
class MyTask1 : public FreeRTOS::Task {
 public:
  void taskFunction() final;
};
 
class MyTask2 : public FreeRTOS::Task {
 public:
  void taskFunction() final;
};
 
class TaskManager {
 private:
  MyTask0 task0;
  MyTask1 task1;
  MyTask2 task2;
};
 
FreeRTOS::StaticEventGroup eventGroup;
 
void function() {
  TaskManager manager;
  FreeRTOS::Kernel::startScheduler();
}
 
constexpr FreeRTOS::EventGroup::EventBits task_0(1 << 0);
constexpr FreeRTOS::EventGroup::EventBits task_1(1 << 1);
constexpr FreeRTOS::EventGroup::EventBits task_2(1 << 2);
const FreeRTOS::EventGroup::EventBits all_tasks(task_0 | task_1 | task_2);
 
void MyTask0::taskFunction() {
  for (;;) {
    // Perform task functionality here.
 
    // Set bit 0 in the event group to note this task has reached the sync
    // point.  The other two tasks will set the other two bits defined by
    // all_tasks.  All three tasks have reached the synchronisation point when
    // all the all_tasks are set.  Wait a maximum of 100ms for this to happen.
    auto value = eventGroup.sync(task_0, all_tasks, pdMS_TO_TICKS(100));
 
    if ((value & all_tasks) == all_tasks) {
      // All three tasks reached the synchronisation point before the call to
      // sync() timed out.
    }
  }
}
 
void MyTask1::taskFunction() {
  for (;;) {
    // Perform task functionality here.
 
    // Set bit 1 in the event group to note this task has reached the
    // synchronisation point.  The other two tasks will set the other two bits
    // defined by all_tasks.  All three tasks have reached the synchronisation
    // point when all the all_tasks are set.  Wait indefinitely for this to
    // happen.
    eventGroup.sync(task_1, all_tasks);
 
    // sync() was called with an indefinite block time, so this task will only
    // reach here if the syncrhonisation was made by all three tasks, so there
    // is no need to test the return value.
  }
}
 
void MyTask2::taskFunction() {
  for (;;) {
    // Perform task functionality here.
 
    // Set bit 2 in the event group to note this task has reached the
    // synchronisation point.  The other two tasks will set the other two bits
    // defined by all_tasks.  All three tasks have reached the synchronisation
    // point when all the all_tasks are set.  Wait indefinitely for this to
    // happen.
    eventGroup.sync(task_1, all_tasks);
 
    // sync() was called with an indefinite block time, so this task will only
    // reach here if the syncrhonisation was made by all three tasks, so there
    // is no need to test the return value.
  }
}

◆ wait()

EventBits FreeRTOS::EventGroupBase::wait	(	const EventBits &	bitsToWaitFor = `0`,
		const bool	clearOnExit = `false`,
		const bool	waitForAllBits = `false`,
		const TickType_t	ticksToWait = `portMAX_DELAY`
	)		const

inline

Function that calls EventBits_t xEventGroupWaitBits( const EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToWaitFor, const BaseType_t xClearOnExit, const BaseType_t xWaitForAllBits, TickType_t xTicksToWait )

EventGroups.hpp

See also: https://www.freertos.org/xEventGroupWaitBits.html

Read bits within an RTOS event group, optionally entering the Blocked state (with a timeout) to wait for a bit or group of bits to become set.

Warning: This function cannot be called from an interrupt.

Parameters

bitsToWaitFor	A bitwise value that indicates the bit or bits to test inside the event group. bitsToWaitFor must not be set to 0.
clearOnExit	If clearOnExit is set to true then any bits set in the value passed as the bitsToWaitFor parameter will be cleared in the event group before wait() returns if wait() returns for any reason other than a timeout. The timeout value is set by the ticksToWait parameter. If clearOnExit is set to false then the bits set in the event group are not altered when the call to wait() returns.
waitForAllBits	waitForAllBits is used to create either a logical AND test (where all bits must be set) or a logical OR test (where one or more bits must be set) as follows: If waitForAllBits is set to true then wait() will return when either all the bits set in the value passed as the bitsToWaitFor parameter are set in the event group or the specified block time expires. If waitForAllBits is set to false then wait() will return when any of the bits set in the value passed as the bitsToWaitFor parameter are set in the event group or the specified block time expires.
ticksToWait	The maximum amount of time (specified in 'ticks') to wait for one/all (depending on the waitForAllBits value) of the bits specified by bitsToWaitFor to become set.

Returns: EventBits The value of the event group at the time either the event bits being waited for became set, or the block time expired. The current value of the event bits in an event group will be different to the returned value if a higher priority task or interrupt changed the value of an event bit between the calling task leaving the Blocked state and exiting the wait() function. Test the return value to know which bits were set. If wait() returned because its timeout expired then not all the bits being waited for will be set. If wait() returned because the bits it was waiting for were set then the returned value is the event group value before any bits were automatically cleared because the clearOnExit parameter was set to true.

Example Usage

#include <FreeRTOS/EventGroups.hpp>
#include <FreeRTOS/Kernel.hpp>
#include <FreeRTOS/Task.hpp>
 
class MyTask : public FreeRTOS::Task {
 public:
  void taskFunction() final;
 
 private:
  FreeRTOS::EventGroup eventGroup;
};
 
MyTask myTask;
 
void MyTask::taskFunction() {
  FreeRTOS::EventGroup::EventBits bitsToWaitFor;
  bitsToWaitFor[0] = true;
  bitsToWaitFor[4] = true;
 
  // Wait a maximum of 100ms for either bit 0 or bit 4 to be set within the
  // event group.  Clear the bits before exiting.
  auto bits = eventGroup.wait(bitsToWaitFor, true, false, pdMS_TO_TICKS(100));
 
  if (bits[0] && bits[4]) {
    // wait() returned because both bits were set.
  } else if (bits[0]) {
    // wait() returned because just bit 0 was set.
  } else if (bits[4]) {
    // wait() returned because just bit 4 was set.
  } else {
    // wait() returned because ticksToWait ticks passed without either bit 0 or
    // bit 4 becoming set.
  }
}

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

/home/runner/work/FreeRTOS-Cpp/FreeRTOS-Cpp/FreeRTOS-Cpp/include/FreeRTOS/EventGroups.hpp

Public Types

Public Member Functions

Static Public Member Functions

Private Member Functions

Private Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

◆ EventGroupBase()

◆ ~EventGroupBase()

Member Function Documentation

◆ clear()

◆ clearFromISR()

◆ get()

◆ getFromISR()

◆ isValid()

◆ set()

◆ setFromISR() [1/2]

◆ setFromISR() [2/2]

◆ sync()

◆ wait()