Base class that provides the standard task interface to FreeRTOS::Task and FreeRTOS::StaticTask. More...

#include <FreeRTOS/Task.hpp>

Inheritance diagram for FreeRTOS::TaskBase:

Public Types
enum class	State { Running = eRunning , Ready = eReady , Blocked = eBlocked , Suspended = eSuspended , Deleted = eDeleted , Invalid = eInvalid }

enum class	NotifyAction { NoAction = eNoAction , SetBits = eSetBits , Increment = eIncrement , SetValueWithOverwrite = eSetValueWithOverwrite , SetValueWithoutOverwrite = eSetValueWithoutOverwrite }

using	NotificationBits = std::bitset< 32 >

Public Member Functions
	TaskBase (const TaskBase &)=delete

TaskBase &	operator= (const TaskBase &)=delete

virtual void	taskEntry () final
	Function that acts as the entry point of the task instance. This function initializes the previous wake time of the task and calls the user implemented taskFunction(). More...

UBaseType_t	getPriority () const
	Function that calls `UBaseType_t uxTaskPriorityGet( TaskHandle_t xTask )` More...

void	setPriority (const UBaseType_t newPriority) const
	Function that calls `void vTaskPrioritySet( TaskHandle_t xTask, UBaseType_t uxNewPriority )` More...

void	suspend () const
	Function that calls `void vTaskSuspend( TaskHandle_t xTaskToSuspend )` More...

void	resume () const
	Function that calls `void vTaskResume( TaskHandle_t xTaskToResume )` More...

bool	resumeFromISR () const
	Function that calls `BaseType_t xTaskResumeFromISR( TaskHandle_t xTaskToResume )` More...

bool	abortDelay () const
	Function that calls `BaseType_t xTaskAbortDelay( TaskHandle_t xTask )` More...

UBaseType_t	getStackHighWaterMark () const
	Function that calls `UBaseType_t uxTaskGetStackHighWaterMark( TaskHandle_t xTask )` More...

configSTACK_DEPTH_TYPE	getStackHighWaterMark2 () const
	Function that calls `UBaseType_t uxTaskGetStackHighWaterMark2( TaskHandle_t xTask )` More...

State	getState () const
	Function that calls `UBaseType_t uxTaskGetStackHighWaterMark2( TaskHandle_t xTask )` More...

const char *	getName () const
	Function that calls `char *pcTaskGetName( TaskHandle_t xTaskToQuery )` More...

void	notifyGive (const UBaseType_t index=0) const
	Function that calls `BaseType_t xTaskNotifyGiveIndexed( TaskHandle_t xTaskToNotify, UBaseType_t uxIndexToNotify )` More...

void	notifyGiveFromISR (bool &higherPriorityTaskWoken, const UBaseType_t index=0) const
	Function that calls `void vTaskNotifyGiveIndexedFromISR( TaskHandle_t xTaskHandle, UBaseType_t uxIndexToNotify, BaseType_t *pxHigherPriorityTaskWoken )` More...

void	notifyGiveFromISR (const UBaseType_t index=0) const
	Function that calls `void vTaskNotifyGiveIndexedFromISR( TaskHandle_t xTaskHandle, UBaseType_t uxIndexToNotify, BaseType_t *pxHigherPriorityTaskWoken )` More...

bool	notify (const NotifyAction action, const NotificationBits value=0, const UBaseType_t index=0) const
	Function that calls `BaseType_t xTaskNotifyIndexed( TaskHandle_t xTaskToNotify, UBaseType_t uxIndexToNotify, uint32_t ulValue, eNotifyAction eAction )` More...

std::pair< bool, NotificationBits >	notifyAndQuery (const NotifyAction action, const NotificationBits value=0, const UBaseType_t index=0) const
	Function that calls `BaseType_t xTaskNotifyAndQueryIndexed( TaskHandle_t xTaskToNotify, UBaseType_t uxIndexToNotify, uint32_t ulValue, eNotifyAction eAction, uint32_t *pulPreviousNotifyValue )` More...

std::pair< bool, NotificationBits >	notifyAndQueryFromISR (bool &higherPriorityTaskWoken, const NotifyAction action, const NotificationBits value=0, const UBaseType_t index=0) const
	Function that calls `BaseType_t xTaskNotifyAndQueryIndexedFromISR( TaskHandle_t xTaskToNotify, UBaseType_t uxIndexToNotify, uint32_t ulValue, eNotifyAction eAction, uint32_t pulPreviousNotifyValue, BaseType_t pxHigherPriorityTaskWoken )` More...

std::pair< bool, NotificationBits >	notifyAndQueryFromISR (const NotifyAction action, const NotificationBits value=0, const UBaseType_t index=0) const
	Function that calls `BaseType_t xTaskNotifyAndQueryIndexedFromISR( TaskHandle_t xTaskToNotify, UBaseType_t uxIndexToNotify, uint32_t ulValue, eNotifyAction eAction, uint32_t pulPreviousNotifyValue, BaseType_t pxHigherPriorityTaskWoken )` More...

bool	notifyFromISR (bool &higherPriorityTaskWoken, const NotifyAction action, const NotificationBits value=0, const UBaseType_t index=0) const
	Function that calls `BaseType_t xTaskNotifyIndexedFromISR( TaskHandle_t xTaskToNotify, UBaseType_t uxIndexToNotify, uint32_t ulValue, eNotifyAction eAction, BaseType_t *pxHigherPriorityTaskWoken )` More...

bool	notifyFromISR (const NotifyAction action, const NotificationBits value=0, const UBaseType_t index=0) const
	Function that calls `BaseType_t xTaskNotifyIndexedFromISR( TaskHandle_t xTaskToNotify, UBaseType_t uxIndexToNotify, uint32_t ulValue, eNotifyAction eAction, BaseType_t *pxHigherPriorityTaskWoken )` More...

bool	notifyStateClear (const UBaseType_t index=0) const
	Function that calls `BaseType_t xTaskNotifyStateClearIndexed( TaskHandle_t xTask, UBaseType_t uxIndexToClear )` More...

NotificationBits	notifyValueClear (const NotificationBits bitsToClear=0, const UBaseType_t index=0) const
	Function that calls `uint32_t ulTaskNotifyValueClearIndexed( TaskHandle_t xTask, UBaseType_t uxIndexToClear, uint32_t ulBitsToClear )` More...

Static Public Member Functions
static void *	operator new (size_t, void *ptr)

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

static void *	operator new (size_t)=delete

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

static TaskHandle_t	getIdleHandle ()
	Function that calls `TaskHandle_t xTaskGetIdleTaskHandle( void )` More...

static TaskHandle_t	getHandle (const char *name)
	Function that calls `TaskHandle_t xTaskGetHandle( const char *pcNameToQuery )` More...

static std::pair< bool, NotificationBits >	notifyWait (const TickType_t ticksToWait=portMAX_DELAY, const NotificationBits bitsToClearOnEntry=0, const NotificationBits bitsToClearOnExit=0, const UBaseType_t index=0)
	Function that calls `BaseType_t xTaskNotifyWaitIndexed( UBaseType_t uxIndexToWaitOn, uint32_t ulBitsToClearOnEntry, uint32_t ulBitsToClearOnExit, uint32_t *pulNotificationValue, TickType_t xTicksToWait )` More...

Protected Member Functions
virtual void	taskFunction ()=0
	Abstraction function that acts as the entry point of the task for the user. More...

bool	delayUntil (const TickType_t timeIncrement=0)
	Function that calls `BaseType_t xTaskDelayUntil( TickType_t *pxPreviousWakeTime, const TickType_t xTimeIncrement )` More...

Static Protected Member Functions
static void	delay (const TickType_t ticksToDelay=0)
	Function that calls `void vTaskDelay( const TickType_t xTicksToDelay )` More...

static NotificationBits	notifyTake (const TickType_t ticksToWait=portMAX_DELAY, const bool clearCountOnExit=true, const UBaseType_t index=0)
	Function that calls `uint32_t ulTaskNotifyTakeIndexed( UBaseType_t uxIndexToWaitOn, BaseType_t xClearCountOnExit, TickType_t xTicksToWait )` More...

Private Member Functions
	TaskBase ()=default
	Construct a new TaskBase object. This default constructor is deliberately private as this class is not intended to be instantiated or derived from by the user. Use FreeRTOS::Task or FreeRTOS::StaticTask as a base class for creating a task.

	TaskBase (TaskBase &&) noexcept=default

TaskBase &	operator= (TaskBase &&) noexcept=default

	~TaskBase ()
	Destroy the Task object. More...

Private Attributes
TaskHandle_t	handle = NULL
	Handle used to refer to the task when using the FreeRTOS interface.

