FreeRTOS 中文参考手册 /9 消息缓冲区 API

第 9 章 · 原书 377–398 页 · 11 个函数消息缓冲区 API

Chapter 9 · Message Buffer API

消息缓冲区(message buffer)是流缓冲区之上的一层薄封装:它在每段数据前面写入一个长度前缀,因此读取时可以“按消息边界”取出整段数据,而不必自己记录长度。

它保留流缓冲区的两个特性:单写者、单读者;也继承一个需要注意的容量开销——每条消息额外占用 sizeof( size_t ) 字节存长度(32 位平台为 4 字节)。

对比项流缓冲区消息缓冲区
读取单位任意字节数一条完整消息(按写入时的长度)
长度传递应用自己知道内部长度前缀,读方用返回值或定长缓冲接收
额外开销无每条消息 sizeof(size_t) 字节 + 对齐
典型用途串口字节流、ADC 采样流变长报文、命令、事件数据包
最关键的坑:调用 xMessageBufferReceive() 时,若传入的接收缓冲长度小于消息实际长度,该消息会被整条丢弃(从缓冲区中移除,数据丢失,但返回值仍给出这条消息的长度)。所以接收缓冲必须够大,或用 xMessageBufferSpacesAvailable() 之外的方式预先取长度——即固定最大报文长度。

与队列相比,消息缓冲区允许“每条消息长度不同”,但依然是单写单读;需要多任务并发写入时仍应使用队列。

9.1xMessageBufferCreate()

消息缓冲区 · 创建 message_buffer.h
MessageBufferHandle_t xMessageBufferCreate( size_t xBufferSizeBytes );

参数

参数方向说明
xBufferSizeBytesin缓冲区总字节数(消息数据 + 每条消息的长度前缀都从这里占用)。

返回值

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

说明

动态创建消息缓冲区。可用空间要按“消息字节数 + sizeof(size_t)”估算,实际能容纳的消息数比同样字节数的流缓冲区少。

注意

典型用法

/* 若最大报文 64 字节,每条占 64+4=68 字节;想同时放 8 条,容量取 8*68 有余量即可 */
MessageBufferHandle_t xMsgBuf = xMessageBufferCreate( 600 );

/* 写一条 */
xMessageBufferSend( xMsgBuf, pucPacket, uxLen, pdMS_TO_TICKS( 10 ) );

/* 读一条(接收缓冲必须 >= 最大报文长度) */
uint8_t ucRx[ 64 ];
size_t xLen = xMessageBufferReceive( xMsgBuf, ucRx, sizeof( ucRx ), portMAX_DELAY );

9.2xMessageBufferCreateStatic()

消息缓冲区 · 创建 message_buffer.h
MessageBufferHandle_t xMessageBufferCreateStatic( size_t xBufferSizeBytes,
                                                    uint8_t *pucMessageBufferStorageArea,
                                                    StaticMessageBuffer_t *pxStaticMessageBuffer );

参数

参数方向说明
xBufferSizeBytesin缓冲区字节数,需与存储区实际大小匹配。
pucMessageBufferStorageAreain应用提供的字节数组,作为存储区。
pxStaticMessageBufferin应用提供的 StaticMessageBuffer_t 控制块。

返回值

创建成功返回句柄;指针为 NULL 或参数非法时返回 NULL。

说明

静态创建消息缓冲区,存储区与控制块由应用提供。

注意

9.3vMessageBufferDelete()

消息缓冲区 message_buffer.h
void vMessageBufferDelete( MessageBufferHandle_t xMessageBuffer );

参数

参数方向说明
xMessageBufferin要删除的消息缓冲区句柄。

说明

删除消息缓冲区并释放内存(静态创建的不释放外部存储区)。阻塞在收发上的任务会被解除阻塞。

注意

9.4xMessageBufferIsEmpty()

消息缓冲区 · 查询 message_buffer.h
BaseType_t xMessageBufferIsEmpty( MessageBufferHandle_t xMessageBuffer );

参数

参数方向说明
xMessageBufferin消息缓冲区句柄。

返回值

pdTRUE 表示没有任何消息;pdFALSE 表示还有消息。

说明

判断是否为空(一条消息都没有)。

注意

9.5xMessageBufferIsFull()

消息缓冲区 · 查询 message_buffer.h
BaseType_t xMessageBufferIsFull( MessageBufferHandle_t xMessageBuffer );

参数

参数方向说明
xMessageBufferin消息缓冲区句柄。

返回值

pdTRUE 表示已满(连一条新消息都放不下);pdFALSE 表示还有空间。

说明

判断是否已满。注意“满”是按剩余空间能否容纳一条消息(含长度前缀)判定,不是严格等于容量用尽。

注意

9.6xMessageBufferReceive()

消息缓冲区 · 读取 message_buffer.h
size_t xMessageBufferReceive( MessageBufferHandle_t xMessageBuffer,
                               void *pvRxData,
                               size_t xBufferLengthBytes,
                               TickType_t xTicksToWait );

