FreeRTOS 中文参考手册 /3 队列 API

第 3 章 · 原书 161–211 页 · 24 个函数队列 API

Chapter 3 · Queue API

队列是 FreeRTOS 最基础的任务间通信机制:任务与任务之间、任务与中断之间按“值拷贝”的方式传递固定大小的数据块。信号量、互斥量、队列集在实现上都依赖队列,所以先弄懂这一章,后面第 4、6 章会轻松很多。

队列的几个要点,先记住:

队列操作是“复制 + 调整索引 + 唤醒等待者”,全部在内核临界区中完成,因此对单个队列的 Send/Receive 天然是原子操作,不需要你在外面再包一层临界区。

本章 3.22、3.23 两节各自包含三个函数(xQueueSend / xQueueSendToFront / xQueueSendToBack 及其 FromISR 版本),因为它们共享同一套参数与语义,只有入队位置不同。为便于检索,速查表中把它们分开列出,正文仍合并在一节说明。

3.1vQueueAddToRegistry()

队列 · 调试 queue.h
void vQueueAddToRegistry( QueueHandle_t xQueue, char *pcQueueName );

参数

参数方向说明
xQueuein要加入注册表的队列句柄。信号量句柄同样可用(信号量本质就是队列)。
pcQueueNamein队列或信号量的描述名。FreeRTOS 内部完全不用它,纯属调试辅助。

说明

给队列挂一个人类可读的名字,并把它登记到“队列注册表”中。注册表的用途有两个:

注意

3.2xQueueAddToSet()

队列集 queue.h
BaseType_t xQueueAddToSet( QueueSetMemberHandle_t xQueueOrSemaphore,
                            QueueSetHandle_t xQueueSet );

参数

参数方向说明
xQueueOrSemaphorein要加入队列集的队列或信号量句柄(需强制转换为 QueueSetMemberHandle_t)。
xQueueSetin目标队列集句柄,由 xQueueCreateSet() 创建。

返回值

pdPASS 表示加入成功;pdFAIL 表示该对象已经是另一个队列集的成员,无法再加入。

说明

把一个队列或信号量加入此前由 xQueueCreateSet() 创建的队列集。

队列集的用途:让一个任务同时“等待多个队列/信号量”中的任意一个就绪。对应的读取函数是 xQueueSelectFromSet()。

注意

3.3xQueueCreate()

队列 queue.h
QueueHandle_t xQueueCreate( UBaseType_t uxQueueLength,
                            UBaseType_t uxItemSize );

参数

参数方向说明
uxQueueLengthin队列深度:最多能存放多少个数据项。
uxItemSizein每个数据项的字节数。发送/接收时按这个长度整块复制。

返回值

创建成功返回队列句柄;堆内存不足返回 NULL。

说明

动态创建一个队列,所需内存由 FreeRTOS 堆自动分配(队列控制块 + 存储区)。

创建出来的队列既可当作普通队列收发数据,也是信号量、互斥量、队列集的底层对象。

注意

典型用法

QueueHandle_t xQueue = xQueueCreate( 10, sizeof( uint32_t ) );
if( xQueue == NULL ) { /* 内存不足,处理错误 */ }

3.4xQueueCreateSet()

队列集 queue.h
QueueSetHandle_t xQueueCreateSet( const UBaseType_t uxEventQueueLength );

参数

参数方向说明
uxEventQueueLengthin队列集能记录的事件总数。它应等于所有成员队列长度与信号量最大计数值之和,否则会丢事件。

返回值

创建成功返回队列集句柄;内存不足返回 NULL。

说明

创建一个队列集。队列集本身也是一个队列(内部队列),用来汇集其成员“有数据/可取”的事件。

典型场景:一个任务要同时处理串口数据、按键队列、两个信号量,用队列集就不必为每个对象开一个任务。

注意

3.5xQueueCreateStatic()

队列 queue.h
QueueHandle_t xQueueCreateStatic( UBaseType_t uxQueueLength,
                                  UBaseType_t uxItemSize,
                                  uint8_t *pucQueueStorageBuffer,
                                  StaticQueue_t *pxQueueBuffer );

参数

参数方向说明
uxQueueLengthin队列深度。
uxItemSizein每项字节数。
pucQueueStorageBufferin应用提供的存储区,长度至少为 uxQueueLength × uxItemSize 字节。
pxQueueBufferin应用提供的 StaticQueue_t 结构,用作队列控制块。