TickType_t	previousWakeTime = 0
	Variable that holds the time at which the task was last unblocked.

Friends
class	Task

template<UBaseType_t >
class	StaticTask

Detailed Description

Base class that provides the standard task interface to FreeRTOS::Task and FreeRTOS::StaticTask.

Note: This class is not intended to be instantiated or derived from by the user. Use FreeRTOS::Task or FreeRTOS::StaticTask as a base class for a user implemented task.

Constructor & Destructor Documentation

◆ ~TaskBase()

FreeRTOS::TaskBase::~TaskBase ( )

inlineprivate

Destroy the Task object.

Task.hpp

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

If INCLUDE_vTaskDelete is defined as 1 and the task handle is not NULL, then the destructor will call void vTaskDelete( TaskHandle_t xTask ) See the RTOS Configuration documentation for more information.

Calling void vTaskDelete( TaskHandle_t xTask ) will remove a task from the RTOS kernels management. The task being deleted will be removed from all ready, blocked, suspended and event lists.

Note: The idle task is responsible for freeing the RTOS kernel allocated memory from tasks that have been deleted. It is therefore important that the idle task is not starved of microcontroller processing time if your application makes any calls to void vTaskDelete( TaskHandle_t xTask ) Memory allocated by the task code is not automatically freed, and should be freed before the task is deleted.

Example Usage

#include <FreeRTOS/Task.hpp>
 
class MyTask : public FreeRTOS::Task {
 public:
  MyTask(const UBaseType_t priority, const char* name)
      : FreeRTOS::Task(priority, configMINIMAL_STACK_SIZE, name) {}
  void taskFunction() final;
};
 
// Task to be created.
void MyTask::taskFunction() {
  for (;;) {
    // Task code goes here.
  }
}
 
// Function that creates a task.
void aFunction() {
  // Create the task.
  MyTask task((tskIDLE_PRIORITY + 1), "NAME");
 
  // Check that the task was created successfully.
  if (task.isValid()) {
    // Start the scheduler.
    FreeRTOS::Kernel::startScheduler();
  }
 
  // Task will be destroyed when the scheduler is stopped and this function
  // returns.
}

Member Function Documentation

◆ abortDelay()

bool FreeRTOS::TaskBase::abortDelay ( ) const

inline

Function that calls BaseType_t xTaskAbortDelay( TaskHandle_t xTask )

Task.hpp

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

INCLUDE_xTaskAbortDelay must be defined as 1 in FreeRTOSConfig.h for this function to be available.

A task will enter the Blocked state when it is waiting for an event. The event it is waiting for can be a temporal event (waiting for a time), such as when delay() is called, or an event on an object, such as when FreeRTOS::Queue::receive() or notifyTake() is called. If the handle of a task that is in the Blocked state is used in a call to abortDelay() then the task will leave the Blocked state, and return from whichever function call placed the task into the Blocked state.

There is no 'FromISR' version of this function as an interrupt would need to know which object a task was blocked on in order to know which actions to take. For example, if the task was blocked on a queue the interrupt handler would then need to know if the queue was locked.

Return values

true	Otherwise.
false	If the task was not in the Blocked state.

◆ delay()

static void FreeRTOS::TaskBase::delay ( const TickType_t ticksToDelay = 0 )

inlinestaticprotected

Function that calls void vTaskDelay( const TickType_t xTicksToDelay )

Task.hpp

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

INCLUDE_vTaskDelay must be defined as 1 for this function to be available. See the configuration section for more information.

Delay a task for a given number of ticks. The actual time that the task remains blocked depends on the tick rate. The constant portTICK_PERIOD_MS can be used to calculate real time from the tick rate - with the resolution of one tick period.

delay() specifies a time at which the task wishes to unblock relative to the time at which delay() is called. For example, specifying a block period of 100 ticks will cause the task to unblock 100 ticks after delay() is called. delay() does not therefore provide a good method of controlling the frequency of a periodic task as the path taken through the code, as well as other task and interrupt activity, will affect the frequency at which delay() gets called and therefore the time at which the task next executes. See delayUntil() for an alternative API function designed to facilitate fixed frequency execution. It does this by specifying an absolute time (rather than a relative time) at which the calling task should unblock.

Parameters

ticksToDelay The amount of time, in tick periods, that the task should block.

Example Usage

#include <FreeRTOS/Task.hpp>
 
class MyTask : public FreeRTOS::Task {
 public:
  void taskFunction() final;
 
 private:
  void toggleLED() {}
};
 
void MyTask::taskFunction() {
  // Block for 500ms.
  constexpr TickType_t xDelay = 500 / portTICK_PERIOD_MS;
 
  for (;;) {
    // Simply toggle the LED every 500ms, blocking between each toggle.
    toggleLED();
    delay(xDelay);
  }
}

◆ delayUntil()

bool FreeRTOS::TaskBase::delayUntil ( const TickType_t timeIncrement = 0 )

inlineprotected

Function that calls BaseType_t xTaskDelayUntil( TickType_t *pxPreviousWakeTime, const TickType_t xTimeIncrement )

Task.hpp

See also: https://www.freertos.org/xtaskdelayuntiltask-control.html

INCLUDE_xTaskDelayUntil must be defined as 1 for this function to be available. See the configuration section for more information.

Delay a task until a specified time. This function can be used by periodic tasks to ensure a constant execution frequency.

This function differs from delay() in one important aspect: delay() will cause a task to block for the specified number of ticks from the time delay () is called. It is therefore difficult to use delay() by itself to generate a fixed execution frequency as the time between a task starting to execute and that task calling delay() may not be fixed [the task may take a different path though the code between calls, or may get interrupted or preempted a different number of times each time it executes].

Whereas delay() specifies a wake time relative to the time at which the function is called, delayUntil() specifies the absolute (exact) time at which it wishes to unblock.

The function pdMS_TO_TICKS() can be used to calculate the number of ticks from a time specified in milliseconds with a resolution of one tick period.

Parameters

timeIncrement The cycle time period. The task will be unblocked at time (previousWakeTime + timeIncrement). Calling delayUntil() with the same timeIncrement parameter value will cause the task to execute with a fixed interval period.

Returns: true If the task way delayed.; false Otherwise. A task will not be delayed if the next expected wake time is in the past.

Example Usage

#include <FreeRTOS/Task.hpp>
 
class MyTask : public FreeRTOS::Task {
 public:
  void taskFunction() final;
};
 
void MyTask::taskFunction() {
  // Perform an action every 10 ticks.
  constexpr TickType_t xFrequency = 10;
 
  for (;;) {
    // Wait for the next cycle.
    auto wasDelayed = delayUntil(xFrequency);
 
    // Perform action here. wasDelayed value can be used to determine
    // whether a deadline was missed if the code here took too long.
    if (wasDelayed) {
      // Check for deadline miss.
    }
  }
}

◆ getHandle()

static TaskHandle_t FreeRTOS::TaskBase::getHandle ( const char * name )

inlinestatic

Function that calls TaskHandle_t xTaskGetHandle( const char *pcNameToQuery )

Task.hpp

See also: https://www.freertos.org/a00021.html#xTaskGetHandle

Note: This function takes a relatively long time to complete and should be used sparingly.

Parameters

name	The text name (as a standard C NULL terminated string) of the task for which the handle will be returned.

Returns: TaskHandle_t The handle of the task that has the human readable name. NULL is returned if no matching name is found. INCLUDE_xTaskGetHandle must be set to 1 in FreeRTOSConfig.h for getHandle() to be available.

◆ getIdleHandle()

static TaskHandle_t FreeRTOS::TaskBase::getIdleHandle ( )

inlinestatic

Function that calls TaskHandle_t xTaskGetIdleTaskHandle( void )

Task.hpp

See also: https://www.freertos.org/a00021.html#xTaskGetIdleTaskHandle

getIdleTaskHandle() is only available if INCLUDE_xTaskGetIdleTaskHandle is set to 1 in FreeRTOSConfig.h.

Simply returns the handle of the idle task. It is not valid to call getIdleTaskHandle() before the scheduler has been started.

Returns: TaskHandle_t The task handle associated with the Idle task. The Idle task is created automatically when the RTOS scheduler is started.

◆ getName()

const char* FreeRTOS::TaskBase::getName ( ) const

inline

Function that calls char *pcTaskGetName( TaskHandle_t xTaskToQuery )

Task.hpp

See also: https://www.freertos.org/a00021.html#pcTaskGetName

Looks up the name of a task.

Returns: const char* The text (human readable) name of the task. A pointer to the subject task's name, which is a standard NULL terminated C string.

◆ getPriority()

UBaseType_t FreeRTOS::TaskBase::getPriority ( ) const

inline

