FreeRTOS 中文参考手册 /6 事件组 API

第 6 章 · 原书 303–327 页 · 11 个函数事件组 API

Chapter 6 · Event Groups API

事件组(event group)本质上是一组“位标志”,每个位可以独立置位、清除和等待。与信号量最大的区别是:一个事件组可以有多个等待者,并且等待条件可以是“任意一位置位”或“全部指定位都置位”。

位数有限制,这点务必先算清楚:

配置可用位数说明
configUSE_16_BIT_TICKS = 1(16 位节拍)8 位(bit0~bit7)位数少,谨慎使用
configUSE_16_BIT_TICKS = 0(32 位节拍,默认)24 位(bit0~bit23)最高的 8 位被内核保留

使用事件组的三个要点:

xEventGroupSetBits() / xEventGroupClearBits() 都不能在中断里调用。中断里置位要用 xEventGroupSetBitsFromISR();它在内部把“置位动作”转交给定时器服务任务完成,因此 configUSE_TIMERS 必须为 1,且返回值只代表“动作是否已成功排入队列”。

事件组不是计数器:同一个位连续置位多次与置一次等价。如果业务需要计次,请用计数信号量或任务通知。

6.1xEventGroupClearBits()

事件组 event_groups.h
BaseType_t xEventGroupClearBits( EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToClear );

参数

参数方向说明
xEventGroupin事件组句柄。
uxBitsToClearin要清除的位掩码,位为 1 表示清除该位。

返回值

清除之前事件组中的位值(EventBits_t)。

说明

清除事件组中指定的位。常用于“处理完事件后把标志清掉”。

注意返回的是清除前的值,因此可以用它来判断“这些位此前是否真的置位了”。

注意

6.2xEventGroupClearBitsFromISR()

事件组 · 中断 event_groups.h
BaseType_t xEventGroupClearBitsFromISR( EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToClear );

参数

参数方向说明
xEventGroupin事件组句柄。
uxBitsToClearin要清除的位掩码。

返回值

pdPASS 表示清除动作已成功排入定时器命令队列;pdFAIL 表示队列满,动作未能排队。

说明

中断里清除事件位的版本。它并不在中断里直接改位,而是把“清位”动作交给定时器服务任务去执行。

注意

6.3xEventGroupCreate()

事件组 event_groups.h
EventGroupHandle_t xEventGroupCreate( void );

返回值

创建成功返回事件组句柄;堆内存不足返回 NULL。

说明

动态创建一个事件组,所有位初始为 0。

一个事件组可容纳 8 位或 24 位(取决于 configUSE_16_BIT_TICKS),因此“一个事件组放多少种事件”要提前规划。

注意

典型用法

#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()

事件组 event_groups.h
EventGroupHandle_t xEventGroupCreateStatic( StaticEventGroup_t *pxEventGroupBuffer );

参数

参数方向说明
pxEventGroupBufferin应用提供的 StaticEventGroup_t 结构,用作事件组控制块。

返回值

创建成功返回句柄;指针为 NULL 时返回 NULL。

说明

静态创建事件组,控制块由应用提供。

注意

6.5vEventGroupDelete()

事件组 event_groups.h
void vEventGroupDelete( EventGroupHandle_t xEventGroup );

参数

参数方向说明
xEventGroupin要删除的事件组句柄。

说明

删除事件组并释放内存(静态创建的不释放)。所有正在等待该事件组的任务会被解除阻塞,并把当前位值作为返回值。

注意

6.6xEventGroupGetBits()

事件组 event_groups.h
EventBits_t xEventGroupGetBits( EventGroupHandle_t xEventGroup );

参数

参数方向说明
xEventGroupin要查询的事件组句柄。

返回值

事件组当前的位值(EventBits_t)。

说明

查询事件组的当前位值,不清除任何位(相当于“看一眼”)。

它是宏:内部调用 xEventGroupClearBits( xEventGroup, 0 ),即清 0 位,从而安全地读取当前值。

注意

6.7xEventGroupGetBitsFromISR()