返回值

创建成功返回队列句柄;任一缓冲区指针为 NULL 时返回 NULL。

说明

用静态分配方式创建队列:存储区与队列控制块都由应用提供,内核不再动态分配内存。

注意

典型用法

static uint8_t ucStorage[ 10 * sizeof( uint32_t ) ];
static StaticQueue_t xQueueStruct;

QueueHandle_t xQueue = xQueueCreateStatic( 10, sizeof( uint32_t ),
                                           ucStorage, &xQueueStruct );

3.6vQueueDelete()

队列 queue.h
void vQueueDelete( QueueHandle_t xQueue );

参数

参数方向说明
xQueuein要删除的队列句柄。信号量句柄也可传入。

说明

删除队列并释放其占用的内存(静态创建的队列不会被释放内存)。队列中尚未取走的数据随之一并丢弃。

注意

3.7pcQueueGetName()

队列 · 调试 queue.h
char *pcQueueGetName( QueueHandle_t xQueue );

参数

参数方向说明
xQueuein要查询的队列句柄。

返回值

队列在注册表中的名字;队列未注册则返回 NULL。

说明

查回队列的名字。名字是先前用 vQueueAddToRegistry() 登记的,纯属调试辅助。

注意

3.8xQueueIsQueueEmptyFromISR()

队列 · 中断 queue.h
BaseType_t xQueueIsQueueEmptyFromISR( const QueueHandle_t xQueue );

参数

参数方向说明
xQueuein要查询的队列句柄。

返回值

队列为空返回 pdTRUE,否则返回 pdFALSE。

说明

在中断里判断队列是否为空。任务里应改用 uxQueueMessagesWaiting()(返回剩余项数,更实用)。

注意

3.9xQueueIsQueueFullFromISR()

队列 · 中断 queue.h
BaseType_t xQueueIsQueueFullFromISR( const QueueHandle_t xQueue );

参数

参数方向说明
xQueuein要查询的队列句柄。

返回值

队列已满返回 pdTRUE,否则返回 pdFALSE。

说明

在中断里判断队列是否已满。常见于中断里发送数据前的快速检查:满就丢帧,避免堵塞中断。

注意

3.10uxQueueMessagesWaiting()

队列 queue.h
UBaseType_t uxQueueMessagesWaiting( const QueueHandle_t xQueue );

参数

参数方向说明
xQueuein要查询的队列句柄。

返回值

当前队列中存放的数据项个数。

说明

查询队列中现有多少个数据项。常用于调试、状态上报,或根据水位做流控。

注意

3.11uxQueueMessagesWaitingFromISR()

队列 · 中断 queue.h
UBaseType_t uxQueueMessagesWaitingFromISR( const QueueHandle_t xQueue );

参数

参数方向说明
xQueuein要查询的队列句柄。

返回值

队列中当前的数据项个数。

说明

uxQueueMessagesWaiting() 的中断安全版本,可在中断服务程序中调用。

注意

3.12xQueueOverwrite()

队列 queue.h
BaseType_t xQueueOverwrite( QueueHandle_t xQueue, const void *pvItemToQueue );

参数

参数方向说明
xQueuein目标队列句柄。
pvItemToQueuein指向要写入的数据项。函数按队列的元素大小复制相应字节数。

返回值

恒返回 pdPASS(因为总能写入)。

说明

xQueueSendToBack() 的变体:即使队列已满也照写,直接覆盖原有数据。它专为长度为 1 的队列(“邮箱”)设计——队列非空即满,写入永远成功,读取永远拿到最新值。

典型用途:把某个传感器的最新读数、某个状态变量的最新值传给任务,旧值被覆盖正是期望行为。

注意

典型用法

/* 创建一个长度为 1 的“邮箱” */
QueueHandle_t xMailbox = xQueueCreate( 1, sizeof( uint32_t ) );

uint32_t ulLatest = 1234;
xQueueOverwrite( xMailbox, &ulLatest );

3.13xQueueOverwriteFromISR()

队列 · 中断 queue.h
BaseType_t xQueueOverwriteFromISR( QueueHandle_t xQueue,
                                    const void *pvItemToQueue,
                                    BaseType_t *pxHigherPriorityTaskWoken );