Function that calls UBaseType_t uxTaskPriorityGet( TaskHandle_t xTask )

Task.hpp

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

INCLUDE_uxTaskPriorityGet must be defined as 1 for this function to be available. See the RTOS Configuration documentation for more information.

Obtain the priority of any task.

Returns: UBaseType_t The priority of the task.

Example Usage

#include <FreeRTOS/Task.hpp>
 
// Define a task that requries the priority to be specified.
class MyTask : public FreeRTOS::Task {
 public:
  explicit MyTask(UBaseType_t priority) : FreeRTOS::Task(priority) {}
  void taskFunction() final;
};
 
// Define a task that uses the default task priority.
class MyDifferentTask : public FreeRTOS::Task {
 public:
  void taskFunction() final;
};
 
MyTask myTask(tskIDLE_PRIORITY);
 
MyDifferentTask myDifferentTask;
 
void MyTask::taskFunction() {
  // Some code that may change the priority.
 
  // Obtain the priority of the this task.  It was created with
  // tskIDLE_PRIORITY, but it may have been changed.
  if (getPriority() != tskIDLE_PRIORITY) {
    // This task has changed priority.
  }
}
 
void MyDifferentTask::taskFunction() {
  // Obtain the priority of myTask.  It was created with tskIDLE_PRIORITY, but
  // it may have been changed.
  if (myTask.getPriority() != tskIDLE_PRIORITY) {
    // myTask has changed priority.
  }
}

◆ getStackHighWaterMark()

UBaseType_t FreeRTOS::TaskBase::getStackHighWaterMark ( ) const

inline

Function that calls UBaseType_t uxTaskGetStackHighWaterMark( TaskHandle_t xTask )

Task.hpp

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

INCLUDE_uxTaskGetStackHighWaterMark must be set to 1 in FreeRTOSConfig.h for this function to be available.

Returns the high water mark of the stack. That is, the minimum free stack space there has been (in words, so on a 32 bit machine a value of 1 means 4 bytes) since the task started. The smaller the returned number the closer the task has come to overflowing its stack.

getStackHighWaterMark() and getStackHighWaterMark2() are the same except for their return type. Using configSTACK_DEPTH_TYPE allows the user to determine the return type. It gets around the problem of the value overflowing on 8-bit types without breaking backward compatibility for applications that expect an 8-bit return type.

Returns: BaseType_t The smallest amount of free stack space there has been (in words, so actual spaces on the stack rather than bytes) since the task was created.

◆ getStackHighWaterMark2()

configSTACK_DEPTH_TYPE FreeRTOS::TaskBase::getStackHighWaterMark2 ( ) const

inline

Function that calls UBaseType_t uxTaskGetStackHighWaterMark2( TaskHandle_t xTask )

Task.hpp

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

Returns the high water mark of the stack. That is, the minimum free stack space there has been (in words, so on a 32 bit machine a value of 1 means 4 bytes) since the task started. The smaller the returned number the closer the task has come to overflowing its stack.

getStackHighWaterMark() and getStackHighWaterMark2() are the same except for their return type. Using configSTACK_DEPTH_TYPE allows the user to determine the return type. It gets around the problem of the value overflowing on 8-bit types without breaking backward compatibility for applications that expect an 8-bit return type.

Returns: configSTACK_DEPTH_TYPE The smallest amount of free stack space there has been (in words, so actual spaces on the stack rather than bytes) since the task was created.

◆ getState()

State FreeRTOS::TaskBase::getState ( ) const

inline

Function that calls UBaseType_t uxTaskGetStackHighWaterMark2( TaskHandle_t xTask )

Task.hpp

See also: https://www.freertos.org/a00021.html#eTaskGetState; getInfo()

INCLUDE_eTaskGetState must be defined as 1 for this function to be available. See the configuration section for more information.

Obtain the state of any task. States are encoded by the FreeRTOS::Task::State enumerated class type.

Returns: State The state of the task at the time the function was called. Note the state of the task might change between the function being called, and the functions return value being tested by the calling task.

◆ notify()

bool FreeRTOS::TaskBase::notify	(	const NotifyAction	action,
		const NotificationBits	value = `0`,
		const UBaseType_t	index = `0`
	)		const

inline

Function that calls BaseType_t xTaskNotifyIndexed( TaskHandle_t xTaskToNotify, UBaseType_t uxIndexToNotify, uint32_t ulValue, eNotifyAction eAction )

Task.hpp

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

configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for these functions to be available.

Each task has a private array of "notification values" (or 'notifications'), each of which is a 32-bit unsigned integer (uint32_t). The constant configTASK_NOTIFICATION_ARRAY_ENTRIES sets the number of indexes in the array, and (for backward compatibility) defaults to 1 if left undefined. Prior to FreeRTOS V10.4.0 there was only one notification value per task.

Events can be sent to a task using an intermediary object. Examples of such objects are queues, semaphores, mutexes and event groups. Task notifications are a method of sending an event directly to a task without the need for such an intermediary object.

A notification sent to a task can optionally perform an action, such as update, overwrite or increment one of the task's notification values. In that way task notifications can be used to send data to a task, or be used as light weight and fast binary or counting semaphores.

A task can use notifyWait() or notifyTake() to [optionally] block to wait for a notification to be pending. The task does not consume any CPU time while it is in the Blocked state.

A notification sent to a task will remain pending until it is cleared by the task calling notifyWait() or notifyTake(). If the task was already in the Blocked state to wait for a notification when the notification arrives then the task will automatically be removed from the Blocked state (unblocked) and the notification cleared.

Note: Each notification within the array operates independently - a task can only block on one notification within the array at a time and will not be unblocked by a notification sent to any other array index.

Parameters

action

Specifies how the notification updates the task's notification value, if at all. Valid values for action are as follows:

NotifyAction Setting	Action Performed
NoAction	The target task receives the event, but its notification value is not updated. In this case value is not used.
SetBits	The notification value of the target task will be bitwise ORed with value. For example, if value is set to 0x01, then bit 0 will get set within the target task's notification value. Likewise if value is 0x04 then bit 2 will get set in the target task's notification value. In this way the RTOS task notification mechanism can be used as a light weight alternative to an event group.
Increment	The notification value of the target task will be incremented by one, making the call to notify() equivalent to a call to notifyGive(). In this case value is not used.
SetValueWithOverwrite	The notification value of the target task is unconditionally set to value. In this way the RTOS task notification mechanism is being used as a light weight alternative to FreeRTOS::Queue::Overwrite().
SetValueWithoutOverwrite	If the target task does not already have a notification pending then its notification value will be set to value. If the target task already has a notification pending then its notification value is not updated as to do so would overwrite the previous value before it was used. In this case the call to notify() fails and false is returned. In this way the RTOS task notification mechanism is being used as a light weight alternative to FreeRTOS::Queue::send() on a queue of length 1.

value Data that can be sent with the notification. How the data is used depends on the value of the action parameter.

index The index within the target task's array of notification values to which the notification is to be sent. index must be less than configTASK_NOTIFICATION_ARRAY_ENTRIES.

Returns: false If action is set to SetValueWithoutOverwrite and the task's notification value cannot be updated because the target task already had a notification pending.; true Otherwise.

Example Usage

#include <FreeRTOS/Task.hpp>
 
class MyTask : public FreeRTOS::Task {
 public:
  void taskFunction() final;
};
 
void MyTask::taskFunction() {
  for (;;) {
    // ...
  }
}
 
MyTask task1;
MyTask task2;
MyTask task3;
MyTask task4;
 
void aFunction() {
  // Set bit 8 in the 0th notification value of task1.
  task1.notify(FreeRTOS::Task::NotifyAction::SetBits, (1UL << 8UL));
 
  // Send a notification to task2, potentially removing the task from the
  // Blocked state, but without updating the task's notification value.
  task2.notify(FreeRTOS::Task::NotifyAction::NoAction);
 
  // Set the notification value of task3 to 0x50, even if the task had not read
  // its previous notification value.
  task3.notify(FreeRTOS::Task::NotifyAction::SetValueWithOverwrite, 0x50);
 
  // Set the notification value of task4 to 0xfff, but only if to do so would
  // not overwrite the task's existing notification value before the task had
  // obtained it (by a call to notifyWait() or notifyTake()).
  if (task4.notify(FreeRTOS::Task::NotifyAction::SetValueWithoutOverwrite,
                   0xfff)) {
    // The task's notification value was updated.
  } else {
    // The task's notification value was not updated.
  }
}

◆ notifyAndQuery()

std::pair<bool, NotificationBits> FreeRTOS::TaskBase::notifyAndQuery	(	const NotifyAction	action,
		const NotificationBits	value = `0`,
		const UBaseType_t	index = `0`
	)		const

