第 6 章 · 原书 303–327 页 · 11 个函数事件组 API
事件组(event group)本质上是一组“位标志”,每个位可以独立置位、清除和等待。与信号量最大的区别是:一个事件组可以有多个等待者,并且等待条件可以是“任意一位置位”或“全部指定位都置位”。
位数有限制,这点务必先算清楚:
| 配置 | 可用位数 | 说明 |
|---|---|---|
| configUSE_16_BIT_TICKS = 1(16 位节拍) | 8 位(bit0~bit7) | 位数少,谨慎使用 |
| configUSE_16_BIT_TICKS = 0(32 位节拍,默认) | 24 位(bit0~bit23) | 最高的 8 位被内核保留 |
使用事件组的三个要点:
- 多任务共享:同一个事件组可被多个任务同时等待,事件到来时可以唤醒多个等待者(这是任务通知做不到的)。
- 等待条件:xEventGroupWaitBits() 的 xWaitForAllBits 为 pdTRUE 时要求所有指定位都置位;为 pdFALSE 时只要任意一位置位就返回。
- 是否清零:xClearOnExit 为 pdTRUE 时,函数返回前会自动把“导致它返回的那些位”清掉,适合“一次性事件”;为 pdFALSE 时位保持,适合“状态型标志”。
事件组不是计数器:同一个位连续置位多次与置一次等价。如果业务需要计次,请用计数信号量或任务通知。
6.1xEventGroupClearBits()
BaseType_t xEventGroupClearBits( EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToClear );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xEventGroup | in | 事件组句柄。 |
| uxBitsToClear | in | 要清除的位掩码,位为 1 表示清除该位。 |
返回值
清除之前事件组中的位值(EventBits_t)。
说明
清除事件组中指定的位。常用于“处理完事件后把标志清掉”。
注意返回的是清除前的值,因此可以用它来判断“这些位此前是否真的置位了”。
注意
- 不能在中断里调用,中断里请用 xEventGroupClearBitsFromISR()。
- 清除动作是原子的,但“读—操作—清”的组合在多任务下仍需自己保证逻辑正确。
6.2xEventGroupClearBitsFromISR()
BaseType_t xEventGroupClearBitsFromISR( EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToClear );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xEventGroup | in | 事件组句柄。 |
| uxBitsToClear | in | 要清除的位掩码。 |
返回值
pdPASS 表示清除动作已成功排入定时器命令队列;pdFAIL 表示队列满,动作未能排队。
说明
中断里清除事件位的版本。它并不在中断里直接改位,而是把“清位”动作交给定时器服务任务去执行。
注意
- configUSE_TIMERS 必须为 1(虽然函数名里没有 Timer,但它依赖定时器服务任务)。
- 返回值只表示“命令是否入队成功”,不代表位已经立即被清除。
6.3xEventGroupCreate()
EventGroupHandle_t xEventGroupCreate( void );
返回值
创建成功返回事件组句柄;堆内存不足返回 NULL。
说明
动态创建一个事件组,所有位初始为 0。
一个事件组可容纳 8 位或 24 位(取决于 configUSE_16_BIT_TICKS),因此“一个事件组放多少种事件”要提前规划。
注意
- configSUPPORT_DYNAMIC_ALLOCATION 必须为 1。
- 用完必须 vEventGroupDelete() 释放。
典型用法
#define BIT_UART_RX ( 1 << 0 ) #define BIT_KEY_PRESS ( 1 << 1 ) EventGroupHandle_t xEvents = xEventGroupCreate(); /* 等待“串口收到数据”或“按键按下”任意一个 */ xEventGroupWaitBits( xEvents, BIT_UART_RX | BIT_KEY_PRESS, pdTRUE, pdFALSE, portMAX_DELAY );
6.4xEventGroupCreateStatic()
EventGroupHandle_t xEventGroupCreateStatic( StaticEventGroup_t *pxEventGroupBuffer );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| pxEventGroupBuffer | in | 应用提供的 StaticEventGroup_t 结构,用作事件组控制块。 |
返回值
创建成功返回句柄;指针为 NULL 时返回 NULL。
说明
静态创建事件组,控制块由应用提供。
注意
- configSUPPORT_STATIC_ALLOCATION 必须为 1。
6.5vEventGroupDelete()
void vEventGroupDelete( EventGroupHandle_t xEventGroup );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xEventGroup | in | 要删除的事件组句柄。 |
说明
删除事件组并释放内存(静态创建的不释放)。所有正在等待该事件组的任务会被解除阻塞,并把当前位值作为返回值。
注意
- 删除后句柄立即失效。
- 等待者被唤醒后应检查返回值是否为期望的位,以免把“事件组被删”误判为“事件发生”。
6.6xEventGroupGetBits()
EventBits_t xEventGroupGetBits( EventGroupHandle_t xEventGroup );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xEventGroup | in | 要查询的事件组句柄。 |
返回值
事件组当前的位值(EventBits_t)。
说明
查询事件组的当前位值,不清除任何位(相当于“看一眼”)。
它是宏:内部调用 xEventGroupClearBits( xEventGroup, 0 ),即清 0 位,从而安全地读取当前值。
注意
- 不能在中断里使用,中断里请用 xEventGroupGetBitsFromISR()。
6.7xEventGroupGetBitsFromISR()
EventBits_t xEventGroupGetBitsFromISR( EventGroupHandle_t xEventGroup );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xEventGroup | in | 要查询的事件组句柄。 |
返回值
事件组当前的位值。
说明
中断里读取事件组位值的版本。
注意
- 中断里只能读,不能阻塞等待;等待必须在任务里做。
6.8xEventGroupSetBits()
BaseType_t xEventGroupSetBits( EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToSet );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xEventGroup | in | 事件组句柄。 |
| uxBitsToSet | in | 要置位的位掩码,位为 1 表示置位该位(按位或写入)。 |
返回值
置位之后事件组的位值(EventBits_t)。
说明
置位事件组中的若干位。置位后若满足某个等待任务的条件(任意位或全部位),相应任务会被解除阻塞。
一个事件组可以同时唤醒多个等待任务,这是它与任务通知、队列的明显差异。
注意
- 不能在中断里调用,中断里请用 xEventGroupSetBitsFromISR()。
- 返回值是“本次操作完成后”的完整位值,可用于判断是否已满足某些组合条件。
- 不要置位内核保留位(32 位节拍的 bit24~bit31),否则行为未定义。
典型用法
#define BIT_DONE ( 1 << 3 ) /* 任务里:任务完成时置位 */ xEventGroupSetBits( xEvents, BIT_DONE ); /* 另一个任务里:等 BIT_DONE 与 BIT_READY 都置位,取出后清零 */ xEventGroupWaitBits( xEvents, BIT_DONE | BIT_READY, pdTRUE, pdTRUE, portMAX_DELAY );
6.9xEventGroupSetBitsFromISR()
BaseType_t xEventGroupSetBitsFromISR( EventGroupHandle_t xEventGroup,
const EventBits_t uxBitsToSet,
BaseType_t *pxHigherPriorityTaskWoken );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xEventGroup | in | 事件组句柄。 |
| uxBitsToSet | in | 要置位的位掩码。 |
| pxHigherPriorityTaskWoken | out | 初始化为 pdFALSE;若置位动作使更高优先级任务解除阻塞,则被置为 pdTRUE。 |
返回值
pdPASS 表示置位动作已成功排入定时器命令队列;pdFAIL 表示队列满,动作未能排队。
说明
中断里置位事件组的版本。与清位一样,它借助定时器服务任务异步完成实际的置位动作。
注意
- configUSE_TIMERS 必须为 1。
- 返回 pdPASS 只表示“命令入队成功”,位值的变化稍后才发生;不要紧接着在中断里用 xEventGroupGetBitsFromISR() 去读它。
- pxHigherPriorityTaskWoken 需由 portYIELD_FROM_ISR() 处理。
6.10xEventGroupSync()
EventBits_t xEventGroupSync( EventGroupHandle_t xEventGroup,
const EventBits_t uxBitsToSet,
const EventBits_t uxBitsToWaitFor,
TickType_t xTicksToWait );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xEventGroup | in | 事件组句柄。 |
| uxBitsToSet | in | 进入本函数时先置位的位(表示“我到了”)。 |
| uxBitsToWaitFor | in | 需要等待的位集合(表示“要等大家都到齐”)。 |
| xTicksToWait | in | 最长等待节拍数,超时返回。 |
返回值
函数返回时事件组的位值。若等到了全部条件位,说明同步成功;若超时,返回值中会缺少某些位(可用它判断谁没到)。
说明
“到达并等待”二合一的同步原语:先把 uxBitsToSet 置位(我来了),再等待 uxBitsToWaitFor 中指定的位全部置位(等齐所有人),等齐后函数返回并把这些位清 0。
典型场景:多个任务要在某个点上集合,全部到齐后才继续(类似栅栏 barrier)。
注意
- 等待期间超时会返回,返回值里能看出还缺哪些位,便于做超时处理。
- 同步成功返回前会自动清除 uxBitsToWaitFor 中的位,便于下一轮同步复用。
- 只能在任务里调用。
6.11xEventGroupWaitBits()
EventBits_t xEventGroupWaitBits( EventGroupHandle_t xEventGroup,
const EventBits_t uxBitsToWaitFor,
const BaseType_t xClearOnExit,
const BaseType_t xWaitForAllBits,
TickType_t xTicksToWait );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xEventGroup | in | 事件组句柄。 |
| uxBitsToWaitFor | in | 要等待的位集合。 |
| xClearOnExit | in | pdTRUE 时,返回前自动清除“导致返回的位”;pdFALSE 时位保持不清。 |
| xWaitForAllBits | in | pdTRUE 要求 uxBitsToWaitFor 中所有位都置位才算满足;pdFALSE 只要任意一位置位即满足。 |
| xTicksToWait | in | 最长等待节拍数。0 表示立即检查;portMAX_DELAY 表示无限等待。 |
返回值
函数返回时(清除位之前)事件组的位值。可据此判断到底哪些位满足了条件、有没有超时。
说明
等待事件组中的位满足指定条件。这是事件组最核心的 API,把“等谁、等几个、等完清不清”都做成了参数。
条件由 xWaitForAllBits 与 xClearOnExit 组合决定,共四种语义组合,选错会得到完全不同的行为。
注意
- 只有任务能调用(会阻塞)。
- 超时返回时也会给出当前位值,因此必须自己判断“条件是否真的满足”,不能只看有没有返回。
- 多个任务可同时等待同一个事件组,事件到来时可以一起被唤醒。
- xClearOnExit 只清除“本次等待涉及的位”,不清除其它位。
典型用法
EventBits_t uxBits;
/* 等 BIT_A 与 BIT_B 都置位,取到后清掉(一次性的“两步完成”事件) */
uxBits = xEventGroupWaitBits( xEvents,
BIT_A | BIT_B,
pdTRUE, /* 满足后清位 */
pdTRUE, /* 要求全部置位 */
pdMS_TO_TICKS( 1000 ) );
if( ( uxBits & ( BIT_A | BIT_B ) ) == ( BIT_A | BIT_B ) )
{
/* 条件确实满足 */
}
else
{
/* 超时:uxBits 里能看到还缺哪些位 */
}