参数

参数方向说明
xMessageBufferin消息缓冲区句柄。
pvRxDataout接收消息的目标缓冲区。
xBufferLengthBytesin接收缓冲的最大长度,必须 ≥ 最大可能的消息长度。
xTicksToWaitin无消息时的最长阻塞节拍数。0 表示立即返回;portMAX_DELAY 表示无限等待。

返回值

读出消息的字节数(不含长度前缀);0 表示超时无消息(或缓冲区为空)。

说明

读取一条完整消息。返回值是消息长度;若接收缓冲不够长(xBufferLengthBytes 小于消息长度),该消息会被丢弃,返回值仍是其长度。

阻塞时按“有消息到达”唤醒,不存在流缓冲区那种触发级别概念。

注意

典型用法

size_t xLen = xMessageBufferReceive( xMsgBuf, ucRx, sizeof( ucRx ), portMAX_DELAY );
if( ( xLen > 0 ) && ( xLen <= sizeof( ucRx ) ) )
{
    /* 消息完整,长度为 xLen */
}
else if( xLen > sizeof( ucRx ) )
{
    /* 消息过长,已被丢弃:说明接收缓冲配小了 */
}

9.7xMessageBufferReceiveFromISR()

消息缓冲区 · 中断 message_buffer.h
size_t xMessageBufferReceiveFromISR( MessageBufferHandle_t xMessageBuffer,
                                      void *pvRxData,
                                      size_t xBufferLengthBytes,
                                      BaseType_t *pxHigherPriorityTaskWoken );

参数

参数方向说明
xMessageBufferin消息缓冲区句柄。
pvRxDataout接收消息的目标缓冲区。
xBufferLengthBytesin接收缓冲最大长度。
pxHigherPriorityTaskWokenout初始化为 pdFALSE;若读取使更高优先级的发送任务解除阻塞,则被置为 pdTRUE。

返回值

读出消息的字节数;0 表示没有消息。

说明

中断里读取消息。实际使用很少(中断一般作为发送方)。

注意

9.8xMessageBufferReset()

消息缓冲区 message_buffer.h
BaseType_t xMessageBufferReset( MessageBufferHandle_t xMessageBuffer );

参数

参数方向说明
xMessageBufferin要复位(清空)的消息缓冲区句柄。

返回值

pdPASS 表示成功清空;pdFAIL 表示有任务正阻塞其上,复位被拒绝。

说明

丢弃所有未读消息,恢复为空状态,不释放内存。用于协议重同步或清理积压。

注意

9.9xMessageBufferSend()

消息缓冲区 · 发送 message_buffer.h
size_t xMessageBufferSend( MessageBufferHandle_t xMessageBuffer,
                             const void *pvTxData,
                             size_t xDataLengthBytes,
                             TickType_t xTicksToWait );

参数

参数方向说明
xMessageBufferin消息缓冲区句柄。
pvTxDatain消息数据起始地址。
xDataLengthBytesin消息长度(不含内部长度前缀)。
xTicksToWaitin空间不足时的最长阻塞节拍数。0 表示不等待;portMAX_DELAY 表示无限等待。

返回值

写入成功的字节数(等于 xDataLengthBytes);0 表示未写入(空间不足或超时)。

说明

把一段数据作为一条消息写入。消息要么整条写入,要么不写——不存在“写一半”的情况,这正是它比流缓冲区更安全的地方。

注意

典型用法

size_t xSent = xMessageBufferSend( xMsgBuf, pucPacket, uxLen, pdMS_TO_TICKS( 5 ) );
if( xSent == 0 )
{
    /* 缓冲区满,本条报文未发送 */
}

9.10xMessageBufferSendFromISR()

消息缓冲区 · 中断 message_buffer.h
size_t xMessageBufferSendFromISR( MessageBufferHandle_t xMessageBuffer,
                                    const void *pvTxData,
                                    size_t xDataLengthBytes,
                                    BaseType_t *pxHigherPriorityTaskWoken );

参数

参数方向说明
xMessageBufferin消息缓冲区句柄。
pvTxDatain消息数据起始地址。
xDataLengthBytesin消息长度。
pxHigherPriorityTaskWokenout初始化为 pdFALSE;若发送使更高优先级的接收任务解除阻塞,则被置为 pdTRUE。

返回值

写入成功的字节数;0 表示空间不足,整条未写入。

说明

中断里把一段数据作为一条消息发送。这是消息缓冲区最典型的用法:ISR 里收完一帧,整帧投递给解析任务。

注意

9.11xMessageBufferSpacesAvailable()

消息缓冲区 · 查询 message_buffer.h
size_t xMessageBufferSpacesAvailable( MessageBufferHandle_t xMessageBuffer );

参数

参数方向说明
xMessageBufferin消息缓冲区句柄。

返回值

当前剩余空间(字节)。

说明

查询还能写入多少字节(含每条消息的长度前缀开销)。发送方可在“必须整条发送”的场景下先查空间,避免白等一场。

注意