API interface to manage tasks. More...

Collaboration diagram for Managing tasks:

Data Structures
struct	qEvent_t
	The task argument with all the regarding information of the task execution. More...

struct	qTask_t
	A task node object. More...

Macros
#define	QMAX_NOTIFICATION_VALUE
	Max allowed notification value.

#define	QEVENTFLAG_CLEAR
	A macro directive to indicate that the eventFlags should be cleared.

#define	QEVENTFLAG_SET
	A macro directive to indicate that the eventFlags should be set.

#define	qTask_Suspend(Task)
	Put the task into a disabled state. More...

#define	qTask_Disable(Task)
	Put the task into a disabled state. More...

#define	qTask_Resume(Task)
	Put the task into an enabled state. More...

#define	qTask_Enable(Task)
	Put the task into an enabled state. More...

#define	qTask_ASleep(Task)
	Put the task into a sleep state. The task can't be triggered by the lower precedence events. More...

#define	qTask_Awake(Task)
	Put the task into a normal operation state. Here the task will be able to catch any kind of events. More...

#define	qTask_IsEnabled(Task)
	Retrieve the enabled/disabled state. More...

Typedefs
typedef qUINT32_t	qNotifier_t
	A 32-bit unsigned integer type to hold a notification value.

typedef qUINT32_t	qTask_Flag_t
	A 32-bit unsigned integer type to hold the task flags.

typedef void(*	qTaskFcn_t) (qEvent_t arg)
	Pointer to a task callback.

Enumerations
enum	qTrigger_t { qTriggerNULL , byTimeElapsed , byNotificationQueued , byNotificationSimple , byQueueReceiver , byQueueFull , byQueueCount , byQueueEmpty , byEventFlags , bySchedulingRelease , byNoReadyTasks }
	An enum with all the possible values for the qEvent_t::Trigger member. More...

enum	qTask_GlobalState_t { qUndefinedGlobalState , qReady , qWaiting , qSuspended , qRunning }
	An enum to describe the task global states. More...

enum	qQueueLinkMode_t { qQueueMode_Receiver , qQueueMode_Full , qQueueMode_Count , qQueueMode_Empty }
	An enum that defines the modes in which a queue can be linked to a task. More...

Functions
qState_t	qTask_Get_State (const qTask_t *const Task)
	Retrieve the task operational state. More...

qCycles_t	qTask_Get_Cycles (const qTask_t *const Task)
	Retrieve the number of task activations. More...

qTask_GlobalState_t	qTask_Get_GlobalState (const qTask_t *const Task)
	Retrieve the task global-state. More...

qBool_t	qTask_Set_Time (qTask_t *const Task, const qTime_t tValue)
	Set/Change the Task execution interval. More...

qBool_t	qTask_Set_Iterations (qTask_t *const Task, const qIteration_t iValue)
	Set/Change the number of task iterations. More...

qBool_t	qTask_Set_Priority (qTask_t *const Task, const qPriority_t pValue)
	Set/Change the task priority value. More...

qBool_t	qTask_Set_Callback (qTask_t *const Task, const qTaskFcn_t cFcn)
	Set/Change the task callback function. More...

qBool_t	qTask_Set_State (qTask_t *const Task, const qState_t s)
	Set the task operational state. More...

qBool_t	qTask_Set_Data (qTask_t const Task, void arg)
	Set the task data. More...

qBool_t	qTask_Clear (qTask_t *const Task, const qTask_ClrParam_t param)
	Clear the specified parameter for the task. More...

qTask_t *	qTask_Self (void)
	Get the current running-task handle. More...

qBool_t	qTask_Set_Name (qTask_t const Task, const char name)
	Set the task name. More...

const char *	qTask_Get_Name (const qTask_t *const Task)
	Retrieves the task name. More...

qTask_t *	qTask_Find_ByName (const char *name)
	Tries to find the first task that matches the name provided. More...

Detailed Description

API interface to manage tasks.

Precondition: In order to be able to manage a task, make sure the task has already been added to the scheduling scheme bt using qOS_Add_Task(), qOS_Add_EventTask(), qOS_Add_StateMachineTask() or qOS_Add_ATCLITask().

Macro Definition Documentation

◆ qTask_ASleep

#define qTask_ASleep ( Task )

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: qTask_Set_State()

Parameters

[in] Task Pointer to the task node.

Returns: qTrue on success. Otherwise return qFalse.

◆ qTask_Awake

#define qTask_Awake ( Task )

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

See also: qTask_Set_State()

Parameters

[in] Task Pointer to the task node.

Returns: qTrue on success. Otherwise return qFalse.

◆ qTask_Disable

#define qTask_Disable ( Task )

Put the task into a disabled state.

See also: qTask_Set_State()

Parameters

[in] Task Pointer to the task node.