参数

参数方向说明
xQueuein目标队列句柄。
pvItemToQueuein要写入的数据项指针。
pxHigherPriorityTaskWokenout初始化为 pdFALSE;若写入解除了一个更高优先级任务的阻塞,则被置为 pdTRUE。

返回值

恒返回 pdPASS。

说明

xQueueOverwrite() 的中断安全版本,用于在中断里更新长度为 1 的“邮箱”。

注意

3.14xQueuePeek()

队列 queue.h
BaseType_t xQueuePeek( QueueHandle_t xQueue,
                        void *pvBuffer,
                        TickType_t xTicksToWait );

参数

参数方向说明
xQueuein要读取的队列句柄。
pvBufferout接收数据的内存,长度至少为队列的元素大小。
xTicksToWaitin队列为空时,任务在阻塞态等待数据的最长节拍数。0 表示不等待;portMAX_DELAY 表示无限等待(需 INCLUDE_vTaskSuspend 为 1)。

返回值

pdPASS 表示成功读到数据;errQUEUE_EMPTY 表示指定的阻塞时间内队列一直为空。

说明

从队列读取一项数据,但不从队列中移除。下一次 xQueueReceive() 或 xQueuePeek() 还会读到同一项数据。

典型用途:先看一眼队头是什么,再决定要不要处理它。

注意

3.15xQueuePeekFromISR()

队列 · 中断 queue.h
BaseType_t xQueuePeekFromISR( QueueHandle_t xQueue, void *pvBuffer );

参数

参数方向说明
xQueuein要读取的队列句柄。
pvBufferout接收数据的内存,长度至少为队列元素大小。

返回值

pdPASS 表示读取成功;errQUEUE_EMPTY 表示队列为空。

说明

xQueuePeek() 的中断安全版本:读队头但不移除。中断里不能阻塞,因此没有超时参数。

注意

3.16xQueueReceive()

队列 queue.h
BaseType_t xQueueReceive( QueueHandle_t xQueue,
                          void *pvBuffer,
                          TickType_t xTicksToWait );

参数

参数方向说明
xQueuein要读取的队列句柄。
pvBufferout接收数据的内存,长度至少为队列元素大小。
xTicksToWaitin队列为空时最长阻塞节拍数。0 表示立即返回;portMAX_DELAY 表示无限等待。

返回值

pdPASS 表示读到数据;errQUEUE_EMPTY 表示等待超时、队列仍为空。

说明

从队列读取(取走)一项数据,取走后该项从队列中删除,空间被释放,可能唤醒正在等待发送的任务。

这是队列最常用的消费接口,通常写在任务主体的死循环里。

注意

典型用法

void vConsumer( void *pvParameters )
{
    uint32_t ulValue;
    for( ;; )
    {
        if( xQueueReceive( xQueue, &ulValue, portMAX_DELAY ) == pdPASS )
        {
            /* 处理 ulValue */
        }
    }
}

3.17xQueueReceiveFromISR()

队列 · 中断 queue.h
BaseType_t xQueueReceiveFromISR( QueueHandle_t xQueue,
                                 void *pvBuffer,
                                 BaseType_t *pxHigherPriorityTaskWoken );

参数

参数方向说明
xQueuein要读取的队列句柄。
pvBufferout接收数据的内存,长度至少为队列元素大小。
pxHigherPriorityTaskWokenout若本次读取腾出了空间、解除了一个等待发送任务的阻塞,且该任务优先级更高,则被置为 pdTRUE。

返回值

pdPASS 表示读到数据;pdFAIL 表示队列为空。

说明

xQueueReceive() 的中断安全版本。中断里不能阻塞,所以没有超时参数。

注意

3.18xQueueRemoveFromSet()

队列集 queue.h
BaseType_t xQueueRemoveFromSet( QueueSetMemberHandle_t xQueueOrSemaphore,
                                QueueSetHandle_t xQueueSet );

参数

参数方向说明
xQueueOrSemaphorein要从队列集移除的队列或信号量句柄(强制转换为 QueueSetMemberHandle_t)。
xQueueSetin所属的队列集句柄。

返回值

pdPASS 表示移除成功;pdFAIL 表示该对象不是该队列集的成员(或该队列/信号量上仍有等待任务)。

说明

