xTaskNotifyStateClear / xTaskNotifyStateClearIndexed
[ RTOS任务通知API ]

task.h

 BaseType_t xTaskNotifyStateClear( TaskHandle_t xTask );


 BaseType_t xTaskNotifyStateClearIndexed( TaskHandle_t xTask, 
                                          UBaseType_t uxIndexToClear );

每个 RTOS 任务都有一个任务通知数组。 每条任务通知 都有通知状态 ，可以是“挂起”或“非挂起” ， 以及一个 32 位通知值。

如果通知被发送到通知数组中的索引，那么 该索引处的通知被称为“待定” ，直到任务读取 其通知值，或通过调用 xTaskNotifyStateClear () 将通知状态明确清除为“非挂起”为止 。

xTaskNotifyStateClear () 和 xTaskNotifyStateClearIndexed () 是等效宏——唯一的区别 是 xTaskNotifyStateClearIndexed () 可以在数组内任何任务通知上运行，而 xTaskNotifyStateClear () 始终在数组索引 0 处的任务通知上运行。

configUSE_TASK_NOTIFICATIONS 必须在 FreeRTOSConfig.h 中设置为 1（或保留为未定义）才能使用这些宏。 常量 configTASK_NOTIFICATION_ARRAY_ENTRIES 设置 任务通知的每个任务数组中的索引数量。

向后兼容性信息：
在 FreeRTOS V10.4.0 之前，每个任务有一个单一的“通知值”，且 所有任务通知 API 函数都在该值上运行。用通知值的数组 更换单个通知值需要 新的 API 函数集，该函数集应能在数组内处理 。 xTaskNotifyStateClear () 是原始 API 函数，并且 通过始终在数组内索引 0 处的通知值上操作来保留向后兼容性 。调用 xTaskNotifyStateClear () 等于调用 xTaskNotifyStateClearIndexed ()，其中 uxIndexToNotify 参数设置为 0。

参数：

xTask	将收到此通知的 RTOS 任务的句柄 状态已清除。 将 xTask 设置为 NULL 以清除通知 调用任务的状态。 要获取任务句柄，请使用 xTaskCreate() 创建任务并使用 pxCreatedTask 参数，或使用返回值创建任务 xTaskCreateStatic() 并存储该值，或在 调用 xTaskGetHandle() 中使用任务的名称。 当前执行的 RTOS 任务的句柄通过以下方式 由 xTaskGetCurrentTaskHandle() API 函数返回。
uxIndexToClear	待采取行动通知值索引内的目标任务数组 。 例如，将 uxIndexToClear 设置为 1 将清除数组内索引为 1 时的通知状态。 uxIndexToClear must be less than configTASK_NOTIFICATION_ARRAY_ENTRIES。 ulTaskNotifyStateClear() 没有此参数，并且始终作用于 索引 0 的通知上。

返回：

如果 xTask 引用的任务有挂起的通知，则通知 已清除，然后返回 pdTRUE。 如果 xTask 引用的任务 有待处理的通知，那么返回 pdFALSE。

用法示例：

[更多示例来自主 RTOS 任务通知页面]

/* An example UART send function.  The function starts a UART transmission then

waits to be notified that the transmission is complete.  The transmission

complete notification is sent from the UART interrupt.  The calling task's

notification state is cleared before the transmission is started to ensure it is

not co-incidentally already pending before the task attempts to block on its

notification state. */

void vSerialPutString( const signed char * const pcStringToSend,

                       unsigned short usStringLength )

{

const TickType_t xMaxBlockTime = pdMS_TO_TICKS( 5000 );



    /* xSendingTask holds the handle of the task waiting for the transmission to

    complete.  If xSendingTask is NULL then a transmission is not in progress.

    Don't start to send a new string unless transmission of the previous string

    is complete. */

    if( ( xSendingTask == NULL ) && ( usStringLength > 0 ) )

    {

        /* Ensure the calling task's 0th notification state is not already

        pending. */

        xTaskNotifyStateClearIndexed( NULL, 0 );



        /* Store the handle of the transmitting task.  This is used to unblock

        the task when the transmission has completed. */

        xSendingTask = xTaskGetCurrentTaskHandle();



        /* Start sending the string - the transmission is then controlled by an

        interrupt. */

        UARTSendString( pcStringToSend, usStringLength );



        /* Wait in the Blocked state (so not using any CPU time) until the UART

        ISR sends the 0th notification to xSendingTask to notify (and unblock) the

        task when the transmission is complete. */

        ulTaskNotifyTakeIndexed( 0, pdTRUE, xMaxBlockTime );

    }

}