inline

Function that calls BaseType_t xTaskNotifyAndQueryIndexed( TaskHandle_t xTaskToNotify, UBaseType_t uxIndexToNotify, uint32_t ulValue, eNotifyAction eAction, uint32_t *pulPreviousNotifyValue )

Task.hpp

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

notifyAndQuery() performs the same operation as notify() with the addition that it also returns the target task's prior notification value (the notification value at the time the function is called rather than when the function returns).

Parameters

action

An enumerated type that can take one of the values documented in the table below in order to perform the associated action.

NotifyAction Setting	Action Performed
NoAction	The target task receives the event, but its notification value is not updated. In this case value is not used.
SetBits	The notification value of the target task will be bitwise ORed with value. For example, if value is set to 0x01, then bit 0 will get set within the target task's notification value. Likewise if value is 0x04 then bit 2 will get set in the target task's notification value. In this way the RTOS task notification mechanism can be used as a light weight alternative to an event group.
Increment	The notification value of the target task will be incremented by one, making the call to notify() equivalent to a call to notifyGive(). In this case value is not used.
SetValueWithOverwrite	The notification value of the target task is unconditionally set to value. In this way the RTOS task notification mechanism is being used as a light weight alternative to FreeRTOS::Queue::Overwrite().
SetValueWithoutOverwrite	If the target task does not already have a notification pending then its notification value will be set to value. If the target task already has a notification pending then its notification value is not updated as to do so would overwrite the previous value before it was used. In this case the call to notify() fails and false is returned. In this way the RTOS task notification mechanism is being used as a light weight alternative to FreeRTOS::Queue::send() on a queue of length 1.

value Used to update the notification value of the task. See the description of the action parameter below.

index The index within the target task's array of notification values to which the notification is to be sent. index must be less than configTASK_NOTIFICATION_ARRAY_ENTRIES.

Returns: false If action is set to SetValueWithoutOverwrite and the task's notification value cannot be updated because the target task already had a notification pending.; true Otherwise.

Example Usage

#include <FreeRTOS/Task.hpp>
 
class MyTask : public FreeRTOS::Task {
 public:
  void taskFunction() final;
};
 
void MyTask::taskFunction() {
  for (;;) {
    // ...
  }
}
 
MyTask task1;
MyTask task2;
MyTask task3;
MyTask task4;
 
void aFunction() {
  using namespace FreeRTOS;
 
  Task::NotificationBits previousValue;
 
  // Set bit 8 in the 0th notification value of task1.  Store the task's
  // previous 0th notification value (before bit 8 is set) in previousValue.
  previousValue =
      task1.notifyAndQuery(Task::NotifyAction::SetBits, (1UL << 8UL)).second;
 
  // Send a notification to task2, potentially removing the task from the
  // Blocked state, but without updating the task's notification value.  Store
  // the tasks notification value in previousValue.
  previousValue = task2.notifyAndQuery(Task::NotifyAction::NoAction).second;
 
  // Set the notification value of task3 to 0x50, even if the task had not read
  // its previous notification value. The task's previous notification value is
  // of no interest.
  task3.notifyAndQuery(Task::NotifyAction::SetValueWithOverwrite, 0x50);
 
  // Set the notification value of task4 to 0xfff, but only if to do so would
  // not overwrite the task's existing notification value before the task had
  // obtained it (by a call to notifyWait() or notifyTake()).
  if (task4.notifyAndQuery(Task::NotifyAction::SetValueWithoutOverwrite, 0xfff)
          .first) {
    // The task's notification value was updated.
  } else {
    // The task's notification value was not updated.
  }
}

◆ notifyAndQueryFromISR() [1/2]

std::pair<bool, NotificationBits> FreeRTOS::TaskBase::notifyAndQueryFromISR	(	bool &	higherPriorityTaskWoken,
		const NotifyAction	action,
		const NotificationBits	value = `0`,
		const UBaseType_t	index = `0`
	)		const

inline

Function that calls BaseType_t xTaskNotifyAndQueryIndexedFromISR( TaskHandle_t xTaskToNotify, UBaseType_t uxIndexToNotify, uint32_t ulValue, eNotifyAction eAction, uint32_t *pulPreviousNotifyValue, BaseType_t *pxHigherPriorityTaskWoken )

Task.hpp

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

notifyAndQueryFromISR() performs the same operation as notifyFromISR() with the addition that it also returns the target task's prior notification value (the notification value at the time the function is called rather than at the time the function returns).

Parameters

higherPriorityTaskWoken A reference that will be set to true if sending the notification caused a task to unblock, and the unblocked task has a priority higher than the currently running task. If higherPriorityTaskWoken is set to true, then a context switch should be requested before the interrupt is exited.

action

An enumerated type that can take one of the values documented in the table below in order to perform the associated action.

NotifyAction Setting	Action Performed
NoAction	The target task receives the event, but its notification value is not updated. In this case value is not used.
SetBits	The notification value of the target task will be bitwise ORed with value. For example, if value is set to 0x01, then bit 0 will get set within the target task's notification value. Likewise if value is 0x04 then bit 2 will get set in the target task's notification value. In this way the RTOS task notification mechanism can be used as a light weight alternative to an event group.
Increment	The notification value of the target task will be incremented by one, making the call to notify() equivalent to a call to notifyGive(). In this case value is not used.
SetValueWithOverwrite	The notification value of the target task is unconditionally set to value. In this way the RTOS task notification mechanism is being used as a light weight alternative to FreeRTOS::Queue::Overwrite().
SetValueWithoutOverwrite	If the target task does not already have a notification pending then its notification value will be set to value. If the target task already has a notification pending then its notification value is not updated as to do so would overwrite the previous value before it was used. In this case the call to notify() fails and false is returned. In this way the RTOS task notification mechanism is being used as a light weight alternative to FreeRTOS::Queue::send() on a queue of length 1.

value Used to update the notification value of the task. See the description of the action parameter below.

index The index within the target task's array of notification values to which the notification is to be sent. index must be less than configTASK_NOTIFICATION_ARRAY_ENTRIES.

Return values

false	If action is set to SetValueWithoutOverwrite and the task's notification value cannot be updated because the target task already had a notification pending.
true	Otherwise.

Returns: NotificationBits The task's notification value before any bits are modified.

Example Usage

#include <FreeRTOS/Kernel.hpp>
#include <FreeRTOS/Task.hpp>
 
class MyTask : public FreeRTOS::Task {
 public:
  void taskFunction() final;
};
 
MyTask myTask;
 
void MyTask::taskFunction() {
  for (;;) {
    // ...
  }
}
 
void anISR() {
  bool higherPriorityTaskWoken = false;
 
  // Set bit 8 in the 0th notification value. Store the task's previous 0th
  // notification value (before bit 8 is set).
  auto [updated, previousValue] = myTask.notifyAndQueryFromISR(
      higherPriorityTaskWoken, FreeRTOS::Task::NotifyAction::SetBits,
      (1UL << 8UL));
 
  // The task's previous notification value is saved in previousValue.
 
  // If the task was in the Blocked state, waiting for the notification, then it
  // will now have been moved from the Blocked state to the Ready state.  If its
  // priority is higher than the priority of the currently executing task (the
  // task this interrupt interrupted) then higherPriorityTaskWoken will have
  // been set to true, and passing the variable into a call to
  // FreeRTOS::Kernel::yield() will result in the interrupt returning directly
  // to the unblocked task.
  if (higherPriorityTaskWoken) {
    FreeRTOS::Kernel::yield();
  }
}

◆ notifyAndQueryFromISR() [2/2]

std::pair<bool, NotificationBits> FreeRTOS::TaskBase::notifyAndQueryFromISR	(	const NotifyAction	action,
		const NotificationBits	value = `0`,
		const UBaseType_t	index = `0`
	)		const

inline

Function that calls BaseType_t xTaskNotifyAndQueryIndexedFromISR( TaskHandle_t xTaskToNotify, UBaseType_t uxIndexToNotify, uint32_t ulValue, eNotifyAction eAction, uint32_t *pulPreviousNotifyValue, BaseType_t *pxHigherPriorityTaskWoken )

Task.hpp

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

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

◆ notifyFromISR() [1/2]

bool FreeRTOS::TaskBase::notifyFromISR	(	bool &	higherPriorityTaskWoken,
		const NotifyAction	action,
		const NotificationBits	value = `0`,
		const UBaseType_t	index = `0`
	)		const

inline

Function that calls BaseType_t xTaskNotifyIndexedFromISR( TaskHandle_t xTaskToNotify, UBaseType_t uxIndexToNotify, uint32_t ulValue, eNotifyAction eAction, BaseType_t *pxHigherPriorityTaskWoken )

