Static Public Member Functions | Protected Member Functions
scheduler_task Class Referenceabstract

#include <scheduler_task.hpp>

Public Member Functions

const char * getTaskName (void) const
 
uint32_t getFreeStack (void) const
 
uint32_t getRunCount (void) const
 
TaskHandle_t getTaskHandle (void) const
 
uint8_t getTaskPriority (void) const
 
void suspend (void) const
 
void resume (void) const
 

Static Public Member Functions

static scheduler_task * getTaskPtrByName (const char *)
 
static bool addSharedObject (const char *name, void *obj_ptr)
 
static void * getSharedObject (const char *name)
 
static bool addSharedObject (uint8_t index, void *obj_ptr)
 
static void * getSharedObject (uint8_t index)
 

Protected Member Functions

 scheduler_task (const char *name, uint32_t stack, uint8_t priority, void *param=0)
 
virtual ~scheduler_task ()
 
virtual bool init (void)
 
virtual bool regTlm (void)
 
virtual bool taskEntry (void)
 
virtual bool run (void *param)=0
 
void setRunDuration (uint32_t milliseconds)
 
uint32_t getRunDuration (void) const
 
void setStatUpdateRate (uint32_t rateMs)
 

Friends

bool scheduler_init_all (bool register_task_tlm)
 
void scheduler_c_task_private (void *param)
 
static uint8_t getSysCpuPercent (void)
 Get total system CPU percent. More...
 
static uint8_t getSysIdlePercent (void)
 Get total system IDLE percent. More...
 
uint8_t getTaskCpuPercent (void) const
 Get CPU usage of this task. More...
 

Detailed Description

Scheduler task. This class should be inherited and at minimum, you would need to override the run() function to execute as part of your task. Note that the run() function should return as the scheduler is responsible for the FreeRTOS task loop.

All tasks perform init() one after another, followed by taskEntry(). Only after all tasks perform their init() and taskEntry(), the run() method begins to loop, so this solves the initialization dependency problem.

The order of operations is the following :

  • All tasks call their: init()
  • All tasks call their: regTlm()
  • FreeRTOS is started
  • All tasks call their: taskEntry()
  • All tasks enter loop to call run() method

Note that until you get to the run() function, you are essentially in a "thread safe" mode since context or task switch will not occur.

Example task that prints a message every 1000ms :

class my_task : public scheduler_task
{
public :
// Call scheduler_task() constructor with your task name, stack size, and priority
my_task() : scheduler_task("task name", 2048, 1)
{
setRunDuration(1000); // Optional frequency control for run()
}
bool run(void *param)
{
puts("Hello World");
return true;
}
};
// Add the task to the scheduler and start it :
scheduler_add_task(new my_task());
scheduler_start();

Constructor & Destructor Documentation

scheduler_task::scheduler_task ( const char *  name,
uint32_t  stack,
uint8_t  priority,
void *  param = 0 
)
protected

Constructor

Parameters
nameThe task's name
stackThe task's stack size in bytes
priorityFreeRTOS task priority
paramOPTIONAL param to pass to your run() when it's called.
virtual scheduler_task::~scheduler_task ( )
inlineprotectedvirtual

Member Function Documentation

bool scheduler_task::addSharedObject ( const char *  name,
void *  obj_ptr 
)
static

Add/Get a shared object pointer by name such that multiple classes of this type can communicate between themselves.

Note
It is recommended to use the later version of addSharedObject() and getSharedObject() because it is faster. Consider this version of overloaded API deprecated – :)
QueueHandle_t sensor_queue;
// Task A can share its handle by a name:
addSharedObject("senqueue", sensor_queue);
// Task B can retrieve the handle in its context:
QueueHandle_t sensor_queue = getSharedObject("senqueue");
Note
These functions are declared static because that way, any code in any context can get a shared object. So a C function (ie terminal cmd) can get a shared object and queue data for a task. Here is the usage (use the scope operator directly):
void my_func(void)
{
xSemaphoreGive(scheduler_task::getSharedObject("foo"));
}
bool scheduler_task::addSharedObject ( uint8_t  index,
void *  obj_ptr 
)
static

Add or get a shared object by an index number. This provides a better alternative to sharing handles because strcmp() doesn't take place, instead the getSharedObject() simply returns the handle at the index.

This index is best utilized by using an enumeration, such as this:

