A task node object. More...

#include <task.hpp>

Inheritance diagram for qOS::task:

Collaboration diagram for qOS::task:

Public Member Functions
	task ()=default

virtual	~task ()

priority_t	getPriority (void) const noexcept
	Retrieve the current task priority.

bool	setPriority (const priority_t pValue) noexcept
	Set/Change the task priority value.

cycles_t	getCycles (void) const noexcept
	Retrieve the number of task activations.

taskState	getState (void) const noexcept
	Retrieve the task operational state.

bool	setState (const taskState s) noexcept
	Set the task operational state.

bool	suspend (void) noexcept
	Put the task into a disabled state.

bool	disable (void) noexcept
	Put the task into a disabled state.

bool	resume (void) noexcept
	Put the task into a enabled state.

bool	enable (void) noexcept
	Put the task into a enabled state.

bool	asleep (void) noexcept
	Put the task into a sleep state. The task can't be triggered by the lower precedence events.

bool	awake (void) noexcept
	Put the task into a normal operation state. Here the task will be able to catch any kind of events.

bool	isEnabled (void) const noexcept
	Retrieve the enabled/disabled state.

void	setIterations (const iteration_t iValue) noexcept
	Set/Change the number of task iterations.

bool	setTime (const qOS::duration_t tValue) noexcept
	Set/Change the Task execution interval.

bool	setCallback (const taskFcn_t tCallback) noexcept
	Set/Change the task callback function.

bool	setData (void *arg) noexcept
	Set the task data.

bool	setName (const char *tName) noexcept
	Set the task name.

const char *	getName (void) const noexcept
	Retrieves the task name.

size_t	getID (void) const noexcept
	Retrieves the Task ID number.

bool	attachQueue (queue &q, const queueLinkMode mode, const size_t arg=1U) noexcept
	Attach a queue to the Task.

void *const &	getBindedObject (void) const noexcept
	Retrieves a pointer to the object binded to the task, could be either a state-machine or a command-line-interface.

queue *	getQueue (void) noexcept
	Retrieves a pointer to the queue attached to the task.

Static Public Attributes
static const iteration_t	PERIODIC
	A constant to indicate that the task will run every time its timeout has expired.

static const iteration_t	INDEFINITE
	Same as PERIODIC. A constant to indicate that the task will run every time its timeout has expired.

static const iteration_t	SINGLE_SHOT
	A constant to indicate that the task will be executed only once after its time has expired.

Protected Member Functions
virtual void	activities (event_t e)

Protected Member Functions inherited from qOS::node
list *	getContainer (void) noexcept
	Get a pointer to the list in which this node is contained.

	node ()

Detailed Description

A task node object.

Like many operating systems, the basic unit of work is the task. Tasks can perform certain functions, which could require periodic or one-time execution, update of specific variables or waiting for specific events. Tasks also could be controlling specific hardware or be triggered by hardware interrupts. In the QuarkTS OS, a task is seen as a node concept that links together:

Program code performing specific task activities (callback function)
Execution interval (time)
Number of execution (iterations)
Event-based data

The OS uses a Task Control Block(TCB) to represent each task, storing essential information about task management and execution. Part of this information also includes link-pointers that allows it to be part of one of the lists available in the Kernel Control Block (KCB).

