[Study FreeRTOS-API] 2.35 taskYIELD()

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

void taskYEILD(void);


Summary
Yield to another task of equal priority.
Yielding is where a task volunteers to leave the Running state,  without being pre-empted,  and
before its time slice has been fully utilized.


Parameters
None.

Return Values
None.


Notes
taskYIELD() 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).
When  a  task  calls  taskYIELD(),  the  scheduler will  select  another  Ready  state  task  of  equal
priority to enter the Running state in its place. If there are no other Ready state tasks of equal
priority  then  the task that  called  taskYIELD()  will  itself  be transitioned  straight  back  into  the
Running state.
The scheduler will only ever select a task of equal priority to the task that called taskYIELD()
because, if there were any tasks of higher priority that were in the Ready state, the task that
called taskYIELD() would not have been executing in the first place.


Example 
void vATask( void * pvParameters)
{
for( ;; )
{
/* Perform some actions. */
/* If there are any tasks of equal priority to this task that are in the
Ready state then let them execute now - even though this task has not used
all of its time slice. */

taskYIELD();

/* If there were any tasks of equal priority to this task in the Ready state,
then they will have executed before this task reaches here. */
}