enum {
shr_Sem,
shr_Queue,
};
SemaphoreHandle_t semaphore;
QueueHandle_t senqueue;
// Task A can share its handles:
addSharedObject(shr_Sem, semaphore);
addSharedObject(shr_Queue, senqueue);
// Task B can retrieve the handles in its class:
QueueHandle_t qh = getSharedObject(shr_Queue);
Note
These functions are declared static because that way, any code in any context can get a shared object. So a C function (ie terminal cmd) can get a shared object and queue data for a task. Here is the usage (use the scope operator directly):
void my_func(void)
{
xSemaphoreGive(scheduler_task::getSharedObject(shr_Sem));
}
uint32_t scheduler_task::getFreeStack ( void  ) const
inline
uint32_t scheduler_task::getRunCount ( void  ) const
inline
uint32_t scheduler_task::getRunDuration ( void  ) const
inlineprotected
Returns
the run duration set by setRunDuration()
void * scheduler_task::getSharedObject ( const char *  name)
static
void * scheduler_task::getSharedObject ( uint8_t  index)
static
uint8_t scheduler_task::getSysCpuPercent ( void  )
static

Get total system CPU percent.

uint8_t scheduler_task::getSysIdlePercent ( void  )
static

Get total system IDLE percent.

uint8_t scheduler_task::getTaskCpuPercent ( void  ) const

Get CPU usage of this task.

CPU usage API

Note
static functions can be called from any function, even not belonging to this class.
TaskHandle_t scheduler_task::getTaskHandle ( void  ) const
inline
const char* scheduler_task::getTaskName ( void  ) const
inline

Get methods Tasks can get each others' pointers by using their task names. After obtaining the pointer, they can get each other's CPU usage, and task handle.

uint8_t scheduler_task::getTaskPriority ( void  ) const
inline
scheduler_task * scheduler_task::getTaskPtrByName ( const char *  name)
static

Get a task pointer by name This is declared static such that any code in any context can retrieve a task pointer by name. Here is the usage (use the scope operator directly):

scheduler_task* pTask = scheduler_task::getTaskPtrByName("taskname");
pTask->suspend();

Static functions:

virtual bool scheduler_task::init ( void  )
inlineprotectedvirtual

Optional: Override this function to initialize anything before FreeRTOS starts.

Returns
true upon success.
Warning
DO NOT USE FreeRTOS blocking API in this function
Note
You should use init() instead of the constructor to initialize and allocate memory because the status of init() is checked and reported, but a failure at constructor will not be easily caught (or reported).
virtual bool scheduler_task::regTlm ( void  )
inlineprotectedvirtual

Optional: Override this function to register your telemetry before FreeRTOS starts.

Returns
true upon success.
Warning
DO NOT USE FreeRTOS blocking API in this function
void scheduler_task::resume ( void  ) const
inline
virtual bool scheduler_task::run ( void *  param)
protectedpure virtual

MUST override this function to run your tasks' code

Parameters
paramThe same pointer as the constructor's param
Returns
false if something unexpected occurs. In this case, the task will be suspended from doing further work.
void scheduler_task::setRunDuration ( uint32_t  milliseconds)
inlineprotected

This can be used to set a desired time that the run() method will be called. For example, if frequency is set to 1000, then the run() will be called every 1 second regardless the duration that your run() method. If your run() takes longer than the milliseconds you set, then it will be called without a delay.

Parameters
millisecondsThe frequency to call your run() function. Set this to zero to disable this functionality.
Note
By default, run() method is called continuously without a delay.
void scheduler_task::setStatUpdateRate ( uint32_t  rateMs)
inlineprotected

Set the update rate in milliseconds that the free stack size is calculated at. Default rate is 60 seconds; zero is to disable it.

void scheduler_task::suspend ( void  ) const
inline

Suspend and resume functions. Obviously you can suspend yourself but someone else will have to resume you ;)

virtual bool scheduler_task::taskEntry ( void  )
inlineprotectedvirtual

Optional : Override this function which is called ONCE after FreeRTOS starts If your task depends on someone else's init(), then you can put your relevant code here that is called after everyone's init(). You CAN use FreeRTOS API but note that all other tasks will wait for everyone's taskEntry() to take place before the run() method is called.

Warning
Do not suspend your task otherwise all tasks will get suspended.
Returns
true upon success.

Friends And Related Function Documentation

void scheduler_c_task_private ( void *  param)
friend

This is the C task that is created multiple times. Each task receives its own parameter therefore differentiating between different tasks.

bool scheduler_init_all ( bool  register_task_tlm)
friend

Give access to our private members to these functions

The documentation for this class was generated from the following files:
Generated by   doxygen 1.8.11