把一个队列或信号量从队列集中移除。移除后,该对象的就绪事件不再计入队列集。

注意

3.19xQueueReset()

队列 queue.h
BaseType_t xQueueReset( QueueHandle_t xQueue );

参数

参数方向说明
xQueuein要复位的队列句柄。

返回值

自 FreeRTOS V7.2.0 起恒返回 pdPASS(早期版本会返回 pdFAIL)。

说明

把队列恢复到创建时的空状态,队列中已有的数据全部丢弃。

注意

3.20xQueueSelectFromSet()

队列集 queue.h
QueueSetMemberHandle_t xQueueSelectFromSet( QueueSetHandle_t xQueueSet,
                                            const TickType_t xTicksToWait );

参数

参数方向说明
xQueueSetin要等待的队列集句柄。
xTicksToWaitin最长阻塞节拍数,等队列集中任一成员就绪。

返回值

返回就绪成员的句柄(队列或信号量,类型为 QueueSetMemberHandle_t);超时返回 NULL。

说明

从队列集的成员中挑出一个“有数据可取(队列)”或“可取到(信号量)”的对象并返回其句柄。

它的意义在于:让一个任务同时阻塞等待多个队列/信号量,谁先来处理谁,不必为每个对象单独开任务。

注意

典型用法

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

队列集 · 中断 queue.h
QueueSetMemberHandle_t xQueueSelectFromSetFromISR( QueueSetHandle_t xQueueSet );

参数

参数方向说明
xQueueSetin要查询的队列集句柄。中断里不能阻塞,因此没有超时参数。

返回值

返回就绪成员句柄;没有成员就绪时返回 NULL。

说明

xQueueSelectFromSet() 的中断安全版本:查询一次队列集,不阻塞。

注意

3.22xQueueSend() / xQueueSendToFront() / xQueueSendToBack()

队列 queue.h
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 );

参数

参数方向说明
xQueuein目标队列句柄。
pvItemToQueuein指向要入队的数据项。函数按创建时确定的元素大小,从该地址复制相应字节数到队列存储区。
xTicksToWaitin队列已满时,任务在阻塞态等待空位的最长节拍数。0 表示不等待、立即返回;portMAX_DELAY 表示无限等待(需 INCLUDE_vTaskSuspend 为 1)。

返回值

pdPASS 表示入队成功;errQUEUE_FULL 表示在指定时间内队列一直是满的。

说明

把数据项送入队列。三个函数只有一个区别:入队位置。

注意

典型用法

uint32_t ulValue = 42;

/* 放到队尾(FIFO) */
xQueueSend( xQueue, &ulValue, pdMS_TO_TICKS( 10 ) );

/* 紧急消息插队到队头 */
xQueueSendToFront( xQueue, &ulValue, 0 );

3.23xQueueSendFromISR() / xQueueSendToBackFromISR() / xQueueSendToFrontFromISR()

队列 · 中断 queue.h
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 );

参数

参数方向说明
xQueuein目标队列句柄。
pvItemToQueuein要入队的数据项指针。
pxHigherPriorityTaskWokenout初始化为 pdFALSE。若入队唤醒了一个正在等待该队列的任务,且其优先级高于被中断的任务,则被置为 pdTRUE。

返回值

pdPASS 表示入队成功;errQUEUE_FULL 表示队列已满(中断里无法等待,只能直接失败)。

说明

三个 Send 的中断安全版本,语义与任务版完全一致,只是没有 xTicksToWait 参数(中断中不允许阻塞)。

注意

典型用法

void vUartISR( void )
{
    BaseType_t xWoken = pdFALSE;
    uint8_t ucByte = UART->DR;

    xQueueSendFromISR( xRxQueue, &ucByte, &xWoken );
    portYIELD_FROM_ISR( xWoken );
}

3.24uxQueueSpacesAvailable()

队列 queue.h
UBaseType_t uxQueueSpacesAvailable( const QueueHandle_t xQueue );

参数

参数方向说明
xQueuein要查询的队列句柄。

返回值

队列中还剩多少个空位(还能再放多少项才会满)。

说明

查询队列的剩余空间,即“还能发多少项”。与 uxQueueMessagesWaiting() 相对:后者返回已有项数。

常见用途:发送前检查,避免因队满而丢数据;或者做流控。

注意