Task.hpp

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

Version of notify() that can be used from an interrupt service routine (ISR). See the documentation page for the notify() API function for a description of their operation and the necessary configuration parameters, as well as backward compatibility information.

Parameters

higherPriorityTaskWoken A reference that will be set to true if sending the notification caused a task to unblock, and the unblocked task has a priority higher than the currently running task. If higherPriorityTaskWoken is set to true, then a context switch should be requested before the interrupt is exited.

action

An enumerated type that can take one of the values documented in the table below in order to perform the associated action.

NotifyAction Setting	Action Performed
NoAction	The target task receives the event, but its notification value is not updated. In this case value is not used.
SetBits	The notification value of the target task will be bitwise ORed with value. For example, if value is set to 0x01, then bit 0 will get set within the target task's notification value. Likewise if value is 0x04 then bit 2 will get set in the target task's notification value. In this way the RTOS task notification mechanism can be used as a light weight alternative to an event group.
Increment	The notification value of the target task will be incremented by one, making the call to notify() equivalent to a call to notifyGive(). In this case value is not used.
SetValueWithOverwrite	The notification value of the target task is unconditionally set to value. In this way the RTOS task notification mechanism is being used as a light weight alternative to FreeRTOS::Queue::Overwrite().
SetValueWithoutOverwrite	If the target task does not already have a notification pending then its notification value will be set to value. If the target task already has a notification pending then its notification value is not updated as to do so would overwrite the previous value before it was used. In this case the call to notify() fails and false is returned. In this way the RTOS task notification mechanism is being used as a light weight alternative to FreeRTOS::Queue::send() on a queue of length 1.

value Used to update the notification value of the task. See the description of the action parameter below.

index The index within the target task's array of notification values to which the notification is to be sent. index must be less than configTASK_NOTIFICATION_ARRAY_ENTRIES.

Return values

false	If action is set to SetValueWithoutOverwrite and the task's notification value cannot be updated because the target task already had a notification pending.
true	Otherwise.

Example Usage This example demonstrates how to use notifyFromISR() with the SetBits action. See the notify() API documentation page for examples showing how to use the NoAction, SetValueWithOverwrite and SetValueWithoutOverwrite actions.

#include <FreeRTOS/Kernel.hpp>
#include <FreeRTOS/Task.hpp>
 
class MyTask : public FreeRTOS::Task {
 public:
  void taskFunction() final;
 
 private:
  void prvProcessRxInterrupt() {}
  void prvProcessTxInterrupt() {}
  void prvClearBufferOverrun() {}
};
 
// Fake peripherial interface functions.
uint32_t ulReadPeripheralInterruptStatus() { return 0; }
void vClearPeripheralInterruptStatus(uint32_t ulStatusRegister) {}
 
MyTask myTask;
 
// The interrupt handler does not perform any processing itself.  Instead it
// unblocks a high priority task in which the events that generated the
// interrupt are processed.  If the priority of the task is high enough then the
// interrupt will return directly to the task (so it will interrupt one task but
// return to a different task), so the processing will occur contiguously in
// time - just as if all the processing had been done in the interrupt handler
// itself. The status of the interrupting peripheral is sent to the task using
// an RTOS task notification.
void anInterruptHandler() {
  bool higherPriorityTaskWoken = false;
 
  // Read the interrupt status register which has a bit for each interrupt
  // source (for example, maybe an Rx bit, a Tx bit, a buffer overrun bit, etc.
  uint32_t ulStatusRegister = ulReadPeripheralInterruptStatus();
 
  // Clear the interrupts.
  vClearPeripheralInterruptStatus(ulStatusRegister);
 
  // Unblock the task so the task can perform any processing necessitated by the
  // interrupt.  The task's 0th notification value is bitwise ORed with the
  // interrupt status - ensuring bits that are already set are not overwritten.
  myTask.notifyFromISR(higherPriorityTaskWoken,
                       FreeRTOS::Task::NotifyAction::SetBits, ulStatusRegister);
 
  if (higherPriorityTaskWoken) {
    // Force a context switch if higherPriorityTaskWoken is true.
    FreeRTOS::Kernel::yield();
  }
}
 
// A task that blocks waiting to be notified that the peripheral needs
// servicing, processing all the events pending in the peripheral each time it
// is notified to do so.
void MyTask::taskFunction() {
  for (;;) {
    // Block indefinitely (without a timeout, so no need to check the function's
    // return value) to wait for a notification.  NOTE!  Real applications
    // should not block indefinitely, but instead time out occasionally in order
    // to handle error conditions that may prevent the interrupt from sending
    // any more notifications.
    auto interruptStatus = std::get<1>(notifyWait());
 
    // Process any bits set in the received notification value.  This assumes
    // the peripheral sets bit 0 for an Rx interrupt, bit 1 for a Tx interrupt,
    // and bit 2 for a buffer overrun interrupt.
    if (interruptStatus[0]) {
      prvProcessRxInterrupt();
    }
 
    if (interruptStatus[1]) {
      prvProcessTxInterrupt();
    }
 
    if (interruptStatus[2]) {
      prvClearBufferOverrun();
    }
  }
}

◆ notifyFromISR() [2/2]

bool FreeRTOS::TaskBase::notifyFromISR	(	const NotifyAction	action,
		const NotificationBits	value = `0`,
		const UBaseType_t	index = `0`
	)		const

inline

Function that calls BaseType_t xTaskNotifyIndexedFromISR( TaskHandle_t xTaskToNotify, UBaseType_t uxIndexToNotify, uint32_t ulValue, eNotifyAction eAction, BaseType_t *pxHigherPriorityTaskWoken )

Task.hpp

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

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

◆ notifyGive()

void FreeRTOS::TaskBase::notifyGive ( const UBaseType_t index = 0 ) const

inline

Function that calls BaseType_t xTaskNotifyGiveIndexed( TaskHandle_t xTaskToNotify, UBaseType_t uxIndexToNotify )

Task.hpp

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

configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for these functions to be available.

Each task has a private array of "notification values" (or 'notifications'), each of which is a 32-bit unsigned integer (uint32_t). The constant configTASK_NOTIFICATION_ARRAY_ENTRIES sets the number of indexes in the array, and (for backward compatibility) defaults to 1 if left undefined. Prior to FreeRTOS V10.4.0 there was only one notification value per task.

Events can be sent to a task using an intermediary object. Examples of such objects are queues, semaphores, mutexes and event groups. Task notifications are a method of sending an event directly to a task without the need for such an intermediary object.

A notification sent to a task can optionally perform an action, such as update, overwrite or increment one of the task's notification values. In that way task notifications can be used to send data to a task, or be used as light weight and fast binary or counting semaphores.

notifyGive() indicies is are intended for use when task notifications are used as light weight and faster binary or counting semaphore equivalents. Actual FreeRTOS semaphores are given using the FreeRTOS::Semaphore API, the equivalent action that instead uses a task notification is notifyGive().

When task notifications are being used as a binary or counting semaphore equivalent then the task being notified should wait for the notification using the notificationTake() API function rather than the notifyWaitIndexed() API function.

Note: Each notification within the array operates independently - a task can only block on one notification within the array at a time and will not be unblocked by a notification sent to any other array index.

Parameters

index The index within the target task's array of notification values to which the notification is to be sent. index must be less than configTASK_NOTIFICATION_ARRAY_ENTRIES.

Example Usage

#include <FreeRTOS/Task.hpp>
 
class MyTask : public FreeRTOS::Task {
 public:
  void taskFunction() final;
};
 
class MyDifferentTask : public FreeRTOS::Task {
 public:
  void taskFunction() final;
};
 
MyTask task1;
 
MyDifferentTask task2;
 
void MyTask::taskFunction() {
  for (;;) {
    // Send notification to task2, bringing it out of the  Blocked state.
    task2.notifyGive();
 
    // Block to wait for task2 to notify this task.
    notifyTake(portMAX_DELAY, true);
  }
}
 
void MyDifferentTask::taskFunction() {
  for (;;) {
    // Block to wait for task1 to notify this task.
    notifyTake(portMAX_DELAY, true);
 
    // Send a notification to task1, bringing it out of the Blocked state.
    task1.notifyGive();
  }
}

◆ notifyGiveFromISR() [1/2]

void FreeRTOS::TaskBase::notifyGiveFromISR	(	bool &	higherPriorityTaskWoken,
		const UBaseType_t	index = `0`
	)		const

inline

Function that calls void vTaskNotifyGiveIndexedFromISR( TaskHandle_t xTaskHandle, UBaseType_t uxIndexToNotify, BaseType_t *pxHigherPriorityTaskWoken )

Task.hpp

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

