[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 );
}