[Study FreeRTOS-API] 2.24 vTaskPrioritySet ()

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

void vTaskPrioritySet(TaskHandle_t pxTask,UBaseType_t uxNewPriority);

Summary
Changes the priority of a task.

Parameters
pxTask  The handle of the task being modified (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 change its own priority by passing NULL in place of a valid task
handle.
uxNewPriority  The priority to which the subject task will be set.  Priorities can be assigned
from 0, which is the lowest priority, to (configMAX_PRIORITIES – 1), which is the highest priority.
configMAX_PRIORITIES is defined in FreeRTOSConfig.h.  Passing a value above (configMAX_PRIORITIES – 1) will result in the priority assigned to the task being capped to the maximum legitimate value.


Return Values
None.

Notes
vTaskPrioritySet()  must  only  be  called  from  an  executing  task,  and  therefore  must  not  be
called while the scheduler is in the Initialization state (prior to the scheduler being started).
It  is  possible  to  have  a  set  of  tasks  that  are  all  blocked  waiting  for  the  same  queue  or
semaphore event.  These tasks will be ordered according to their priority  –  for example,  the
first event will unblock the highest priority task  that was waiting for the event, the second event
will  unblock  the  second  highest  priority  task  that  was  originally  waiting  for  the  event,  etc.
Using vTaskPrioritySet() to change the priority of  such a blocked task will not cause the  order
in which the blocked tasks are assessed to be re-evaluated.


Example
void vAFunction( void )
{
TaskHandle_t xHandle;
/* Create a task, storing the handle of the created task in xHandle. */
if( xTaskCreate( vTaskCode,
"Demo task",
STACK_SIZE,
NULL,
PRIORITY,
&xHandle
) != pdPASS )
{
/* The task was not created successfully. */
}
else
{
/* Use the handle to raise the priority of the created task. */
vTaskPrioritySet( xHandle, PRIORITY + 1 );

/* Use NULL in place of a valid task handle to set the priority of the
calling task to 1. */
vTaskPrioritySet( NULL, 1 );
}
}