事件组 · 中断 event_groups.h
EventBits_t xEventGroupGetBitsFromISR( EventGroupHandle_t xEventGroup );

参数

参数方向说明
xEventGroupin要查询的事件组句柄。

返回值

事件组当前的位值。

说明

中断里读取事件组位值的版本。

注意

6.8xEventGroupSetBits()

事件组 event_groups.h
BaseType_t xEventGroupSetBits( EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToSet );

参数

参数方向说明
xEventGroupin事件组句柄。
uxBitsToSetin要置位的位掩码,位为 1 表示置位该位(按位或写入)。

返回值

置位之后事件组的位值(EventBits_t)。

说明

置位事件组中的若干位。置位后若满足某个等待任务的条件(任意位或全部位),相应任务会被解除阻塞。

一个事件组可以同时唤醒多个等待任务,这是它与任务通知、队列的明显差异。

注意

典型用法

#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()

事件组 · 中断 event_groups.h
BaseType_t xEventGroupSetBitsFromISR( EventGroupHandle_t xEventGroup,
                                         const EventBits_t uxBitsToSet,
                                         BaseType_t *pxHigherPriorityTaskWoken );

参数

参数方向说明
xEventGroupin事件组句柄。
uxBitsToSetin要置位的位掩码。
pxHigherPriorityTaskWokenout初始化为 pdFALSE;若置位动作使更高优先级任务解除阻塞,则被置为 pdTRUE。

返回值

pdPASS 表示置位动作已成功排入定时器命令队列;pdFAIL 表示队列满,动作未能排队。

说明

中断里置位事件组的版本。与清位一样,它借助定时器服务任务异步完成实际的置位动作。

注意

6.10xEventGroupSync()

事件组 · 同步 event_groups.h
EventBits_t xEventGroupSync( EventGroupHandle_t xEventGroup,
                              const EventBits_t uxBitsToSet,
                              const EventBits_t uxBitsToWaitFor,
                              TickType_t xTicksToWait );

参数

参数方向说明
xEventGroupin事件组句柄。
uxBitsToSetin进入本函数时先置位的位(表示“我到了”)。
uxBitsToWaitForin需要等待的位集合(表示“要等大家都到齐”)。
xTicksToWaitin最长等待节拍数,超时返回。

返回值

函数返回时事件组的位值。若等到了全部条件位,说明同步成功;若超时,返回值中会缺少某些位(可用它判断谁没到)。

说明

“到达并等待”二合一的同步原语:先把 uxBitsToSet 置位(我来了),再等待 uxBitsToWaitFor 中指定的位全部置位(等齐所有人),等齐后函数返回并把这些位清 0。

典型场景:多个任务要在某个点上集合,全部到齐后才继续(类似栅栏 barrier)。

注意

6.11xEventGroupWaitBits()

事件组 · 等待 event_groups.h
EventBits_t xEventGroupWaitBits( EventGroupHandle_t xEventGroup,
                                   const EventBits_t uxBitsToWaitFor,
                                   const BaseType_t xClearOnExit,
                                   const BaseType_t xWaitForAllBits,
                                   TickType_t xTicksToWait );

参数

参数方向说明
xEventGroupin事件组句柄。
uxBitsToWaitForin要等待的位集合。
xClearOnExitinpdTRUE 时,返回前自动清除“导致返回的位”;pdFALSE 时位保持不清。
xWaitForAllBitsinpdTRUE 要求 uxBitsToWaitFor 中所有位都置位才算满足;pdFALSE 只要任意一位置位即满足。
xTicksToWaitin最长等待节拍数。0 表示立即检查;portMAX_DELAY 表示无限等待。

返回值

函数返回时(清除位之前)事件组的位值。可据此判断到底哪些位满足了条件、有没有超时。

说明

等待事件组中的位满足指定条件。这是事件组最核心的 API,把“等谁、等几个、等完清不清”都做成了参数。

条件由 xWaitForAllBits 与 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 里能看到还缺哪些位 */
}