Task Control

Group that contains macros & functions to control tasks. More...

Collaboration diagram for Task Control:

Functions
void	vTaskDelay (const TickType_t xTicksToDelay) PRIVILEGED_FUNCTION
	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. More...
void	vTaskDelayUntil (TickType_t *const pxPreviousWakeTime, const TickType_t xTimeIncrement) PRIVILEGED_FUNCTION
	Delay a task until a specified time. This function can be used by periodic tasks to ensure a constant execution frequency. More...
BaseType_t	xTaskAbortDelay (TaskHandle_t xTask) PRIVILEGED_FUNCTION
UBaseType_t	uxTaskPriorityGet (TaskHandle_t xTask) PRIVILEGED_FUNCTION
	Obtain the priority of any task. More...
UBaseType_t	uxTaskPriorityGetFromISR (TaskHandle_t xTask) PRIVILEGED_FUNCTION
	A version of uxTaskPriorityGet() that can be used from an ISR.
void	vTaskSuspend (TaskHandle_t xTaskToSuspend) PRIVILEGED_FUNCTION
	Suspend any task. When suspended a task will never get any microcontroller processing time, no matter what its priority. More...
void	vTaskResume (TaskHandle_t xTaskToResume) PRIVILEGED_FUNCTION
	Resumes a suspended task. More...
BaseType_t	xTaskResumeFromISR (TaskHandle_t xTaskToResume) PRIVILEGED_FUNCTION
	An implementation of vTaskResume() that can be called from within an ISR. More...

Detailed Description

Group that contains macros & functions to control tasks.

Function Documentation

uxTaskPriorityGet()

UBaseType_t uxTaskPriorityGet

(

TaskHandle_t

xTask

)

#include <task.h>

Obtain the priority of any task.

Precondition

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

Parameters

xTask

Handle of the task to be queried. Passing a NULL handle results in the priority of the calling task being returned.

Returns

The priority of xTask.

Example usage:

void vAFunction( void )
{
TaskHandle_t xHandle;
 
    // Create a task, storing the handle.
    xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle );
 
    // ...
 
    // Use the handle to obtain the priority of the created task.
    // It was created with tskIDLE_PRIORITY, but may have changed
    // it itself.
    if( uxTaskPriorityGet( xHandle ) != tskIDLE_PRIORITY )
    {
        // The task has changed it's priority.
    }
 
    // ...
 
    // Is our priority higher than the created task?
    if( uxTaskPriorityGet( xHandle ) < uxTaskPriorityGet( NULL ) )
    {
        // Our priority (obtained using NULL handle) is higher.
    }
}

vTaskDelay()

void vTaskDelay

(

const TickType_t

xTicksToDelay

)

#include <task.h>

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.

Precondition

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

vTaskDelay() specifies a time at which the task wishes to unblock relative to the time at which vTaskDelay() is called. For example, specifying a block period of 100 ticks will cause the task to unblock 100 ticks after vTaskDelay() is called. vTaskDelay() 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 effect the frequency at which vTaskDelay() gets called and therefore the time at which the task next executes. See vTaskDelayUntil() 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

xTicksToDelay

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

Example usage:

void vTaskFunction( void * pvParameters )
{
   // Block for 500ms.
   const TickType_t xDelay = 500 / portTICK_PERIOD_MS;
 
    for( ;; )
    {
        // Simply toggle the LED every 500ms, blocking between each toggle.
        vToggleLED();
        vTaskDelay( xDelay );
    }
}

vTaskDelayUntil()

void vTaskDelayUntil	(	TickType_t *const	pxPreviousWakeTime,
		const TickType_t	xTimeIncrement
	)

#include <task.h>

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

Precondition

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

This function differs from vTaskDelay() in one important aspect: vTaskDelay() will cause a task to block for the specified number of ticks from the time vTaskDelay() is called. It is therefore difficult to use vTaskDelay() by itself to generate a fixed execution frequency as the time between a task starting to execute and that task calling vTaskDelay() 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 vTaskDelay() specifies a wake time relative to the time at which the function is called, vTaskDelayUntil() specifies the absolute (exact) time at which it wishes to unblock.