Version of notifyGive() that can be used from an interrupt service routine (ISR). See the documentation page for the notifyGive() API function for a description of their operation and the necessary configuration parameters.

Parameters

higherPriorityTaskWoken	A reference that will be set to true if sending the notification caused a task to unblock, and the unblocked task has a priority higher than the currently running task. If higherPriorityTaskWoken is set to true, then a context switch should be requested before the interrupt is exited.
index	The index within the target task's array of notification values to which the notification is to be sent. index must be less than configTASK_NOTIFICATION_ARRAY_ENTRIES.

Example Usage

#include <FreeRTOS/Kernel.hpp>
#include <FreeRTOS/Task.hpp>
 
// This is an example of a transmit function in a generic peripheral driver.  An
// RTOS task calls the transmit function, then waits in the Blocked state (so
// not using an CPU time) until it is notified that the transmission is
// complete. The transmission is performed by a DMA, and the DMA end interrupt
// is used to notify the task.
 
class MyTask : public FreeRTOS::Task {
 public:
  void taskFunction() final;
};
 
MyTask task;
 
FreeRTOS::TaskBase *taskToNotify = nullptr;
 
// The peripheral driver's transmit function.
void startTransmission(FreeRTOS::TaskBase *task, uint8_t *pcData,
                       size_t xDatalength) {
  // At this point taskToNotify should be nullptr as no transmission is in
  // progress.  A mutex can be used to guard access to the peripheral if
  // necessary.
  configASSERT(taskToNotify == nullptr);
 
  // Store the handle of the calling task.
  taskToNotify = task;
 
  // Start the transmission - an interrupt is generated when the transmission is
  // complete.
}
 
// The transmit end interrupt.
void transmitEndISR(void) {
  bool higherPriorityTaskWoken = false;
 
  // At this point taskToNotify should not be nullptr as a transmission was in
  // progress.
  configASSERT(taskToNotify != nullptr);
 
  // Notify the task that the transmission is complete.
  taskToNotify->notifyGiveFromISR(higherPriorityTaskWoken);
 
  if (higherPriorityTaskWoken) {
    /* If higherPriorityTaskWoken is true then a context switch should be
    performed to ensure the interrupt returns directly to the highest priority
    task.  The macro used for this purpose is dependent on the port in use and
    may be called portEND_SWITCHING_ISR(). */
    FreeRTOS::Kernel::yield();
  }
 
  // There are no transmissions in progress, so no tasks to notify.
  taskToNotify = nullptr;
}
 
void MyTask::taskFunction() {
  constexpr TickType_t xMaxBlockTime = pdMS_TO_TICKS(200);
 
  uint8_t data[8];
 
  startTransmission(this, data, sizeof(data));
}

◆ notifyGiveFromISR() [2/2]

void FreeRTOS::TaskBase::notifyGiveFromISR ( const UBaseType_t index = 0 ) const

inline

Function that calls void vTaskNotifyGiveIndexedFromISR( TaskHandle_t xTaskHandle, UBaseType_t uxIndexToNotify, BaseType_t *pxHigherPriorityTaskWoken )

Task.hpp

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

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

◆ notifyStateClear()

bool FreeRTOS::TaskBase::notifyStateClear ( const UBaseType_t index = 0 ) const

inline

Function that calls BaseType_t xTaskNotifyStateClearIndexed( TaskHandle_t xTask, UBaseType_t uxIndexToClear )

Task.hpp

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

configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for these functions to be available.

Each RTOS task has an array of task notifications. Each task notification has a notification state that can be either ‘pending’ or ‘not pending’, and a 32-bit notification value.

If a notification is sent to an index within the array of notifications then the notification at that index is said to be 'pending' until the task reads its notification value or explicitly clears the notification state to 'not pending' by calling notifyStateClear().

Parameters

index The index within the target task's array of notification values to act upon. For example, setting index to 1 will clear the state of the notification at index 1 within the array.

index must be less than configTASK_NOTIFICATION_ARRAY_ENTRIES.

notifyStateClear() does not have this parameter and always acts on the notification at index 0.

Return values

true	If the task had a notification pending, and the notification was cleared.
false	If the task didn't have a notification pending.

Example Usage

#include <FreeRTOS/Kernel.hpp>
#include <FreeRTOS/Task.hpp>
 
class MyTask : public FreeRTOS::Task {
 public:
  void taskFunction() final {}
 
 private:
  void serialPutString(const signed char* const pcStringToSend,
                       uint16_t usStringLength);
};
 
// Fake peripherial interface functions.
void UARTSendString(const signed char* const pcStringToSend,
                    uint16_t usStringLength) {}
 
MyTask myTask;
 
// An example UART send function.  The function starts a UART transmission then
// waits to be notified that the transmission is complete.  The transmission
// complete notification is sent from the UART interrupt.  The calling task's
// notification state is cleared before the transmission is started to ensure it
// is not co-incidentally already pending before the task attempts to block on
// its notification state.
void MyTask::serialPutString(const signed char* const pcStringToSend,
                             uint16_t usStringLength) {
  constexpr TickType_t maxBlockTime = pdMS_TO_TICKS(5000);
 
  // sendingTask holds the handle of the task waiting for the transmission to
  // complete.  If sendingTask is nullptr then a transmission is not in
  // progress.  Don't start to send a new string unless transmission of the
  // previous string is complete.
  if (usStringLength > 0) {
    // Ensure the task's 0th notification state is not already pending.
    notifyStateClear();
 
    // Start sending the string - the transmission is then controlled by an
    // interrupt.
    UARTSendString(pcStringToSend, usStringLength);
 
    // Wait in the Blocked state (so not using any CPU time) until the UART ISR
    // sends the 0th notification to sendingTask to notify (and unblock) the
    // task when the transmission is complete.
    notifyTake();
  }
}

◆ notifyTake()

static NotificationBits FreeRTOS::TaskBase::notifyTake	(	const TickType_t	ticksToWait = `portMAX_DELAY`,
		const bool	clearCountOnExit = `true`,
		const UBaseType_t	index = `0`
	)

inlinestaticprotected

Function that calls uint32_t ulTaskNotifyTakeIndexed( UBaseType_t uxIndexToWaitOn, BaseType_t xClearCountOnExit, TickType_t xTicksToWait )

Task.hpp

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

configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for these functions to be available.

Each task has a private array of "notification values" (or 'notifications'), each of which is a 32-bit unsigned integer (uint32_t). The constant configTASK_NOTIFICATION_ARRAY_ENTRIES sets the number of indexes in the array, and (for backward compatibility) defaults to 1 if left undefined. Prior to FreeRTOS V10.4.0 there was only one notification value per task.

Events can be sent to a task using an intermediary object. Examples of such objects are queues, semaphores, mutexes and event groups. Task notifications are a method of sending an event directly to a task without the need for such an intermediary object.

A notification sent to a task can optionally perform an action, such as update, overwrite or increment one of the task's notification values. In that way task notifications can be used to send data to a task, or be used as light weight and fast binary or counting semaphores.

notifyTake() is intended for use when a task notification is used as a faster and lighter weight binary or counting semaphore alternative. Actual FreeRTOS semaphores are taken using the FreeRTOS::Semaphore::take() API function, the equivalent action that instead uses a task notification is notifyTake().

When task notifications are being used as a binary or counting semaphore equivalent then the task being notified should wait for the notification using the notificationTake() API function rather than the notifyWait() API function.

notifyTake() can either clear the task's notification value at the array index specified by the indexToWaitOn parameter to zero on exit, in which case the notification value acts like a binary semaphore, or decrement the notification value on exit, in which case the notification value acts like a counting semaphore.

A task can use notifyTake() to [optionally] block to wait for a notification. The task does not consume any CPU time while it is in the Blocked state.

Where as notifyWait() will return when a notification is pending, notifyTake() will return when the task's notification value is not zero.

Note: Each notification within the array operates independently - a task can only block on one notification within the array at a time and will not be unblocked by a notification sent to any other array index.

Parameters

ticksToWait	The maximum time to wait in the Blocked state for a notification to be received if a notification is not already pending when notifyTake() is called. The RTOS task does not consume any CPU time when it is in the Blocked state. The time is specified in RTOS tick periods. The pdMS_TO_TICKS() macro can be used to convert a time specified in milliseconds into a time specified in ticks.
clearCountOnExit	If an RTOS task notification is received and clearCountOnExit is set to false then the RTOS task's notification value is decremented before notifyTake() exits. This is equivalent to the value of a counting semaphore being decremented by a successful call to FreeRTOS::Semaphore::Take(). If an RTOS task notification is received and clearCountOnExit is set to true then the RTOS task's notification value is reset to 0 before notifyTake() exits. This is equivalent to the value of a binary semaphore being left at zero (or empty, or 'not available') after a successful call to FreeRTOS::Semaphore::Take().
index	The index within the calling task's array of notification values on which the calling task will wait for a notification to be non-zero. index must be less than configTASK_NOTIFICATION_ARRAY_ENTRIES.

