[Study FreeRTOS-Task API] 2.10 vTaskDelayUntil()

#include "FreeRTOS.h"
#include "task.h"

void vTaskDelayUntil(TickType_t *pxPreviousWakeTime,TickType_t xTimeIncrement);

Summary
Places  the  task  that  calls  vTaskDelayUntil()  into  the  Blocked  state  until  an  absolute  time  is
reached.
Periodic tasks can use vTaskDelayUntil() to achieve a constant execution frequency.
Differences Between vTaskDelay() and  vTaskDelayUntil()
vTaskDelay()  results in  the calling task  entering into the Blocked state, and then remaining in
the  Blocked  state,  for the  specified  number  of ticks from the  time  vTaskDelay()  was  called.
The time at which the task  that called vTaskDelay()  exits the Blocked state is  relative  to when
vTaskDelay() was called.
vTaskDelayUntil()  results  in  the  calling  task  entering  into  the  Blocked  state,  and  then
remaining in the Blocked state, until an  absolute  time has been reached. The task that called
vTaskDelayUntil()  exits  the  Blocked state  exactly  at  the  specified  time, not  at  a  time that  is
relative to when vTaskDelayUntil() was called.

Parameters
pxPreviousWakeTime - This parameter is named on the assumption that vTaskDelayUntil() is
being used to implement a task that executes periodically and with a fixed frequency. In this case pxPreviousWakeTime holds the time at which the task last left the Blocked state (was ‘woken’ up). This time is used as a reference point to calculate the time at which t he task should next leave the
Blocked state.
The variable pointed to by pxPreviousWakeTime is updated automatically within the vTaskDelayUntil() function; it would not normally be modified by the application code, other than when the variable is first initialized.  The example in this section demonstrates
how the initialization is performed.
xTimeIncrement  This parameter is also named on the assumption that
vTaskDelayUntil() is being used to implement a task that executes
periodically and with a fixed frequency – the frequency being set by
the xTimeIncrement value.
xTimeIncrement is specified in ‘ticks’. The pdMS_TO_TICKS() macro
can be used to convert milliseconds to ticks.

Return Values
None.

Notes
INCLUDE_vTaskDelayUntil  must be set to 1 in FreeRTOSConfig.h for the vTaskDelay() API
function to be available.


Example 
/* Define a task that performs an action every 50 milliseconds. */
void vCyclicTaskFunction( void * pvParameters )
{
TickType_t xLastWakeTime;
const TickType_t xPeriod = pdMS_TO_TICKS( 50 );
/* The xLastWakeTime variable needs to be initialized with the current tick count. Note that this is the only time the variable is written to explicitly.After this assignment, xLastWakeTime is updated automatically internally within vTaskDelayUntil(). */
xLastWakeTime = xTaskGetTickCount();

/* Enter the loop that defines the task behavior. */
for( ;; )
{
/* This task should execute every 50 milliseconds. Time is measured in ticks. The pdMS_TO_TICKS macro is used to convert milliseconds into ticks. xLastWakeTime is automatically updated within vTaskDelayUntil() so is not explicitly updated by the task. */
vTaskDelayUntil( &xLastWakeTime, xPeriod );

/* Perform the periodic actions here. */
}
}

[Study FreeRTOS-Task API] 2.11 vTaskDelete ( )

#include "FreeRTOS.h"
#include "task.h"

void vTaskDelete(TaskHandle_t pxTask);

Summary
Deletes  an  instance  of  a  task  that  was  previously  created  using  a  call  to  xTaskCreate()  or
xTaskCreateStatic().
Deleted tasks no longer exist so cannot enter the Running state.
Do not attempt to use a task handle to reference a task that has been deleted.
When a task is deleted, it is the responsibility of the idle task to free the memory that had been
used to hold the deleted task’s stack and data structures (task  control block).  Therefore, if an
application  makes  use  of  the  vTaskDelete()  API  function,  it  is  vital  that  the  application  also
ensures the idle task is not starved of processing time (the idle task must be allocated time in
the Running state).
Only memory that is allocated to a task by the kernel itself is automatically freed when a task is
deleted.  Memory,  or any other resource,  that the  application (rather than the kernel) allocates
to a task must be explicitly freed by the application when the task is deleted.


Parameters
pxTask  The handle of the task being deleted (the subject task).
To obtain a task’s handle create the task using xTaskCreate() and make use of the pxCreatedTask parameter, or create the task using xTaskCreateStatic() and store the returned value, or use the task’s name in a call to xTaskGetHandle().
A task can delete itself by passing NULL in place of a valid task handle.

Return Values
None.


Example
void vAnotherFunction( void )
{
TaskHandle_t xHandle;
/* Create a task, storing the handle to the created task in xHandle. */
if(
xTaskCreate(
vTaskCode,
"Demo task",
STACK_SIZE,
NULL,
PRIORITY,
&xHandle /* The address of xHandle is passed in as the last parameter to xTaskCreate() to obtain a handle to the task being created. */
)
!= pdPASS )
{
/* The task could not be created because there was not enough FreeRTOS heap memory available for the task data structures and stack to be allocated. */
}
else
{
/* Delete the task just created. Use the handle passed out of xTaskCreate() to reference the subject task. */
vTaskDelete( xHandle );
}
/* Delete the task that called this function by passing NULL in as the vTaskDelete() parameter. The same task (this task) could also be deleted by passing in a valid handle to itself. */
vTaskDelete( NULL );
}