Returns: qTrue on success. Otherwise return qFalse.

◆ qTask_Enable

#define qTask_Enable ( Task )

Put the task into an enabled state.

See also: qTask_Set_State()

Parameters

[in] Task Pointer to the task node.

Returns: qTrue on success. Otherwise return qFalse.

◆ qTask_IsEnabled

#define qTask_IsEnabled ( Task )

Retrieve the enabled/disabled state.

See also: qTask_Set_State()

Parameters

[in] Task Pointer to the task node.

Returns: qTrue if the task in on Enabled state, otherwise returns qFalse.

◆ qTask_Resume

#define qTask_Resume ( Task )

Put the task into an enabled state.

See also: qTask_Set_State()

Parameters

[in] Task Pointer to the task node.

Returns: qTrue on success. Otherwise return qFalse.

◆ qTask_Suspend

#define qTask_Suspend ( Task )

Put the task into a disabled state.

See also: qTask_Set_State()

Parameters

[in] Task Pointer to the task node.

Returns: qTrue on success. Otherwise return qFalse.

Enumeration Type Documentation

◆ qQueueLinkMode_t

enum qQueueLinkMode_t

An enum that defines the modes in which a queue can be linked to a task.

Enumerator
qQueueMode_Receiver	This mode will trigger the task if there are elements in the queue. Data will be extracted automatically in every trigger and will be available in the qEvent_t::EventData field.
qQueueMode_Full	This mode will trigger the task if the queue is full. A pointer to the queue will be available in the qEvent_t::EventData field.
qQueueMode_Count	This mode will trigger the task if the count of elements in the queue reach the specified value. A pointer to the queue will be available in the qEvent_t::EventData field.
qQueueMode_Empty	This mode will trigger the task if the queue is empty. A pointer to the queue will be available in the qEvent_t::EventData field.

◆ qTask_GlobalState_t

enum qTask_GlobalState_t

An enum to describe the task global states.

Enumerator
qUndefinedGlobalState	A task should never reach this state(Reserved for internal use)
qReady	The task has completed preparations for running, but cannot run because a task with a higher precedence is running.
qWaiting	The task cannot run because the conditions for running are not in place.
qSuspended	The task doesn't take part in what is going on. Normally this state is taken after the qRunning state or when the task doesn't reach the qReady state
qRunning	The task is currently being executed.

◆ qTrigger_t

enum qTrigger_t

An enum with all the possible values for the qEvent_t::Trigger member.

Enumerator
qTriggerNULL	To indicate the absence of trigger. Reserved for internal use.
byTimeElapsed	When the time specified for the task elapsed.
byNotificationQueued	When there is a queued notification in the FIFO priority queue. For this trigger, the dispatcher performs a dequeue operation automatically. A pointer to the extracted event data will be available in the qEvent_t::EventData field.
byNotificationSimple	When the execution chain does, according to a requirement of asynchronous notification event prompted by qTask_Notification_Send(). A pointer to the notified data will be available in the qEvent_t::EventData field.
byQueueReceiver	When there are elements available in the attached qQueue, the scheduler make a data dequeue (auto-receive) from the front. A pointer to the received data will be available in the qEvent_t::EventData field.
byQueueFull	When the attached queue is full. A pointer to the queue will be available in the qEvent_t::EventData field.
byQueueCount	When the element-count of the attached queue reaches the specified value. A pointer to the queue will be available in the qEvent_t::EventData field.
byQueueEmpty	When the attached queue is empty. A pointer to the queue will be available in the qEvent_t::EventData field.
byEventFlags	When any event-flag is set.
bySchedulingRelease	When the scheduler is released.
byNoReadyTasks	Only available when the Idle Task is triggered.

Function Documentation

◆ qTask_Clear()

qBool_t qTask_Clear	(	qTask_t *const	Task,
		const qTask_ClrParam_t	param
	)

Clear the specified parameter for the task.

Parameters

[in]	Task	Pointer to the task node.
[in]	param	Use one of the following values:

qTask_ClearIterations : Clear the number of iterations.

qTask_ClearTimeElapsed : Clear the time elapsed.

qTask_ClearCycles : Clear the number of task activations.

qTask_ClearSimpleNotifications : Clear the notification value.

qTask_ClearQueuedNotifications : Clear all the queued notifications.

qTask_ClearNotifications : Clear all notifications (simple and queued).

Returns: qTrue on success. Otherwise return qFalse.

◆ qTask_Find_ByName()

qTask_t * qTask_Find_ByName ( const char * name )

Tries to find the first task that matches the name provided.

Parameters

[in] name The string with the name to find.

Returns: A pointer to the task node if found, otherwise returns NULL.

◆ qTask_Get_Cycles()

qCycles_t qTask_Get_Cycles ( const qTask_t *const Task )