Returns: NotificationBits The value of the task's notification value before it is decremented or cleared (see the description of clearCountOnExit)

Example Usage

#include <FreeRTOS/Kernel.hpp>
#include <FreeRTOS/Task.hpp>
 
class MyTask : public FreeRTOS::Task {
 public:
  void taskFunction() final;
};
 
// Fake peripherial interface functions
BaseType_t xQueryPeripheral() { return 0; }
void vProcessPeripheralEvent(BaseType_t xEvent) {}
constexpr BaseType_t NO_MORE_EVENTS = 0;
 
MyTask myTask;
 
// An interrupt handler.  The interrupt handler does not perform any processing,
// instead it unblocks a high priority task in which the event that generated
// the interrupt is processed.  If the priority of the task is high enough then
// the interrupt will return directly to the task (so it will interrupt one task
// but return to a different task), so the processing will occur contiguously in
// time - just as if all the processing had been done in the interrupt handler
// itself.
void anInterruptHandler() {
  bool higherPriorityTaskWoken = false;
 
  // Unblock the handling task so the task can perform any processing
  // necessitated by the interrupt.
  myTask.notifyGiveFromISR(higherPriorityTaskWoken);
 
  if (higherPriorityTaskWoken) {
    // Force a context switch if notifyGiveFromISR was set to true.
    FreeRTOS::Kernel::yield();
  }
}
 
// A task that blocks waiting to be notified that the peripheral needs
// servicing, processing all the events pending in the peripheral each time it
// is notified to do so.
void MyTask::taskFunction() {
  BaseType_t xEvent;
 
  for (;;) {
    // Block indefinitely (without a timeout, so no need to check the function's
    // return value) to wait for a notification.  Here the RTOS task
    // notification is being used as a binary semaphore, so the notification
    // value is cleared to zero on exit.  NOTE!  Real applications should not
    // block indefinitely, but instead time out occasionally in order to handle
    // error conditions that may prevent the interrupt from sending any more
    // notifications.
    notifyTake();
 
    // The RTOS task notification is used as a binary (as opposed to a counting)
    // semaphore, so only go back to wait for further notifications when all
    // events pending in the peripheral have been processed.
    do {
      xEvent = xQueryPeripheral();
 
      if (xEvent != NO_MORE_EVENTS) {
        vProcessPeripheralEvent(xEvent);
      }
 
    } while (xEvent != NO_MORE_EVENTS);
  }
}

◆ notifyValueClear()

NotificationBits FreeRTOS::TaskBase::notifyValueClear	(	const NotificationBits	bitsToClear = `0`,
		const UBaseType_t	index = `0`
	)		const

inline

Function that calls uint32_t ulTaskNotifyValueClearIndexed( TaskHandle_t xTask, UBaseType_t uxIndexToClear, uint32_t ulBitsToClear )

Task.hpp

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

configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for these functions to be available.

Each RTOS task has an array of task notifications. Each task notification has a notification state that can be either ‘pending’ or ‘not pending’, and a 32-bit notification value.

notifyValueClear() clears the bits specified by the bitsToClear bit mask in the notification value at array index index of the task.

Parameters

bitsToClear	Bit mask of the bits to clear in the notification value of the task. Set a bit to 1 to clear the corresponding bits in the task's notification value. Set bitsToClear to 0xffffffff (UINT_MAX on 32-bit architectures) to clear the notification value to 0. Set bitsToClear to 0 to query the task's notification value without clearing any bits.
index	The index within the target task's array of notification values in which to clear the bits. index must be less than configTASK_NOTIFICATION_ARRAY_ENTRIES.

Returns: NotificationBits The value of the target task's notification value before the bits specified by bitsToClear were cleared.

Example Usage

#include <FreeRTOS/Kernel.hpp>
#include <FreeRTOS/Task.hpp>
 
class MyTask : public FreeRTOS::Task {
 public:
  void taskFunction() final;
 
 private:
  void sendMessage() {}
  void process_response_timeout() {}
  void process_response() {}
  void process_error() {}
};
 
MyTask myTask;
 
constexpr uint8_t messageReceivedBit = 4;
constexpr TickType_t ticksUntilTimeout = 100;
 
void MyTask::taskFunction() {
  for (;;) {
    // Send a message that expects a response.
    sendMessage();
 
    // Block this task until it has another pending notification. In this
    // example, the task only ever uses the messageReceivedBit of its
    // notification value, so the next event can only ever be on message
    // received.
    auto [received, notification] =
        notifyWait(0, 0, 0, ticksUntilTimeout);  // TODO: Clean up
 
    // If there wasn't a timeout, then the only possible event was received.  In
    // this example, that is the MESSAGE_RECEIVED_EVENT.
    if (notification.none()) {
      // Handle the response timeout.
      process_response_timeout();
    } else if (notification[messageReceivedBit]) {
      // Process the response event.
      process_response();
      notifyValueClear(1U << messageReceivedBit);
    } else {
      process_error();
    }
  }
}

◆ notifyWait()

static std::pair<bool, NotificationBits> FreeRTOS::TaskBase::notifyWait	(	const TickType_t	ticksToWait = `portMAX_DELAY`,
		const NotificationBits	bitsToClearOnEntry = `0`,
		const NotificationBits	bitsToClearOnExit = `0`,
		const UBaseType_t	index = `0`
	)

inlinestatic

Function that calls BaseType_t xTaskNotifyWaitIndexed( UBaseType_t uxIndexToWaitOn, uint32_t ulBitsToClearOnEntry, uint32_t ulBitsToClearOnExit, uint32_t *pulNotificationValue, TickType_t xTicksToWait )

Task.hpp

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

configUSE_TASK_NOTIFICATIONS must be undefined or defined as 1 for these functions to be available.

Each task has an array of 'task notifications' (or just 'notifications'), each of which has a state and a 32-bit value. A direct to task notification is an event sent directly to a task that can unblock the receiving task, and optionally update one of the receiving task’s notification values in a number of different ways. For example, a notification may overwrite one of the receiving task’s notification values, or just set one or more bits in one of the receiving task’s notification values.

notifyWait() waits, with an optional timeout, for the calling task to receive a notification. If the receiving RTOS task was already Blocked waiting for a notification when the notification it is waiting for arrives the receiving RTOS task will be removed from the Blocked state and the notification cleared.

Note: Each notification within the array operates independently - a task can only block on one notification within the array at a time and will not be unblocked by a notification sent to any other array index.

notifyGive() must not be called from an interrupt service routine. Use notifyGiveFromISR() instead.

Parameters

ticksToWait The maximum time to wait in the Blocked state for a notification to be received if a notification is not already pending when notifyWait() is called.

The RTOS task does not consume any CPU time when it is in the Blocked state.

The time is specified in RTOS tick periods. The pdMS_TO_TICKS() macro can be used to convert a time specified in milliseconds into a time specified in ticks.

Parameters

bitsToClearOnEntry Any bits set in bitsToClearOnEntry will be cleared in the calling RTOS task's notification value on entry to the notifyWait() function (before the task waits for a new notification) provided a notification is not already pending when notifyWait() is called.

For example, if bitsToClearOnEntry is 0x01, then bit 0 of the task's notification value will be cleared on entry to the function.

Setting bitsToClearOnEntry to 0xffffffff (ULONG_MAX) will clear all the bits in the task's notification value, effectively clearing the value to 0.

Parameters

bitsToClearOnExit Any bits set in bitsToClearOnExit will be cleared in the calling RTOS task's notification value before notifyWait() function exits if a notification was received.

The bits are cleared after the RTOS task's notification value are returned.

For example, if bitsToClearOnExit is 0x03, then bit 0 and bit 1 of the task's notification value will be cleared before the function exits.

Setting bitsToClearOnExit to 0xffffffff (ULONG_MAX) will clear all the bits in the task's notification value, effectively clearing the value to 0.

Parameters

index The index within the calling task's array of notification values on which the calling task will wait for a notification to be received. index must be less than configTASK_NOTIFICATION_ARRAY_ENTRIES.

Return values

true	If a notification was received, or a notification was already pending when notifyWait() was called.
false	If the call to notifyWait() timed out before a notification was received.

Returns: The RTOS task's notification value as it was before any bits were cleared due to the bitsToClearOnExit setting.

Example Usage

#include <FreeRTOS/Kernel.hpp>
#include <FreeRTOS/Task.hpp>
 
class MyTask : public FreeRTOS::Task {
 public:
  void taskFunction() final;
 
