8 · 原书 292–319 页事件组
8.1本章引言与范围
前文已指出,实时嵌入式系统必须对事件做出响应。前几章介绍了 FreeRTOS 中可把事件通知给任务的特性,例如信号量和队列,二者都具有以下性质:
- 允许任务在阻塞态等待单个事件发生;
- 事件发生时只解除一个任务的阻塞——被解除阻塞的是等待该事件的最高优先级任务。
事件组是 FreeRTOS 中另一种把事件通知给任务的特性。与队列和信号量不同:
- 事件组允许任务在阻塞态等待一个或多个事件的某种组合发生;
- 事件发生时,解除所有等待同一事件(或同一事件组合)的任务的阻塞。
事件组这些独特性质使其可用于:同步多个任务、向多个任务广播事件、让任务在阻塞态等待一组事件中任意一个发生、让任务在阻塞态等待多个动作全部完成。事件组还有助于降低应用占用的 RAM:通常可用单个事件组替换许多二值信号量。
事件组功能是可选的;要包含事件组功能,需把 FreeRTOS 源文件 event_groups.c 纳入工程一起编译。
8.1.1范围
本章帮助读者理解:事件组的实际用途;事件组相对其他 FreeRTOS 特性的优缺点;如何在事件组中置位;如何在阻塞态等待事件组中的位置位;如何用事件组同步一组任务。
8.2事件组的特性
8.2.1事件组、事件标志与事件位
事件“标志”是一个布尔值(1 或 0),用于指示某事件是否已发生;事件“组”是一组事件标志的集合。事件标志只能取 1 或 0,因此其状态可用单个位保存,事件组中所有事件标志的状态可用单个变量保存:事件组中每个事件标志的状态,由 EventBits_t 类型变量中的一位表示。因此事件标志也称事件“位”。若 EventBits_t 变量中某一位为 1,表示该位代表的事件已发生;为 0 表示尚未发生。
EventBits_t 变量中,位 0 对应标志 0,位 8 对应标志 8,位 16 对应标志 16,依此类推,位 23 对应标志 23。例如事件组值为 0x92(二进制 1001 0010)时,只有事件位 1、4、7 被置位,即只有位 1、4、7 代表的事件已发生。图 72 展示一个 EventBits_t 变量:事件位 1、4、7 置位,其余位清零,事件组值为 0x92。
事件组中各个位的含义由应用编写者分配。例如编写者创建事件组后可:
- 定义位 0 表示“已从网络收到一条消息”;
- 定义位 1 表示“已有一条消息准备发送到网络”;
- 定义位 2 表示“中止当前网络连接”。
8.2.2关于 EventBits_t 数据类型
事件组中可用事件位的数量取决于 FreeRTOSConfig.h 中的编译期配置常量 configUSE_16_BIT_TICKS:
configUSE_16_BIT_TICKS为 1 时,每个事件组含 8 个可用事件位;configUSE_16_BIT_TICKS为 0 时,每个事件组含 24 个可用事件位。
configUSE_16_BIT_TICKS 配置的是保存 RTOS 节拍计数所用的类型,看似与事件组无关;它对 EventBits_t 类型的影响是 FreeRTOS 内部实现的结果。只有在 FreeRTOS 运行于处理 16 位类型比 32 位类型更高效的架构上时,才应把 configUSE_16_BIT_TICKS 设为 1。8.2.3多任务访问
事件组本身是独立对象,任何知道其存在的任务或 ISR 都可访问。任意数量的任务都可在同一事件组中置位,也可从同一事件组读位。
8.2.4使用事件组的实际例子
FreeRTOS+TCP TCP/IP 协议栈的实现提供了一个实际范例:事件组如何同时简化设计并最小化资源占用。TCP 套接字必须响应多种不同事件,例如 accept(接受连接)、bind(绑定)、read(读)、close(关闭)事件;套接字在任一时刻可能收到的事件取决于其状态。例如套接字已创建但尚未绑定地址,则可能收到 bind 事件,而不会收到 read 事件(没有地址就无法读数据)。
FreeRTOS+TCP 套接字状态保存在名为 FreeRTOS_Socket_t 的结构体中;该结构体包含一个事件组,为套接字必须处理的每个事件定义一个事件位。阻塞等待某个事件或某组事件的 FreeRTOS+TCP API 调用,直接在该事件组上阻塞。事件组还包含一个“中止”位,使 TCP 连接无论套接字当时正在等待哪个事件都能被中止。
8.3用事件组管理事件
8.3.1xEventGroupCreate() API 函数
FreeRTOS V9.0.0 还提供 xEventGroupCreateStatic(),在编译期静态分配创建事件组所需内存。事件组使用前必须显式创建。事件组用 EventGroupHandle_t 类型变量引用;xEventGroupCreate() 用于创建事件组,并返回一个 EventGroupHandle_t 作为所创建事件组的引用。
EventGroupHandle_t xEventGroupCreate( void );
| 返回值 | 说明 |
|---|---|
| 返回值 | 返回 NULL 表示因堆内存不足、FreeRTOS 无法分配事件组数据结构,事件组创建失败(堆管理见第 2 章);返回非 NULL 表示事件组创建成功,返回值应保存为所创建事件组的句柄。 |
8.3.2xEventGroupSetBits() API 函数
xEventGroupSetBits() 在事件组中置位一个或多个位,通常用于通知任务:被置位的位所代表的事件已经发生。注意:绝不能从中断服务程序调用 xEventGroupSetBits();应改用其中断安全版本 xEventGroupSetBitsFromISR()。
EventBits_t xEventGroupSetBits( EventGroupHandle_t xEventGroup,
const EventBits_t uxBitsToSet );| 参数名 | 说明 |
|---|---|
| xEventGroup | 要置位的事件组句柄;该句柄来自创建事件组时的 xEventGroupCreate() 调用。 |
| uxBitsToSet | 位掩码,指定要在事件组中置为 1 的事件位。事件组现有值与 uxBitsToSet 传入值按位或后更新。例如 uxBitsToSet 设为 0x04(二进制 0100),会把事件位 3 置位(若尚未置位),其余事件位保持不变。 |
| 返回值 | xEventGroupSetBits() 返回时事件组的值。注意返回值不一定包含 uxBitsToSet 指定的位,因为这些位可能已被另一个任务再次清零。 |
8.3.3xEventGroupSetBitsFromISR() API 函数
xEventGroupSetBitsFromISR() 是 xEventGroupSetBits() 的中断安全版本。给出信号量是确定性操作,因为事先可知给出信号量至多让一个任务退出阻塞态;而在事件组中置位时,事先不知道会有多少任务退出阻塞态,因此置位操作不是确定性操作。
FreeRTOS 的设计与实现标准不允许在中断服务程序内、或中断关闭期间执行非确定性操作。因此 xEventGroupSetBitsFromISR() 并不在 ISR 内直接置位,而是把该动作推迟到 RTOS 守护任务执行。
BaseType_t xEventGroupSetBitsFromISR( EventGroupHandle_t xEventGroup,
const EventBits_t uxBitsToSet,
BaseType_t *pxHigherPriorityTaskWoken );| 参数名 | 说明 |
|---|---|
| xEventGroup | 要置位的事件组句柄;来自创建事件组时的 xEventGroupCreate() 调用。 |
| uxBitsToSet | 位掩码,指定要置为 1 的事件位;事件组现有值与传入值按位或更新。例如设为 0x05(二进制 0101)会把事件位 3 和事件位 0 置位(若尚未置位),其余位不变。 |
| pxHigherPriorityTaskWoken | 本函数不在 ISR 内直接置位,而是通过向定时器命令队列发送命令,把动作推迟到守护任务。若守护任务当时在阻塞态等待定时器命令队列数据,写队列会使其退出阻塞态;若守护任务优先级高于当前被中断任务的优先级,函数内部会把 *pxHigherPriorityTaskWoken 置为 pdTRUE。若该值被置为 pdTRUE,退出中断前应执行一次上下文切换,确保中断直接返回到守护任务(它将是就绪态中优先级最高的任务)。 |
| 返回值 | 两种可能:① pdPASS——仅当数据成功发送到定时器命令队列时返回;② pdFALSE——因队列已满,“置位”命令无法写入定时器命令队列时返回。 |
8.3.4xEventGroupWaitBits() API 函数
xEventGroupWaitBits() 允许任务读取事件组的值;若事件位尚未置位,还可选择在阻塞态等待事件组中一个或多个事件位置位。
EventBits_t xEventGroupWaitBits( const EventGroupHandle_t xEventGroup,
const EventBits_t uxBitsToWaitFor,
const BaseType_t xClearOnExit,
const BaseType_t xWaitForAllBits,
TickType_t xTicksToWait );调度器用于判定任务何时进入阻塞态、何时退出阻塞态的条件称为“解除阻塞条件”。解除阻塞条件由 uxBitsToWaitFor 与 xWaitForAllBits 两个参数组合指定:uxBitsToWaitFor 指定要测试事件组中的哪些事件位;xWaitForAllBits 指定使用按位或测试还是按位与测试。调用 xEventGroupWaitBits() 时若解除阻塞条件已满足,任务不会进入阻塞态。
表 45 给出任务进入或退出阻塞态的条件示例;表中只显示事件组值与 uxBitsToWaitFor 值的最低 4 个二进制位,其余位假定为 0。
| 现有事件组值 | uxBitsToWaitFor | xWaitForAllBits | 结果行为 |
|---|---|---|---|
| 0000 | 0101 | pdFALSE | 调用任务进入阻塞态:事件组中位 0 与位 2 都未置位;当位 0 或 位 2 任一置位时退出阻塞态。 |
| 0100 | 0101 | pdTRUE | 调用任务进入阻塞态:位 0 与位 2 未同时置位;当位 0 与 位 2 都置位时退出阻塞态。 |
| 0100 | 0110 | pdFALSE | 调用任务不进入阻塞态:xWaitForAllBits 为 pdFALSE,且 uxBitsToWaitFor 指定的两位中已有一位在事件组中置位。 |
| 0100 | 0110 | pdTRUE | 调用任务进入阻塞态:xWaitForAllBits 为 pdTRUE,指定的两位中只有一位已置位;当位 2 与位 3 都置位时退出阻塞态。 |
调用任务用 uxBitsToWaitFor 指定要测试的位;解除阻塞条件满足后,调用任务很可能需要把这些位清回 0。事件位可用 xEventGroupClearBits() 清零,但在以下情况下手动清零会在应用代码中引入竞态条件:① 有多个任务使用同一事件组;② 事件组中的位由另一个任务或中断服务程序置位。提供 xClearOnExit 参数正是为避免这些潜在竞态:若 xClearOnExit 设为 pdTRUE,对事件位的测试与清零对调用任务表现为一次原子操作(不被其他任务或中断打断)。
| 参数名 | 说明 |
|---|---|
| xEventGroup | 包含待读取事件位的事件组句柄;来自创建事件组时的 xEventGroupCreate() 调用。 |
| uxBitsToWaitFor | 位掩码,指定要在事件组中测试的事件位。例如任务想等待事件位 0 和/或位 2 置位,把 uxBitsToWaitFor 设为 0x05(二进制 0101);更多示例见表 45。 |
| xClearOnExit | 若调用任务的解除阻塞条件已满足,且 xClearOnExit 设为 pdTRUE,则在调用任务退出 xEventGroupWaitBits() 前,uxBitsToWaitFor 指定的事件位被清回 0;若设为 pdFALSE,事件位状态不被本函数修改。 |
| xWaitForAllBits | 指定调用任务是在 uxBitsToWaitFor 指定的事件位中一个或多个置位时退出阻塞态,还是仅在全部置位时退出。设为 pdFALSE:任一指定位置位(或 xTicksToWait 超时到期)即退出;设为 pdTRUE:全部指定位置位(或超时到期)才退出。示例见表 45。 |
| xTicksToWait | 任务为等待解除阻塞条件满足而停留在阻塞态的最长时间。xTicksToWait 为 0,或调用时条件已满足,函数立即返回。阻塞时间以节拍为单位,绝对时间取决于节拍频率;可用 pdMS_TO_TICKS() 把毫秒换算成节拍。设为 portMAX_DELAY 时任务无限等待(不超时),前提是 FreeRTOSConfig.h 中 INCLUDE_vTaskSuspend 为 1。 |
| 返回值 | 若因解除阻塞条件满足而返回,返回值是条件满足时事件组的值(若 xClearOnExit 为 pdTRUE,则在自动清零之前),该返回值也满足解除阻塞条件;若因 xTicksToWait 指定的阻塞时间到期而返回,返回值是阻塞时间到期时事件组的值,此时不满足解除阻塞条件。 |
8.3.5示例 22:实验事件组
本例演示:创建事件组;从中断服务程序在事件组中置位;从任务在事件组中置位;在事件组上阻塞。xEventGroupWaitBits() 的 xWaitForAllBits 参数效果,分别在其设为 pdFALSE 和 pdTRUE 时各执行一次示例加以演示。事件位 0、1 由任务置位,事件位 2 由中断服务程序置位;这三个位用清单 136 的 #define 语句起描述性名称。
/* Definitions for the event bits in the event group. */ #define mainFIRST_TASK_BIT ( 1UL << 0UL ) /* Event bit 0, which is set by a task. */ #define mainSECOND_TASK_BIT ( 1UL << 1UL ) /* Event bit 1, which is set by a task. */ #define mainISR_BIT ( 1UL << 2UL ) /* Event bit 2, which is set by an ISR. */
清单 137 给出置位事件位 0 和事件位 1 的任务实现:任务在循环中反复先置一个位、再置另一个位,两次 xEventGroupSetBits() 调用之间延时 200 毫秒;每次置位前打印一条字符串,便于在控制台观察执行序列。
static void vEventBitSettingTask( void *pvParameters )
{
const TickType_t xDelay200ms = pdMS_TO_TICKS( 200UL ), xDontBlock = 0;
for( ;; )
{
/* Delay for a short while before starting the next loop. */
vTaskDelay( xDelay200ms );
/* Print out a message to say event bit 0 is about to be set by the task,
then set event bit 0. */
vPrintString( "Bit setting task -\t about to set bit 0.\r\n" );
xEventGroupSetBits( xEventGroup, mainFIRST_TASK_BIT );
/* Delay for a short while before setting the other bit. */
vTaskDelay( xDelay200ms );
/* Print out a message to say event bit 1 is about to be set by the task,
then set event bit 1. */
vPrintString( "Bit setting task -\t about to set bit 1.\r\n" );
xEventGroupSetBits( xEventGroup, mainSECOND_TASK_BIT );
}
}清单 138 给出在事件组置位 2 的中断服务程序实现。同样在置位前打印字符串以便观察序列;但由于控制台输出不应在 ISR 内直接执行,本例用 xTimerPendFunctionCallFromISR() 在 RTOS 守护任务上下文中完成输出。与前面示例一样,ISR 由一个简单周期性任务触发软件中断;本例每 500 毫秒产生一次中断。
static uint32_t ulEventBitSettingISR( void )
{
/* The string is not printed within the interrupt service routine, but is instead
sent to the RTOS daemon task for printing. It is therefore declared static to ensure
the compiler does not allocate the string on the stack of the ISR, as the ISR's stack
frame will not exist when the string is printed from the daemon task. */
static const char *pcString = "Bit setting ISR -\t about to set bit 2.\r\n";
BaseType_t xHigherPriorityTaskWoken = pdFALSE;
/* Print out a message to say bit 2 is about to be set. Messages cannot be
printed from an ISR, so defer the actual output to the RTOS daemon task by
pending a function call to run in the context of the RTOS daemon task. */
xTimerPendFunctionCallFromISR( vPrintStringFromDaemonTask,
( void * ) pcString,
0,
&xHigherPriorityTaskWoken );
/* Set bit 2 in the event group. */
xEventGroupSetBitsFromISR( xEventGroup, mainISR_BIT, &xHigherPriorityTaskWoken );
/* xTimerPendFunctionCallFromISR() and xEventGroupSetBitsFromISR() both write to
the timer command queue, and both used the same xHigherPriorityTaskWoken
variable. If writing to the timer command queue resulted in the RTOS daemon task
leaving the Blocked state, and if the priority of the RTOS daemon task is higher
than the priority of the currently executing task (the task this interrupt
interrupted) then xHigherPriorityTaskWoken will have been set to pdTRUE.
.
xHigherPriorityTaskWoken is used as the parameter to portYIELD_FROM_ISR(). If
xHigherPriorityTaskWoken equals pdTRUE, then calling portYIELD_FROM_ISR() will
request a context switch. If xHigherPriorityTaskWoken is still pdFALSE, then
calling portYIELD_FROM_ISR() will have no effect.
The implementation of portYIELD_FROM_ISR() used by the Windows port includes a
return statement, which is why this function does not explicitly return a
value. */
portYIELD_FROM_ISR( xHigherPriorityTaskWoken );
}清单 139 给出调用 xEventGroupWaitBits() 在事件组上阻塞的任务实现;事件组中每置一位,任务就打印一条字符串。xClearOnExit 参数设为 pdTRUE,因此导致 xEventGroupWaitBits() 返回的事件位(一个或多个)会在函数返回前自动清零。
static void vEventBitReadingTask( void *pvParameters )
{
EventBits_t xEventGroupValue;
const EventBits_t xBitsToWaitFor = ( mainFIRST_TASK_BIT |
mainSECOND_TASK_BIT |
mainISR_BIT );
for( ;; )
{
/* Block to wait for event bits to become set within the event group. */
xEventGroupValue = xEventGroupWaitBits( /* The event group to read. */
xEventGroup,
/* Bits to test. */
xBitsToWaitFor,
/* Clear bits on exit if the
unblock condition is met. */
pdTRUE,
/* Don't wait for all bits. This
parameter is set to pdTRUE for the
second execution. */
pdFALSE,
/* Don't time out. */
portMAX_DELAY );
/* Print a message for each bit that was set. */
if( ( xEventGroupValue & mainFIRST_TASK_BIT ) != 0 )
{
vPrintString( "Bit reading task -\t Event bit 0 was set\r\n" );
}
if( ( xEventGroupValue & mainSECOND_TASK_BIT ) != 0 )
{
vPrintString( "Bit reading task -\t Event bit 1 was set\r\n" );
}
if( ( xEventGroupValue & mainISR_BIT ) != 0 )
{
vPrintString( "Bit reading task -\t Event bit 2 was set\r\n" );
}
}
}main() 在启动调度器前创建事件组和任务,实现见清单 140。从事件组读取的任务优先级高于向事件组写入的任务,确保读取任务每次解除阻塞条件满足时都抢占写入任务。
int main( void )
{
/* Before an event group can be used it must first be created. */
xEventGroup = xEventGroupCreate();
/* Create the task that sets event bits in the event group. */
xTaskCreate( vEventBitSettingTask, "Bit Setter", 1000, NULL, 1, NULL );
/* Create the task that waits for event bits to get set in the event group. */
xTaskCreate( vEventBitReadingTask, "Bit Reader", 1000, NULL, 2, NULL );
/* Create the task that is used to periodically generate a software interrupt. */
xTaskCreate( vInterruptGenerator, "Int Gen", 1000, NULL, 3, NULL );
/* Install the handler for the software interrupt. The syntax necessary to do
this is dependent on the FreeRTOS port being used. The syntax shown here can
only be used with the FreeRTOS Windows port, where such interrupts are only
simulated. */
vPortSetInterruptHandler( mainINTERRUPT_NUMBER, ulEventBitSettingISR );
/* Start the scheduler so the created tasks start executing. */
vTaskStartScheduler();
/* The following line should never be reached. */
for( ;; );
return 0;
}xWaitForAllBits 设为 pdFALSE 时执行示例 22 的输出见图 73:可见由于 xWaitForAllBits 为 pdFALSE,每次任意一个事件位置位,读取任务就退出阻塞态并立即执行。