Retrieve the number of task activations.

Parameters

[in] Task Pointer to the task node.

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

◆ qTask_Get_GlobalState()

qTask_GlobalState_t qTask_Get_GlobalState ( const qTask_t *const Task )

Retrieve the task global-state.

Parameters

[in] Task Pointer to the task node.

Returns: One of the available global states : qWaiting, qSuspended, qRunning, qReady. Return qUndefinedGlobalState if the current task its passing through a current kernel transaction

◆ qTask_Get_Name()

const char * qTask_Get_Name ( const qTask_t *const Task )

Retrieves the task name.

Parameters

[in] Task Pointer to the task node.

Returns: A pointer to the string containing the task name.

◆ qTask_Get_State()

qState_t qTask_Get_State ( const qTask_t *const Task )

Retrieve the task operational state.

Parameters

[in] Task Pointer to the task node.

Returns: Enabled or qDisabled if the task is Awaken. qAsleep if the task is in a Sleep operational state.

◆ qTask_Self()

qTask_t * qTask_Self ( void )

Get the current running-task handle.

Returns: A pointer to the current running task. NULL when the OS scheduler it's in a busy state or when IDLE Task is running.

◆ qTask_Set_Callback()

qBool_t qTask_Set_Callback	(	qTask_t *const	Task,
		const qTaskFcn_t	cFcn
	)

Set/Change the task callback function.

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

Parameters

[in]	Task	Pointer to the task node.
[in]	cFcn	A pointer to a void callback method with a qEvent_t parameter as input argument.

Returns: qTrue on success. Otherwise return qFalse.

◆ qTask_Set_Data()

qBool_t qTask_Set_Data	(	qTask_t *const	Task,
		void *	arg
	)

Set the task data.

Parameters

[in]	Task	Pointer to the task node.
[in]	arg	The task storage pointer. User data.

Returns: qTrue on success. Otherwise return qFalse.

◆ qTask_Set_Iterations()

qBool_t qTask_Set_Iterations	(	qTask_t *const	Task,
		const qIteration_t	iValue
	)

Set/Change the number of task iterations.

Parameters

[in]	Task	Pointer to the task node.
[in]	iValue	Number of task executions (Integer value). For indefinite execution (iValue = qPeriodic or qIndefinite). 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.

Returns: qTrue on success. Otherwise return qFalse.

◆ qTask_Set_Name()

qBool_t qTask_Set_Name	(	qTask_t *const	Task,
		const char *	name
	)

Set the task name.

Note: Name should be unique.

Parameters

[in]	Task	Pointer to the task node.
[in]	name	A string with the task name

Returns: qTrue on success. Otherwise return qFalse.

◆ qTask_Set_Priority()

qBool_t qTask_Set_Priority	(	qTask_t *const	Task,
		const qPriority_t	pValue
	)

Set/Change the task priority value.

Parameters

[in]	Task	Pointer to the task node.
[in]	pValue	Priority Value. [0(min) - `Q_PRIORITY_LEVELS` (max)]

Returns: qTrue on success. Otherwise return qFalse.

◆ qTask_Set_State()

qBool_t qTask_Set_State	(	qTask_t *const	Task,
		const qState_t	s
	)

Set the task operational state.

See also: qTask_Suspend, qTask_Disable, qTask_Resume, qTask_Enable, qTask_ASleep, qTask_Awake

Parameters

[in]	Task	Pointer to the task node.
[in]	s	Use one of the following values:

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

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

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

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

Returns: qTrue on success. Otherwise return qFalse.

◆ qTask_Set_Time()

qBool_t qTask_Set_Time	(	qTask_t *const	Task,
		const qTime_t	tValue
	)

Set/Change the Task execution interval.

Parameters

[in]	Task	Pointer to the task node.
[in]	tValue	Execution interval defined in seconds (floating-point format). For immediate execution (tValue = qTimeImmediate).

Returns: qTrue on success, otherwise returns qFalse.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ qTask_ASleep

◆ qTask_Awake

◆ qTask_Disable

◆ qTask_Enable

◆ qTask_IsEnabled

◆ qTask_Resume

◆ qTask_Suspend

Enumeration Type Documentation

◆ qQueueLinkMode_t

◆ qTask_GlobalState_t

◆ qTrigger_t

Function Documentation

◆ qTask_Clear()

◆ qTask_Find_ByName()

◆ qTask_Get_Cycles()

◆ qTask_Get_GlobalState()

◆ qTask_Get_Name()

◆ qTask_Get_State()

◆ qTask_Self()

◆ qTask_Set_Callback()

◆ qTask_Set_Data()

◆ qTask_Set_Iterations()

◆ qTask_Set_Name()

◆ qTask_Set_Priority()

◆ qTask_Set_State()

◆ qTask_Set_Time()