The constant portTICK_PERIOD_MS can be used to calculate real time from the tick rate - with the resolution of one tick period.

Parameters

pxPreviousWakeTime	Pointer to a variable that holds the time at which the task was last unblocked. The variable must be initialised with the current time prior to its first use (see the example below). Following this the variable is automatically updated within vTaskDelayUntil().
xTimeIncrement	The cycle time period. The task will be unblocked at time *pxPreviousWakeTime + xTimeIncrement. Calling vTaskDelayUntil with the same xTimeIncrement parameter value will cause the task to execute with a fixed interface period.

Example usage:

// Perform an action every 10 ticks.
void vTaskFunction( void * pvParameters )
{
    TickType_t xLastWakeTime;
    const TickType_t xFrequency = 10;
 
    // Initialise the xLastWakeTime variable with the current time.
    xLastWakeTime = xTaskGetTickCount ();
    for( ;; )
    {
        // Wait for the next cycle.
        vTaskDelayUntil( &xLastWakeTime, xFrequency );
 
        // Perform action here.
    }
}

vTaskResume()

void vTaskResume

(

TaskHandle_t

xTaskToResume

)

#include <task.h>

Resumes a suspended task.

Precondition

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

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

Parameters

xTaskToResume

Handle to the task being readied.

Example usage:

void vAFunction( void )
{
TaskHandle_t xHandle;
 
    // Create a task, storing the handle.
    xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle );
 
    // ...
 
    // Use the handle to suspend the created task.
    vTaskSuspend( xHandle );
 
    // ...
 
    // The created task will not run during this period, unless
    // another task calls vTaskResume( xHandle ).
 
    //...
 
 
    // Resume the suspended task ourselves.
    vTaskResume( xHandle );
 
    // The created task will once again get microcontroller processing
    // time in accordance with its priority within the system.
}

vTaskSuspend()

void vTaskSuspend

(

TaskHandle_t

xTaskToSuspend

)

#include <task.h>

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

Precondition

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

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

Parameters

xTaskToSuspend

Handle to the task being suspended. Passing a NULL handle will cause the calling task to be suspended.

Example usage:

void vAFunction( void )
{
    TaskHandle_t xHandle;
 
    // Create a task, storing the handle.
    xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle );
 
    // ...
 
    // Use the handle to suspend the created task.
    vTaskSuspend( xHandle );
 
    // ...
 
    // The created task will not run during this period, unless
    // another task calls vTaskResume( xHandle ).
 
    //...
 
 
    // Suspend ourselves.
    vTaskSuspend( NULL );
 
    // We cannot get here unless another task calls vTaskResume
    // with our handle as the parameter.
}

xTaskAbortDelay()

BaseType_t xTaskAbortDelay

(

TaskHandle_t

xTask

)

#include <task.h>

Precondition

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 vTaskDelay() is called, or an event on an object, such as when xQueueReceive() or ulTaskNotifyTake() is called. If the handle of a task that is in the Blocked state is used in a call to xTaskAbortDelay() then the task will leave the Blocked state, and return from whichever function call placed the task into the Blocked state.

Parameters

xTask

The handle of the task to remove from the Blocked state.

Returns

If the task referenced by xTask was not in the Blocked state then pdFAIL is returned. Otherwise pdPASS is returned.

xTaskResumeFromISR()

BaseType_t xTaskResumeFromISR

(

TaskHandle_t

xTaskToResume

)

#include <task.h>

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

Precondition

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

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

xTaskResumeFromISR() should not be used to synchronise 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.

Parameters

xTaskToResume

Handle to the task being readied.

Returns

pdTRUE if resuming the task should result in a context switch, otherwise pdFALSE. This is used by the ISR to determine if a context switch may be required following the ISR.