xWaitForAllBits 设为 pdTRUE 时的输出见图 74:可见由于参数为 pdTRUE,读取任务只在三个事件位全部置位后才退出阻塞态。

8.4用事件组同步任务
应用设计有时要求两个或更多任务相互同步。例如设想:Task A 收到一个事件,再把该事件所需的部分处理工作委派给另外三个任务 Task B、Task C、Task D;在 B、C、D 全部完成上一事件处理之前,Task A 不能再接收下一事件,于是四个任务都需要相互同步。每个任务的同步点在其完成自身处理之后;在其他每个任务都完成之前,它不能继续前进。只有四个任务都到达同步点后,Task A 才能接收下一事件。
这类任务同步需求的一个不那么抽象的例子来自某个 FreeRTOS+TCP 演示工程:演示在两个任务之间共享一个 TCP 套接字,一个任务向套接字发送数据,另一个任务从同一套接字接收数据。在确信对方不会再访问套接字之前,任一任务关闭套接字都不安全。若两个任务中任一方想关闭套接字,必须告知对方意图,然后等待对方停止使用套接字后再继续。清单 141 伪代码演示“发送数据的任务想关闭套接字”的场景。
清单 141 场景很简单,因为只有两个任务需要相互同步;但若还有其他任务执行依赖套接字保持打开的处理,场景会变得更复杂、需要更多任务加入同步。
void SocketTxTask( void *pvParameters )
{
xSocket_t xSocket;
uint32_t ulTxCount = 0UL;
for( ;; )
{
/* Create a new socket. This task will send to this socket, and another task will receive
from this socket. */
xSocket = FreeRTOS_socket( ... );
/* Connect the socket. */
FreeRTOS_connect( xSocket, ... );
/* Use a queue to send the socket to the task that receives data. */
xQueueSend( xSocketPassingQueue, &xSocket, portMAX_DELAY );
/* Send 1000 messages to the socket before closing the socket. */
for( ulTxCount = 0; ulTxCount < 1000; ulTxCount++ )
{
if( FreeRTOS_send( xSocket, ... ) < 0 )
{
/* Unexpected error - exit the loop, after which the socket will be closed. */
break;
}
}
/* Let the Rx task know the Tx task wants to close the socket. */
TxTaskWantsToCloseSocket();
/* This is the Tx task’s synchronization point. The Tx task waits here for the Rx task to
reach its synchronization point. The Rx task will only reach its synchronization point
when it is no longer using the socket, and the socket can be closed safely. */
xEventGroupSync( ... );
/* Neither task is using the socket. Shut down the connection, then close the socket. */
FreeRTOS_shutdown( xSocket, ... );
WaitForSocketToDisconnect();
FreeRTOS_closesocket( xSocket );
}
}
/*-----------------------------------------------------------*/
void SocketRxTask( void *pvParameters )
{
xSocket_t xSocket;
for( ;; )
{
/* Wait to receive a socket that was created and connected by the Tx task. */
xQueueReceive( xSocketPassingQueue, &xSocket, portMAX_DELAY );
/* Keep receiving from the socket until the Tx task wants to close the socket. */
while( TxTaskWantsToCloseSocket() == pdFALSE )
{
/* Receive then process data. */
FreeRTOS_recv( xSocket, ... );
ProcessReceivedData();
}
/* This is the Rx task’s synchronization point - it only reaches here when it is no longer
using the socket, and it is therefore safe for the Tx task to close the socket. */
xEventGroupSync( ... );
}
}可用事件组创建同步点:① 每个必须参与同步的任务在事件组中分配一个唯一事件位;② 每个任务到达同步点时置位自己的事件位;③ 置位自己的位后,各任务在事件组上阻塞,等待代表其他所有同步任务的事件位也都置位。
但本场景不能用 xEventGroupSetBits() 与 xEventGroupWaitBits():若使用它们,置位(表示任务到达同步点)与测试位(判断其他同步任务是否到达同步点)会作为两个独立操作执行。设想 Task A、B、C 尝试用事件组同步:① A、B 已到达同步点,位已置位,处于阻塞态等待 C 的位也置位;② C 到达同步点,用 xEventGroupSetBits() 置位自己的位;C 的位一置位,A、B 退出阻塞态并清掉全部三个事件位;③ C 再调用 xEventGroupWaitBits() 等待三位都置位,但此时三位已被清零,A、B 已离开各自同步点,同步失败。
要用事件组成功创建同步点,置位事件位与随后测试事件位必须作为一次不可打断的操作完成;xEventGroupSync() API 函数正是为此提供。
8.4.1xEventGroupSync() API 函数
xEventGroupSync() 用于让两个或更多任务用事件组相互同步:函数允许任务在事件组中置位一个或多个事件位,然后等待同一事件组中某组事件位置位,整个过程作为一次不可打断的操作。uxBitsToWaitFor 参数指定调用任务的解除阻塞条件;若因条件满足而返回,返回前 uxBitsToWaitFor 指定的事件位会被清回 0。
EventBits_t xEventGroupSync( EventGroupHandle_t xEventGroup,
const EventBits_t uxBitsToSet,
const EventBits_t uxBitsToWaitFor,
TickType_t xTicksToWait );| 参数名 | 说明 |
|---|---|
| xEventGroup | 要置位并随后测试事件位的事件组句柄;来自创建事件组时的 xEventGroupCreate() 调用。 |
| uxBitsToSet | 位掩码,指定要置为 1 的事件位;事件组现有值与传入值按位或更新。例如设为 0x04(二进制 0100)会把事件位 3 置位(若尚未置位),其余位不变。 |
| uxBitsToWaitFor | 位掩码,指定要测试的事件位。例如调用任务想等待事件位 0、1、2 都置位,把 uxBitsToWaitFor 设为 0x07(二进制 111)。 |
| xTicksToWait | 任务为等待解除阻塞条件满足而停留在阻塞态的最长时间。xTicksToWait 为 0,或调用时条件已满足,函数立即返回。阻塞时间以节拍为单位,绝对时间取决于节拍频率;可用 pdMS_TO_TICKS() 换算毫秒。设为 portMAX_DELAY 时无限等待(不超时),前提是 INCLUDE_vTaskSuspend 为 1。 |
| 返回值 | 若因解除阻塞条件满足而返回,返回值是条件满足时事件组的值(自动清零之前),该值也满足解除阻塞条件;若因阻塞时间到期而返回,返回值是到期时事件组的值,不满足解除阻塞条件。 |
8.4.2示例 23:同步任务
示例 23 用 xEventGroupSync() 同步单一任务实现的三个实例;任务参数用于向每个实例传入它调用 xEventGroupSync() 时要置位的事件位。任务在调用 xEventGroupSync() 前打印一条消息,调用返回后再打印一条消息,每条消息带时间戳,便于在输出中观察执行序列。伪随机延时用于避免所有任务同时到达同步点。任务实现见清单 143。
static void vSyncingTask( void *pvParameters )
{
const TickType_t xMaxDelay = pdMS_TO_TICKS( 4000UL );
const TickType_t xMinDelay = pdMS_TO_TICKS( 200UL );
TickType_t xDelayTime;
EventBits_t uxThisTasksSyncBit;
const EventBits_t uxAllSyncBits = ( mainFIRST_TASK_BIT |
mainSECOND_TASK_BIT |
mainTHIRD_TASK_BIT );
/* Three instances of this task are created - each task uses a different event
bit in the synchronization. The event bit to use is passed into each task
instance using the task parameter. Store it in the uxThisTasksSyncBit
variable. */
uxThisTasksSyncBit = ( EventBits_t ) pvParameters;
for( ;; )
{
/* Simulate this task taking some time to perform an action by delaying for a
pseudo random time. This prevents all three instances of this task reaching
the synchronization point at the same time, and so allows the example’s
behavior to be observed more easily. */
xDelayTime = ( rand() % xMaxDelay ) + xMinDelay;
vTaskDelay( xDelayTime );
/* Print out a message to show this task has reached its synchronization
point. pcTaskGetTaskName() is an API function that returns the name assigned
to the task when the task was created. */
vPrintTwoStrings( pcTaskGetTaskName( NULL ), "reached sync point" );
/* Wait for all the tasks to have reached their respective synchronization
points. */
xEventGroupSync( /* The event group used to synchronize. */
xEventGroup,
/* The bit set by this task to indicate it has reached the
synchronization point. */
uxThisTasksSyncBit,
/* The bits to wait for, one bit for each task taking part
in the synchronization. */
uxAllSyncBits,
/* Wait indefinitely for all three tasks to reach the
synchronization point. */
portMAX_DELAY );
/* Print out a message to show this task has passed its synchronization
point. As an indefinite delay was used the following line will only be
executed after all the tasks reached their respective synchronization
points. */
vPrintTwoStrings( pcTaskGetTaskName( NULL ), "exited sync point" );
}
}main() 创建事件组、创建三个任务,再启动调度器,实现见清单 144。
/* Definitions for the event bits in the event group. */
#define mainFIRST_TASK_BIT ( 1UL << 0UL ) /* Event bit 0, set by the first task. */
#define mainSECOND_TASK_BIT( 1UL << 1UL ) /* Event bit 1, set by the second task. */
#define mainTHIRD_TASK_BIT ( 1UL << 2UL ) /* Event bit 2, set by the third task. */
/* Declare the event group used to synchronize the three tasks. */
EventGroupHandle_t xEventGroup;
int main( void )
{
/* Before an event group can be used it must first be created. */
xEventGroup = xEventGroupCreate();
/* Create three instances of the task. Each task is given a different name,
which is later printed out to give a visual indication of which task is
executing. The event bit to use when the task reaches its synchronization point
is passed into the task using the task parameter. */
xTaskCreate( vSyncingTask, "Task 1", 1000, mainFIRST_TASK_BIT, 1, NULL );
xTaskCreate( vSyncingTask, "Task 2", 1000, mainSECOND_TASK_BIT, 1, NULL );
xTaskCreate( vSyncingTask, "Task 3", 1000, mainTHIRD_TASK_BIT, 1, NULL );
/* Start the scheduler so the created tasks start executing. */
vTaskStartScheduler();
/* As always, the following line should never be reached. */
for( ;; );
return 0;
}执行示例 23 的输出见图 75。可见尽管每个任务在不同(伪随机)时刻到达同步点,但每个任务都在同一时刻离开同步点——即最后一个任务到达同步点的时刻。