Each task performs its activities via a callback function and each of them is responsible for supporting cooperative multitasking by being “good neighbors”, i.e., running their callback methods quickly in a non-blocking way and releasing control back to the scheduler as soon as possible (returning). Every task node, must be defined using the qOS::task class and the callback is defined as a function that returns void and takes a event_t data structure as its only parameter (This input argument can be used later to get event information.

Example :

using namespace qOS;
 
task UserTask;
 
void UserTask_Callback( event_t e ) {
 
}

Attention: All tasks in QuarkTS must ensure their completion to return the CPU control back to the scheduler, otherwise, the scheduler will hold the execution-state for that task, preventing the activation of other tasks.

Note: Do not access any member of this structure directly.

Constructor & Destructor Documentation

◆ task()

qOS::task::task ( )

default

◆ ~task()

virtual qOS::task::~task ( )

inlinevirtual

Member Function Documentation

◆ activities()

virtual void qOS::task::activities ( event_t e )

protectedvirtual

◆ asleep()

bool qOS::task::asleep ( void )

inlinenoexcept

Put the task into a sleep state. The task can't be triggered by the lower precedence events.

Note: Only the higher precedence events (Queued Notifications) can wake up the task.

See also: task::setState()

Returns: true on success. Otherwise return false.

◆ attachQueue()

bool qOS::task::attachQueue	(	queue &	q,
		const queueLinkMode	mode,
		const size_t	arg = 1U )

noexcept

Attach a queue to the Task.

Parameters

[in]	q	The queue object
[in]	mode	Attach mode. This implies the event that will trigger the task according to one of the following modes:

queueLinkMode::QUEUE_RECEIVER : The task will be triggered if there are elements in the Queue. Data will be extracted automatically in every trigger and will be available in the event_t::EventData field.

queueLinkMode::QUEUE_FULL : The task will be triggered if the Queue is full. A pointer to the queue will be available in the event_t::EventData field.

queueLinkMode::QUEUE_COUNT : The task will be triggered if the count of elements in the queue reach the specified value. A pointer to the queue will be available in the event_t::EventData field.

queueLinkMode::QUEUE_EMPTY : The task will be triggered if the queue is empty. A pointer to the queue will be available in the event_t::EventData field.

Parameters

[in] arg This argument defines if the queue will be attached (1u) or detached (0u) from the task. If the queueLinkMode::QUEUE_COUNT mode is specified, this value will be used to check the element count of the queue. A zero value will act as a detach action.

Returns: Returns true on success, otherwise returns false.

◆ awake()

bool qOS::task::awake ( void )

inlinenoexcept

Put the task into a normal operation state. Here the task will be able to catch any kind of events.

See also: task::setState()

Returns: true on success. Otherwise return false.

◆ disable()

bool qOS::task::disable ( void )

inlinenoexcept

Put the task into a disabled state.

See also: task::setState()

Returns: true on success. Otherwise return false.

◆ enable()

bool qOS::task::enable ( void )

inlinenoexcept

Put the task into a enabled state.

See also: task::setState()

Returns: true on success. Otherwise return false.

◆ getBindedObject()

void *const & qOS::task::getBindedObject ( void ) const

noexcept

Retrieves a pointer to the object binded to the task, could be either a state-machine or a command-line-interface.

Returns: A void pointer to the attached object.

◆ getCycles()

cycles_t qOS::task::getCycles ( void ) const

noexcept

Retrieve the number of task activations.

Returns: An unsigned long value containing the number of task activations.

◆ getID()

size_t qOS::task::getID ( void ) const

noexcept

Retrieves the Task ID number.

Returns: The task ID

◆ getName()

const char * qOS::task::getName ( void ) const

noexcept

Retrieves the task name.

Returns: A pointer to the string containing the task name. If the task is unnamed an empty string will be returned.

◆ getPriority()

priority_t qOS::task::getPriority ( void ) const

noexcept

Retrieve the current task priority.

Returns: The task priority value.

◆ getQueue()

queue * qOS::task::getQueue ( void )

noexcept

Retrieves a pointer to the queue attached to the task.

Returns: A void pointer to the attached object.

◆ getState()

taskState qOS::task::getState ( void ) const

noexcept

Retrieve the task operational state.

Returns: taskState::ENABLED_STATE or taskState::DISABLED_STATE if the task is taskState::AWAKE_STATE. taskState::ASLEEP_STATE if the task is in a Sleep operational state.

◆ isEnabled()

bool qOS::task::isEnabled ( void ) const

inlinenoexcept

Retrieve the enabled/disabled state.

See also: task::getState()

Returns: true if the task in on Enabled state, otherwise returns false.

◆ resume()

bool qOS::task::resume ( void )

inlinenoexcept

Put the task into a enabled state.

See also: task::setState()

Returns: true on success. Otherwise return false.

◆ setCallback()

bool qOS::task::setCallback ( const taskFcn_t tCallback )

noexcept

Set/Change the task callback function.

Note: This function can be used to detach a state-machine from a task

Parameters

[in] tCallback A pointer to a void callback method with a event_t parameter as input argument.

Returns: true on success. Otherwise return false.

◆ setData()

bool qOS::task::setData ( void * arg )

noexcept

Set the task data.

Parameters

[in] arg The task storage pointer. User data.

Returns: true on success. Otherwise return false.

◆ setIterations()

void qOS::task::setIterations ( const iteration_t iValue )

noexcept

Set/Change the number of task iterations.

Parameters

[in] iValue Number of task executions (Integer value). For indefinite execution (iValue = task::PERIODIC or task::INDEFINITE). Tasks do not remember the number of iteration set initially. After the iterations are done, internal iteration counter is 0. If you need to perform another set of iterations, you need to set the number of iterations again and resume.

◆ setName()

bool qOS::task::setName ( const char * tName )

noexcept

Set the task name.

Precondition: The task must already be added to the scheduling scheme

Note: Name should be unique.; The name idle is reserved for the Idle task

Remarks: The size of the string must be less than 11

Parameters

[in] tName A raw-string with the task name

Returns: true on success. Otherwise return false.

◆ setPriority()

bool qOS::task::setPriority ( const priority_t pValue )

noexcept

Set/Change the task priority value.

Parameters

[in] pValue Priority Value. [0(min) - Q_PRIORITY_LEVELS (max)]

Returns: true on success. Otherwise return false.

◆ setState()

bool qOS::task::setState ( const taskState s )

noexcept

Set the task operational state.

Parameters

[in] s Use one of the following values:

taskState::ENABLED_STATE : Task will be able to catch all the events. ( ENABLE_Bit=1 )

taskState::DISABLED_STATE : Time events will be discarded. The task catch asynchronous events. ( ENABLE_Bit=0)

taskState::ASLEEP_STATE : Put the task into a sleep operability state. The task can't be triggered by the lower precedence events. ( SHUTDOWN_Bit=0)

taskState::AWAKE_STATE : Put the task into the previous state before it was put in the sleep state.( SHUTDOWN_Bit=1 )

Returns: true on success. Otherwise return false.

◆ setTime()

bool qOS::task::setTime ( const qOS::duration_t tValue )

noexcept

Set/Change the Task execution interval.

Parameters

[in] tValue Execution interval given in milliseconds. For immediate execution (tValue = clock::IMMEDIATE).

Returns: true on success, otherwise returns false.

◆ suspend()

bool qOS::task::suspend ( void )

inlinenoexcept

Put the task into a disabled state.

See also: task::setState()

Returns: true on success. Otherwise return false.

Member Data Documentation

◆ INDEFINITE

const iteration_t qOS::task::INDEFINITE

static

Same as PERIODIC. A constant to indicate that the task will run every time its timeout has expired.

◆ PERIODIC

const iteration_t qOS::task::PERIODIC

static

A constant to indicate that the task will run every time its timeout has expired.

◆ SINGLE_SHOT

const iteration_t qOS::task::SINGLE_SHOT

static

A constant to indicate that the task will be executed only once after its time has expired.

Public Member Functions

Static Public Attributes

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ task()

◆ ~task()

Member Function Documentation

◆ activities()

◆ asleep()

◆ attachQueue()

◆ awake()

◆ disable()

◆ enable()

◆ getBindedObject()

◆ getCycles()

◆ getID()

◆ getName()

◆ getPriority()

◆ getQueue()

◆ getState()

◆ isEnabled()

◆ resume()

◆ setCallback()

◆ setData()

◆ setIterations()

◆ setName()

◆ setPriority()

◆ setState()

◆ setTime()

◆ suspend()

Member Data Documentation

◆ INDEFINITE

◆ PERIODIC

◆ SINGLE_SHOT