[Study FreeRTOS - API ] 2.3 xTaskAbortDelay()

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

BaseType_t xTaskAbortDelay(TaskHandle_t xTask);

Summary
Calling an API function that includes a timeout parameter can result in the calling task entering
the Blocked state. A task that is in the Blocked state is either waiting for a timeout period to
elapse, or waiting with a timeout for an event to occur, after which the task will automatically
leave  the  Blocked  state  and  enter  the  Ready  state.   There  are  many  examples  of  this
behavior, two of which are:

  If a task calls vTaskDelay() it will enter the Blocked state until the timeout specified by
the function’s parameter has elapsed, at which time the task will automatically leave
the Blocked state and enter the Ready state.

  If  a  task  calls  ulTaskNotifyTake()  when  its  notification  value  is  zero  it  will  enter  the
Blocked state until either it receives a notification or the timeout specified by one of the
function’s  parameters has elapsed, at which time the task will automatically leave the
Blocked state and enter the Ready state.

xTaskAbortDelay() will move a task from the Blocked state to the Ready state even if the event
the task is waiting for has not occurred, and the timeout specified when t he task entered the
Blocked state has not elapsed.
While a task is in the Blocked state it is not available to the scheduler, and will not consume
any processing time.


Parameters

xTask  The handle of the task that will be moved out of the Blocked state.
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().

Returned value
If the task referenced by xTask was removed from the Blocked state then
pdPASS is returned. If the task referenced by xTask was not removed from the
Blocked state because it was not in the Blocked state then pdFAIL is returned.


Notes
INCLUDE_xTaskAbortDelay must be set to 1 in FreeRTOSConfig.h for xTaskAbortDelay() to
be available.


Example
void vAFunction( TaskHandle_t xTask )
{
/* The task referenced by xTask is blocked to wait for something that the task calling
this function has determined will never happen. Force the task referenced by xTask
out of the Blocked state. */
if( xTaskAbortDelay( xTask ) == pdFAIL )
{
/* The task referenced by xTask was not in the Blocked state anyway. */
}
else
{
/* The task referenced by xTask was in the Blocked state, but is not now. */
}