 private:
  void prvProcessBit0Event() {}
  void prvProcessBit1Event() {}
  void prvProcessBit2Event() {}
};
 
MyTask myTask;
 
// This task shows bits within the RTOS task notification value being used to
// pass different events to the task in the same way that flags in an event
// group might be used for the same purpose.
void MyTask::taskFunction() {
  for (;;) {
    // Block indefinitely (without a timeout, so no need to check the function's
    // return value) to wait for a notification.  Bits in this RTOS task's
    // notification value are set by the notifying tasks and interrupts to
    // indicate which events have occurred.
    auto notifiedValue = notifyWait().second;
 
    // Process any events that have been latched in the notified value.
    if (notifiedValue[0]) {
      // Bit 0 was set - process whichever event is represented by bit 0.
      prvProcessBit0Event();
    }
 
    if (notifiedValue[1]) {
      // Bit 1 was set - process whichever event is represented by bit 1.
      prvProcessBit1Event();
    }
 
    if (notifiedValue[2]) {
      // Bit 2 was set - process whichever event is represented by bit 2.
      prvProcessBit2Event();
    }
  }
}

◆ resume()

void FreeRTOS::TaskBase::resume ( ) const

inline

Function that calls void vTaskResume( TaskHandle_t xTaskToResume )

Task.hpp

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

INCLUDE_vTaskSuspend must be defined as 1 for this function to be available. See the RTOS Configuration documentation for more information.

Resumes a suspended task.

A task that has been suspended by one or more calls to suspend() will be made available for running again by a single call to resume().

Example Usage

#include <FreeRTOS/Task.hpp>
 
// Define a task that requries the priority to be specified.
class MyTask : public FreeRTOS::Task {
 public:
  explicit MyTask(UBaseType_t priority) : FreeRTOS::Task(priority) {}
  void taskFunction() final;
};
 
// Define a task that uses the default task priority.
class MyDifferentTask : public FreeRTOS::Task {
 public:
  void taskFunction() final;
};
 
MyTask myTask(tskIDLE_PRIORITY);
 
void MyTask::taskFunction() {
  // Create another task.
  MyDifferentTask myDifferentTask;
 
  // ...
 
  // Suspend the created task.
  myDifferentTask.suspend();
 
  // ...
 
  // The created task will not run during this period, unless another task calls
  // myDifferentTask.resume().
 
  //...
 
  // Resume the suspended task ourselves.
  myDifferentTask.resume();
 
  // The created task will once again get microcontroller processing time in
  // accordance with its priority within the system.
}
 
void MyDifferentTask::taskFunction() {
  for (;;) {
    // ...
  }
}

◆ resumeFromISR()

bool FreeRTOS::TaskBase::resumeFromISR ( ) const

inline

Function that calls BaseType_t xTaskResumeFromISR( TaskHandle_t xTaskToResume )

Task.hpp

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

INCLUDE_xTaskResumeFromISR must be defined as 1 for this function to be available. See the configuration section for more information.

An implementation of resume() that can be called from within an ISR.

A task that has been suspended by one or more calls to suspend() will be made available for running again by a single call to resumeFromISR().

resumeFromISR() should not be used to synchronize a task with an interrupt if there is a chance that the interrupt could arrive prior to the task being suspended - as this can lead to interrupts being missed. Use of a semaphore as a synchronisation mechanism would avoid this eventuality.

Return values

true	If resuming the task should result in a context switch. This is used by the ISR to determine if a context switch may be required following the ISR.
false	Otherwise.

Example Usage

#include <FreeRTOS/Kernel.hpp>
#include <FreeRTOS/Task.hpp>
 
class MyTask : public FreeRTOS::Task {
 public:
  void taskFunction() final;
};
 
MyTask myTask;
 
void MyTask::taskFunction() {
  // The task being suspended and resumed.
  for (;;) {
    // ... Perform some function here.
 
    // The task suspends itself.
    suspend();
 
    // The task is now suspended, so will not reach here until the ISR resumes
    // it.
  }
}
 
void anExampleISR() {
  // Resume the suspended task.
  if (myTask.resumeFromISR()) {
    // We should switch context so the ISR returns to a different task.
    // NOTE:  How this is done depends on the port you are using.  Check the
    // documentation and examples for your port.
    FreeRTOS::Kernel::yield();
  }
}

◆ setPriority()

void FreeRTOS::TaskBase::setPriority ( const UBaseType_t newPriority ) const

inline

Function that calls void vTaskPrioritySet( TaskHandle_t xTask, UBaseType_t uxNewPriority )

Task.hpp

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

INCLUDE_vTaskPrioritySet must be defined as 1 for this function to be available. See the configuration section for more information.

Set the priority of the task.

A context switch will occur before the function returns if the priority being set is higher than the currently executing task.

Parameters

newPriority The priority to which the task will be set.

Example Usage

#include <FreeRTOS/Task.hpp>
 
// Define a task that requries the priority to be specified.
class MyTask : public FreeRTOS::Task {
 public:
  explicit MyTask(UBaseType_t priority) : FreeRTOS::Task(priority) {}
  void taskFunction() final;
};
 
// Define a task that uses the default task priority.
class MyDifferentTask : public FreeRTOS::Task {
 public:
  void taskFunction() final;
};
 
MyTask myTask(tskIDLE_PRIORITY);
 
MyDifferentTask myDifferentTask;
 
void MyTask::taskFunction() {
  // Raise the priority of this task.
  setPriority(tskIDLE_PRIORITY + 1);
}
 
void MyDifferentTask::taskFunction() {
  // Raise the priority of myTask.
  myTask.setPriority(myTask.getPriority() + 1);
}

◆ suspend()

void FreeRTOS::TaskBase::suspend ( ) const

inline

Function that calls void vTaskSuspend( TaskHandle_t xTaskToSuspend )

Task.hpp

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

INCLUDE_vTaskSuspend must be defined as 1 for this function to be available. See the RTOS Configuration documentation for more information.

Suspend a task. When suspended a task will never get any microcontroller processing time, no matter what its priority.

Calls to suspend() are not accumulative - i.e. calling suspend() twice on the same task still only requires one call to resume() to ready the suspended task.

Example Usage

#include <FreeRTOS/Task.hpp>
 
// Define a task that requries the priority to be specified.
class MyTask : public FreeRTOS::Task {
 public:
  explicit MyTask(UBaseType_t priority) : FreeRTOS::Task(priority) {}
  void taskFunction() final;
};
 
// Define a task that uses the default task priority.
class MyDifferentTask : public FreeRTOS::Task {
 public:
  void taskFunction() final;
};
 
MyTask myTask(tskIDLE_PRIORITY);
 
void MyTask::taskFunction() {
  // Create another task.
  MyDifferentTask myDifferentTask;
 
  // ...
 
  // Suspend the created task.
  myDifferentTask.suspend();
 
  // ...
 
  // The created task will not run during this period, unless another task calls
  // myDifferentTask.resume().
 
  //...
 
  // Suspend ourselves.
  suspend();
 
  // We cannot get here unless another task calls myTask.resume().
}
 
void MyDifferentTask::taskFunction() {
  for (;;) {
    // ...
  }
}

◆ taskEntry()

virtual void FreeRTOS::TaskBase::taskEntry ( )

inlinefinalvirtual

Function that acts as the entry point of the task instance. This function initializes the previous wake time of the task and calls the user implemented taskFunction().

Task.hpp

Note: This function is only public so that it can be accessed by the C interface function callTaskFunction() and should not be called or referenced by the user.

◆ taskFunction()

virtual void FreeRTOS::TaskBase::taskFunction ( )

protectedpure virtual

Abstraction function that acts as the entry point of the task for the user.

Task.hpp

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

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

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Static Protected Member Functions

Private Member Functions

Private Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

◆ ~TaskBase()

Member Function Documentation

◆ abortDelay()

◆ delay()

◆ delayUntil()

◆ getHandle()

◆ getIdleHandle()

◆ getName()

◆ getPriority()

◆ getStackHighWaterMark()

◆ getStackHighWaterMark2()

◆ getState()

◆ notify()

◆ notifyAndQuery()

◆ notifyAndQueryFromISR() [1/2]

◆ notifyAndQueryFromISR() [2/2]

◆ notifyFromISR() [1/2]

◆ notifyFromISR() [2/2]

◆ notifyGive()

◆ notifyGiveFromISR() [1/2]

◆ notifyGiveFromISR() [2/2]

◆ notifyStateClear()

◆ notifyTake()

◆ notifyValueClear()

◆ notifyWait()

◆ resume()

◆ resumeFromISR()

◆ setPriority()

◆ suspend()

◆ taskEntry()

◆ taskFunction()