第 3 章 · 原书 161–211 页 · 24 个函数队列 API
队列是 FreeRTOS 最基础的任务间通信机制:任务与任务之间、任务与中断之间按“值拷贝”的方式传递固定大小的数据块。信号量、互斥量、队列集在实现上都依赖队列,所以先弄懂这一章,后面第 4、6 章会轻松很多。
队列的几个要点,先记住:
- 拷贝而非引用:xQueueSend() 把 pvItemToQueue 指向的数据按 uxItemSize 字节复制进队列;xQueueReceive() 再复制到你的缓冲区。数据项很大时,更常见的做法是传指针(数据放在别处)。
- 长度固定、元素定长:创建时决定队列深度(最多几项)与每项大小(多少字节),运行期不能改。
- 先进先出(FIFO):xQueueSend() 把数据放到队尾,xQueueReceive() 从队头取。xQueueSendToFront() 可以插队,xQueueOverwrite() 则在满时覆盖旧值(专门用于长度为 1 的“邮箱”)。
- 阻塞即等待:发送时队列满、接收时队列空,都可以指定阻塞时间(xTicksToWait),任务进入阻塞态等待,事件到来或超时后返回。
本章 3.22、3.23 两节各自包含三个函数(xQueueSend / xQueueSendToFront / xQueueSendToBack 及其 FromISR 版本),因为它们共享同一套参数与语义,只有入队位置不同。为便于检索,速查表中把它们分开列出,正文仍合并在一节说明。
3.1vQueueAddToRegistry()
void vQueueAddToRegistry( QueueHandle_t xQueue, char *pcQueueName );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xQueue | in | 要加入注册表的队列句柄。信号量句柄同样可用(信号量本质就是队列)。 |
| pcQueueName | in | 队列或信号量的描述名。FreeRTOS 内部完全不用它,纯属调试辅助。 |
说明
给队列挂一个人类可读的名字,并把它登记到“队列注册表”中。注册表的用途有两个:
- 让内核感知型调试器(kernel aware debugger)在界面上用名字标识队列,而不是显示一串句柄;
- 让调试器能够定位队列与信号量的数据结构,从而显示队列内容、等待任务等信息。
注意
- configQUEUE_REGISTRY_SIZE 决定注册表能容纳多少个队列/信号量;为 0 时该功能被编译掉(函数为空实现)。
- 只是登记名字,不改变队列的任何行为。
3.2xQueueAddToSet()
BaseType_t xQueueAddToSet( QueueSetMemberHandle_t xQueueOrSemaphore,
QueueSetHandle_t xQueueSet );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xQueueOrSemaphore | in | 要加入队列集的队列或信号量句柄(需强制转换为 QueueSetMemberHandle_t)。 |
| xQueueSet | in | 目标队列集句柄,由 xQueueCreateSet() 创建。 |
返回值
pdPASS 表示加入成功;pdFAIL 表示该对象已经是另一个队列集的成员,无法再加入。
说明
把一个队列或信号量加入此前由 xQueueCreateSet() 创建的队列集。
队列集的用途:让一个任务同时“等待多个队列/信号量”中的任意一个就绪。对应的读取函数是 xQueueSelectFromSet()。
注意
- configUSE_QUEUE_SETS 必须置 1。
- 纪律:对队列集成员执行接收/读取之前,必须先通过 xQueueSelectFromSet() 拿到该成员的句柄,否则会破坏队列集的计数逻辑。
- 队列集内部为每个成员维护一个计数,因此会额外占用 RAM。
3.3xQueueCreate()
QueueHandle_t xQueueCreate( UBaseType_t uxQueueLength,
UBaseType_t uxItemSize );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| uxQueueLength | in | 队列深度:最多能存放多少个数据项。 |
| uxItemSize | in | 每个数据项的字节数。发送/接收时按这个长度整块复制。 |
返回值
创建成功返回队列句柄;堆内存不足返回 NULL。
说明
动态创建一个队列,所需内存由 FreeRTOS 堆自动分配(队列控制块 + 存储区)。
创建出来的队列既可当作普通队列收发数据,也是信号量、互斥量、队列集的底层对象。
注意
- configSUPPORT_DYNAMIC_ALLOCATION 必须为 1。
- 所需字节数约为 uxQueueLength × uxItemSize 再加上队列控制块开销,可用 xPortGetFreeHeapSize() 观察剩余堆。
- 队列句柄用完必须用 vQueueDelete() 释放,否则内存泄漏。
典型用法
QueueHandle_t xQueue = xQueueCreate( 10, sizeof( uint32_t ) );
if( xQueue == NULL ) { /* 内存不足,处理错误 */ }
3.4xQueueCreateSet()
QueueSetHandle_t xQueueCreateSet( const UBaseType_t uxEventQueueLength );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| uxEventQueueLength | in | 队列集能记录的事件总数。它应等于所有成员队列长度与信号量最大计数值之和,否则会丢事件。 |
返回值
创建成功返回队列集句柄;内存不足返回 NULL。
说明
创建一个队列集。队列集本身也是一个队列(内部队列),用来汇集其成员“有数据/可取”的事件。
典型场景:一个任务要同时处理串口数据、按键队列、两个信号量,用队列集就不必为每个对象开一个任务。
注意
- configUSE_QUEUE_SETS 必须置 1。
- uxEventQueueLength 要给足:例如成员是两个长度 5 的队列,则应取 10;若成员含长度为 1 的二进制信号量,再 +1。
- 队列集的成员在读取前必须先 select,见 3.2 的纪律说明。
3.5xQueueCreateStatic()
QueueHandle_t xQueueCreateStatic( UBaseType_t uxQueueLength,
UBaseType_t uxItemSize,
uint8_t *pucQueueStorageBuffer,
StaticQueue_t *pxQueueBuffer );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| uxQueueLength | in | 队列深度。 |
| uxItemSize | in | 每项字节数。 |
| pucQueueStorageBuffer | in | 应用提供的存储区,长度至少为 uxQueueLength × uxItemSize 字节。 |
| pxQueueBuffer | in | 应用提供的 StaticQueue_t 结构,用作队列控制块。 |
返回值
创建成功返回队列句柄;任一缓冲区指针为 NULL 时返回 NULL。
说明
用静态分配方式创建队列:存储区与队列控制块都由应用提供,内核不再动态分配内存。
注意
- configSUPPORT_STATIC_ALLOCATION 必须为 1。
- 存储区大小必须自己算够:uxQueueLength × uxItemSize,通常声明为 static uint8_t ucQueueStorage[ 10 * sizeof( uint32_t ) ];
典型用法
static uint8_t ucStorage[ 10 * sizeof( uint32_t ) ];
static StaticQueue_t xQueueStruct;
QueueHandle_t xQueue = xQueueCreateStatic( 10, sizeof( uint32_t ),
ucStorage, &xQueueStruct );
3.6vQueueDelete()
void vQueueDelete( QueueHandle_t xQueue );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xQueue | in | 要删除的队列句柄。信号量句柄也可传入。 |
说明
删除队列并释放其占用的内存(静态创建的队列不会被释放内存)。队列中尚未取走的数据随之一并丢弃。
注意
- 删除时若有任务正阻塞在该队列上等待,这些任务会被解除阻塞并返回失败。
- 删除后句柄立即失效,不可再用。
3.7pcQueueGetName()
char *pcQueueGetName( QueueHandle_t xQueue );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xQueue | in | 要查询的队列句柄。 |
返回值
队列在注册表中的名字;队列未注册则返回 NULL。
说明
查回队列的名字。名字是先前用 vQueueAddToRegistry() 登记的,纯属调试辅助。
注意
- configQUEUE_REGISTRY_SIZE 必须大于 0。
3.8xQueueIsQueueEmptyFromISR()
BaseType_t xQueueIsQueueEmptyFromISR( const QueueHandle_t xQueue );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xQueue | in | 要查询的队列句柄。 |
返回值
队列为空返回 pdTRUE,否则返回 pdFALSE。
说明
在中断里判断队列是否为空。任务里应改用 uxQueueMessagesWaiting()(返回剩余项数,更实用)。
注意
- 判断与后续操作之间不是原子的:中断里判断为空,不代表下一句操作时还为空。
3.9xQueueIsQueueFullFromISR()
BaseType_t xQueueIsQueueFullFromISR( const QueueHandle_t xQueue );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xQueue | in | 要查询的队列句柄。 |
返回值
队列已满返回 pdTRUE,否则返回 pdFALSE。
说明
在中断里判断队列是否已满。常见于中断里发送数据前的快速检查:满就丢帧,避免堵塞中断。
注意
- 任务里应改用 uxQueueSpacesAvailable()(返回剩余空间数)。
3.10uxQueueMessagesWaiting()
UBaseType_t uxQueueMessagesWaiting( const QueueHandle_t xQueue );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xQueue | in | 要查询的队列句柄。 |
返回值
当前队列中存放的数据项个数。
说明
查询队列中现有多少个数据项。常用于调试、状态上报,或根据水位做流控。
注意
- 返回值是瞬时值,函数返回后可能立即变化。
- 信号量句柄也能传进来,此时返回的是“当前计数”。
3.11uxQueueMessagesWaitingFromISR()
UBaseType_t uxQueueMessagesWaitingFromISR( const QueueHandle_t xQueue );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xQueue | in | 要查询的队列句柄。 |
返回值
队列中当前的数据项个数。
说明
uxQueueMessagesWaiting() 的中断安全版本,可在中断服务程序中调用。
注意
- 任务里请用 uxQueueMessagesWaiting()。
3.12xQueueOverwrite()
BaseType_t xQueueOverwrite( QueueHandle_t xQueue, const void *pvItemToQueue );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xQueue | in | 目标队列句柄。 |
| pvItemToQueue | in | 指向要写入的数据项。函数按队列的元素大小复制相应字节数。 |
返回值
恒返回 pdPASS(因为总能写入)。
说明
xQueueSendToBack() 的变体:即使队列已满也照写,直接覆盖原有数据。它专为长度为 1 的队列(“邮箱”)设计——队列非空即满,写入永远成功,读取永远拿到最新值。
典型用途:把某个传感器的最新读数、某个状态变量的最新值传给任务,旧值被覆盖正是期望行为。
注意
- 不要用它写长度大于 1 的队列,否则会破坏队列语义。
- 中断里请用 xQueueOverwriteFromISR()。
- 没有阻塞概念:它总是立即写入。
典型用法
/* 创建一个长度为 1 的“邮箱” */ QueueHandle_t xMailbox = xQueueCreate( 1, sizeof( uint32_t ) ); uint32_t ulLatest = 1234; xQueueOverwrite( xMailbox, &ulLatest );
3.13xQueueOverwriteFromISR()
BaseType_t xQueueOverwriteFromISR( QueueHandle_t xQueue,
const void *pvItemToQueue,
BaseType_t *pxHigherPriorityTaskWoken );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xQueue | in | 目标队列句柄。 |
| pvItemToQueue | in | 要写入的数据项指针。 |
| pxHigherPriorityTaskWoken | out | 初始化为 pdFALSE;若写入解除了一个更高优先级任务的阻塞,则被置为 pdTRUE。 |
返回值
恒返回 pdPASS。
说明
xQueueOverwrite() 的中断安全版本,用于在中断里更新长度为 1 的“邮箱”。
注意
- 同样只适用于长度为 1 的队列。
- pxHigherPriorityTaskWoken 需在中断返回前由 portYIELD_FROM_ISR() 处理。
3.14xQueuePeek()
BaseType_t xQueuePeek( QueueHandle_t xQueue,
void *pvBuffer,
TickType_t xTicksToWait );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xQueue | in | 要读取的队列句柄。 |
| pvBuffer | out | 接收数据的内存,长度至少为队列的元素大小。 |
| xTicksToWait | in | 队列为空时,任务在阻塞态等待数据的最长节拍数。0 表示不等待;portMAX_DELAY 表示无限等待(需 INCLUDE_vTaskSuspend 为 1)。 |
返回值
pdPASS 表示成功读到数据;errQUEUE_EMPTY 表示指定的阻塞时间内队列一直为空。
说明
从队列读取一项数据,但不从队列中移除。下一次 xQueueReceive() 或 xQueuePeek() 还会读到同一项数据。
典型用途:先看一眼队头是什么,再决定要不要处理它。
注意
- “读而不删”意味着多个任务 peek 会拿到同一项,别把它当成消费。
3.15xQueuePeekFromISR()
BaseType_t xQueuePeekFromISR( QueueHandle_t xQueue, void *pvBuffer );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xQueue | in | 要读取的队列句柄。 |
| pvBuffer | out | 接收数据的内存,长度至少为队列元素大小。 |
返回值
pdPASS 表示读取成功;errQUEUE_EMPTY 表示队列为空。
说明
xQueuePeek() 的中断安全版本:读队头但不移除。中断里不能阻塞,因此没有超时参数。
注意
- 只能在中断里用;任务里请用 xQueuePeek()。
3.16xQueueReceive()
BaseType_t xQueueReceive( QueueHandle_t xQueue,
void *pvBuffer,
TickType_t xTicksToWait );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xQueue | in | 要读取的队列句柄。 |
| pvBuffer | out | 接收数据的内存,长度至少为队列元素大小。 |
| xTicksToWait | in | 队列为空时最长阻塞节拍数。0 表示立即返回;portMAX_DELAY 表示无限等待。 |
返回值
pdPASS 表示读到数据;errQUEUE_EMPTY 表示等待超时、队列仍为空。
说明
从队列读取(取走)一项数据,取走后该项从队列中删除,空间被释放,可能唤醒正在等待发送的任务。
这是队列最常用的消费接口,通常写在任务主体的死循环里。
注意
- 数据是被复制到 pvBuffer 的,随后队列中的副本被丢弃。
- 若 xTicksToWait 为 portMAX_DELAY 且 INCLUDE_vTaskSuspend 为 1,任务会无限等待,不会超时返回。
- 中断里请用 xQueueReceiveFromISR()。
典型用法
void vConsumer( void *pvParameters )
{
uint32_t ulValue;
for( ;; )
{
if( xQueueReceive( xQueue, &ulValue, portMAX_DELAY ) == pdPASS )
{
/* 处理 ulValue */
}
}
}
3.17xQueueReceiveFromISR()
BaseType_t xQueueReceiveFromISR( QueueHandle_t xQueue,
void *pvBuffer,
BaseType_t *pxHigherPriorityTaskWoken );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xQueue | in | 要读取的队列句柄。 |
| pvBuffer | out | 接收数据的内存,长度至少为队列元素大小。 |
| pxHigherPriorityTaskWoken | out | 若本次读取腾出了空间、解除了一个等待发送任务的阻塞,且该任务优先级更高,则被置为 pdTRUE。 |
返回值
pdPASS 表示读到数据;pdFAIL 表示队列为空。
说明
xQueueReceive() 的中断安全版本。中断里不能阻塞,所以没有超时参数。
注意
- 返回值是 pdFAIL(而不是任务版的 errQUEUE_EMPTY),写代码时按 pdFAIL 判断即可。
- 读取可能唤醒等待发送的高优先级任务,务必用 portYIELD_FROM_ISR() 处理 pxHigherPriorityTaskWoken。
3.18xQueueRemoveFromSet()
BaseType_t xQueueRemoveFromSet( QueueSetMemberHandle_t xQueueOrSemaphore,
QueueSetHandle_t xQueueSet );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xQueueOrSemaphore | in | 要从队列集移除的队列或信号量句柄(强制转换为 QueueSetMemberHandle_t)。 |
| xQueueSet | in | 所属的队列集句柄。 |
返回值
pdPASS 表示移除成功;pdFAIL 表示该对象不是该队列集的成员(或该队列/信号量上仍有等待任务)。
说明
把一个队列或信号量从队列集中移除。移除后,该对象的就绪事件不再计入队列集。
注意
- configUSE_QUEUE_SETS 必须为 1。
- 移除前最好确认该成员当前不在队列集内部的事件队列中,否则计数可能残留。
3.19xQueueReset()
BaseType_t xQueueReset( QueueHandle_t xQueue );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xQueue | in | 要复位的队列句柄。 |
返回值
自 FreeRTOS V7.2.0 起恒返回 pdPASS(早期版本会返回 pdFAIL)。
说明
把队列恢复到创建时的空状态,队列中已有的数据全部丢弃。
注意
- 复位不会唤醒等待接收的任务(队列变空,它们继续等)。
- 典型用途:通信链路出错后清空积压的旧数据,避免处理过期信息。
3.20xQueueSelectFromSet()
QueueSetMemberHandle_t xQueueSelectFromSet( QueueSetHandle_t xQueueSet,
const TickType_t xTicksToWait );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xQueueSet | in | 要等待的队列集句柄。 |
| xTicksToWait | in | 最长阻塞节拍数,等队列集中任一成员就绪。 |
返回值
返回就绪成员的句柄(队列或信号量,类型为 QueueSetMemberHandle_t);超时返回 NULL。
说明
从队列集的成员中挑出一个“有数据可取(队列)”或“可取到(信号量)”的对象并返回其句柄。
它的意义在于:让一个任务同时阻塞等待多个队列/信号量,谁先来处理谁,不必为每个对象单独开任务。
注意
- configUSE_QUEUE_SETS 必须为 1。
- 拿到句柄之后才允许对该成员执行 xQueueReceive() / xSemaphoreTake();顺序反了会破坏内部计数。
- 若队列集包含互斥量,阻塞在队列集上不会触发优先级继承,可能引起优先级反转,需谨慎。
- 队列集并非唯一方案,任务通知、事件组在很多场景更轻量。
典型用法
QueueSetMemberHandle_t xActivated;
UBaseType_t ulValue;
/* 等串口队列或按键队列任意一个有数据 */
xActivated = xQueueSelectFromSet( xQueueSet, portMAX_DELAY );
if( xActivated == xSerialQueue ) { xQueueReceive( xSerialQueue, &ulValue, 0 ); }
else if( xActivated == xKeyQueue ) { xQueueReceive( xKeyQueue, &ulValue, 0 ); }
3.21xQueueSelectFromSetFromISR()
QueueSetMemberHandle_t xQueueSelectFromSetFromISR( QueueSetHandle_t xQueueSet );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xQueueSet | in | 要查询的队列集句柄。中断里不能阻塞,因此没有超时参数。 |
返回值
返回就绪成员句柄;没有成员就绪时返回 NULL。
说明
xQueueSelectFromSet() 的中断安全版本:查询一次队列集,不阻塞。
注意
- configUSE_QUEUE_SETS 必须为 1。
- 中断里用队列集判断“哪个外设的队列有数据”,可以省去多个中断服务程序里的重复逻辑。
3.22xQueueSend() / xQueueSendToFront() / xQueueSendToBack()
BaseType_t xQueueSend( QueueHandle_t xQueue, const void *pvItemToQueue,
TickType_t xTicksToWait );
BaseType_t xQueueSendToBack( QueueHandle_t xQueue, const void *pvItemToQueue,
TickType_t xTicksToWait );
BaseType_t xQueueSendToFront( QueueHandle_t xQueue, const void *pvItemToQueue,
TickType_t xTicksToWait );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xQueue | in | 目标队列句柄。 |
| pvItemToQueue | in | 指向要入队的数据项。函数按创建时确定的元素大小,从该地址复制相应字节数到队列存储区。 |
| xTicksToWait | in | 队列已满时,任务在阻塞态等待空位的最长节拍数。0 表示不等待、立即返回;portMAX_DELAY 表示无限等待(需 INCLUDE_vTaskSuspend 为 1)。 |
返回值
pdPASS 表示入队成功;errQUEUE_FULL 表示在指定时间内队列一直是满的。
说明
把数据项送入队列。三个函数只有一个区别:入队位置。
- xQueueSendToBack() 放到队尾(正常 FIFO 顺序),最常用;
- xQueueSendToFront() 插到队头,下一次 xQueueReceive() 就会最先取到它——用于“插队”的紧急消息;
- xQueueSend() 与 xQueueSendToBack() 完全等价,只是名字更老、更短。
注意
- 数据是复制进队列的:函数返回后 pvItemToQueue 指向的内容你可以随意改,队列里是独立的一份。
- 队满时的阻塞可能被其它事件打断而提前返回。
- 中断里请用 3.23 的 FromISR 版本。
- 若元素是指针,注意被指向的内存生命周期要覆盖到接收方处理完为止(不要传栈上临时变量的地址)。
典型用法
uint32_t ulValue = 42; /* 放到队尾(FIFO) */ xQueueSend( xQueue, &ulValue, pdMS_TO_TICKS( 10 ) ); /* 紧急消息插队到队头 */ xQueueSendToFront( xQueue, &ulValue, 0 );
3.23xQueueSendFromISR() / xQueueSendToBackFromISR() / xQueueSendToFrontFromISR()
BaseType_t xQueueSendFromISR( QueueHandle_t xQueue, const void *pvItemToQueue,
BaseType_t *pxHigherPriorityTaskWoken );
BaseType_t xQueueSendToBackFromISR( QueueHandle_t xQueue, const void *pvItemToQueue,
BaseType_t *pxHigherPriorityTaskWoken );
BaseType_t xQueueSendToFrontFromISR( QueueHandle_t xQueue, const void *pvItemToQueue,
BaseType_t *pxHigherPriorityTaskWoken );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xQueue | in | 目标队列句柄。 |
| pvItemToQueue | in | 要入队的数据项指针。 |
| pxHigherPriorityTaskWoken | out | 初始化为 pdFALSE。若入队唤醒了一个正在等待该队列的任务,且其优先级高于被中断的任务,则被置为 pdTRUE。 |
返回值
pdPASS 表示入队成功;errQUEUE_FULL 表示队列已满(中断里无法等待,只能直接失败)。
说明
三个 Send 的中断安全版本,语义与任务版完全一致,只是没有 xTicksToWait 参数(中断中不允许阻塞)。
注意
- 队列满时中断里只能丢掉数据。要求“不丢”就要把队列深度做够,或用流缓冲区/消息缓冲区。
- 必须处理 pxHigherPriorityTaskWoken:中断返回前调用 portYIELD_FROM_ISR( pxHigherPriorityTaskWoken )。
典型用法
void vUartISR( void )
{
BaseType_t xWoken = pdFALSE;
uint8_t ucByte = UART->DR;
xQueueSendFromISR( xRxQueue, &ucByte, &xWoken );
portYIELD_FROM_ISR( xWoken );
}
3.24uxQueueSpacesAvailable()
UBaseType_t uxQueueSpacesAvailable( const QueueHandle_t xQueue );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xQueue | in | 要查询的队列句柄。 |
返回值
队列中还剩多少个空位(还能再放多少项才会满)。
说明
查询队列的剩余空间,即“还能发多少项”。与 uxQueueMessagesWaiting() 相对:后者返回已有项数。
常见用途:发送前检查,避免因队满而丢数据;或者做流控。
注意
- 返回值是瞬时值,随后可能变化。
- 空位 = 队列深度 - 已有项数。