第 9 章 · 原书 377–398 页 · 11 个函数消息缓冲区 API
消息缓冲区(message buffer)是流缓冲区之上的一层薄封装:它在每段数据前面写入一个长度前缀,因此读取时可以“按消息边界”取出整段数据,而不必自己记录长度。
它保留流缓冲区的两个特性:单写者、单读者;也继承一个需要注意的容量开销——每条消息额外占用 sizeof( size_t ) 字节存长度(32 位平台为 4 字节)。
| 对比项 | 流缓冲区 | 消息缓冲区 |
|---|---|---|
| 读取单位 | 任意字节数 | 一条完整消息(按写入时的长度) |
| 长度传递 | 应用自己知道 | 内部长度前缀,读方用返回值或定长缓冲接收 |
| 额外开销 | 无 | 每条消息 sizeof(size_t) 字节 + 对齐 |
| 典型用途 | 串口字节流、ADC 采样流 | 变长报文、命令、事件数据包 |
与队列相比,消息缓冲区允许“每条消息长度不同”,但依然是单写单读;需要多任务并发写入时仍应使用队列。
9.1xMessageBufferCreate()
MessageBufferHandle_t xMessageBufferCreate( size_t xBufferSizeBytes );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xBufferSizeBytes | in | 缓冲区总字节数(消息数据 + 每条消息的长度前缀都从这里占用)。 |
返回值
创建成功返回句柄;堆内存不足返回 NULL。
说明
动态创建消息缓冲区。可用空间要按“消息字节数 + sizeof(size_t)”估算,实际能容纳的消息数比同样字节数的流缓冲区少。
注意
- configSUPPORT_DYNAMIC_ALLOCATION 必须为 1。
- 只有单写者、单读者模型,多生产者会破坏内部状态。
- 容量给太小时,发送会被阻塞或失败,而错误表现是“发送超时”,容易误判为任务优先级问题。
典型用法
/* 若最大报文 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()
MessageBufferHandle_t xMessageBufferCreateStatic( size_t xBufferSizeBytes,
uint8_t *pucMessageBufferStorageArea,
StaticMessageBuffer_t *pxStaticMessageBuffer );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xBufferSizeBytes | in | 缓冲区字节数,需与存储区实际大小匹配。 |
| pucMessageBufferStorageArea | in | 应用提供的字节数组,作为存储区。 |
| pxStaticMessageBuffer | in | 应用提供的 StaticMessageBuffer_t 控制块。 |
返回值
创建成功返回句柄;指针为 NULL 或参数非法时返回 NULL。
说明
静态创建消息缓冲区,存储区与控制块由应用提供。
注意
- configSUPPORT_STATIC_ALLOCATION 必须为 1。
- 存储区大小必须 ≥ xBufferSizeBytes,且不要与其它数据共用。
9.3vMessageBufferDelete()
void vMessageBufferDelete( MessageBufferHandle_t xMessageBuffer );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xMessageBuffer | in | 要删除的消息缓冲区句柄。 |
说明
删除消息缓冲区并释放内存(静态创建的不释放外部存储区)。阻塞在收发上的任务会被解除阻塞。
注意
- 删除后句柄失效。
- 若有任务仍在等待,应先确保其退出。
9.4xMessageBufferIsEmpty()
BaseType_t xMessageBufferIsEmpty( MessageBufferHandle_t xMessageBuffer );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xMessageBuffer | in | 消息缓冲区句柄。 |
返回值
pdTRUE 表示没有任何消息;pdFALSE 表示还有消息。
说明
判断是否为空(一条消息都没有)。
注意
- 瞬时状态,仅适合调试或粗略判断。
9.5xMessageBufferIsFull()
BaseType_t xMessageBufferIsFull( MessageBufferHandle_t xMessageBuffer );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xMessageBuffer | in | 消息缓冲区句柄。 |
返回值
pdTRUE 表示已满(连一条新消息都放不下);pdFALSE 表示还有空间。
说明
判断是否已满。注意“满”是按剩余空间能否容纳一条消息(含长度前缀)判定,不是严格等于容量用尽。
注意
- 发送时若空间只够放数据不够放长度前缀,同样会失败。
9.6xMessageBufferReceive()
size_t xMessageBufferReceive( MessageBufferHandle_t xMessageBuffer,
void *pvRxData,
size_t xBufferLengthBytes,
TickType_t xTicksToWait );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xMessageBuffer | in | 消息缓冲区句柄。 |
| pvRxData | out | 接收消息的目标缓冲区。 |
| xBufferLengthBytes | in | 接收缓冲的最大长度,必须 ≥ 最大可能的消息长度。 |
| xTicksToWait | in | 无消息时的最长阻塞节拍数。0 表示立即返回;portMAX_DELAY 表示无限等待。 |
返回值
读出消息的字节数(不含长度前缀);0 表示超时无消息(或缓冲区为空)。
说明
读取一条完整消息。返回值是消息长度;若接收缓冲不够长(xBufferLengthBytes 小于消息长度),该消息会被丢弃,返回值仍是其长度。
阻塞时按“有消息到达”唤醒,不存在流缓冲区那种触发级别概念。
注意
- 接收缓冲必须按“最大报文长度”分配,否则会静默丢消息——这是本 API 最常见的故障。
- 同一时刻只能有一个读取方。
- portMAX_DELAY 需要 INCLUDE_vTaskSuspend 为 1。
典型用法
size_t xLen = xMessageBufferReceive( xMsgBuf, ucRx, sizeof( ucRx ), portMAX_DELAY );
if( ( xLen > 0 ) && ( xLen <= sizeof( ucRx ) ) )
{
/* 消息完整,长度为 xLen */
}
else if( xLen > sizeof( ucRx ) )
{
/* 消息过长,已被丢弃:说明接收缓冲配小了 */
}
9.7xMessageBufferReceiveFromISR()
size_t xMessageBufferReceiveFromISR( MessageBufferHandle_t xMessageBuffer,
void *pvRxData,
size_t xBufferLengthBytes,
BaseType_t *pxHigherPriorityTaskWoken );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xMessageBuffer | in | 消息缓冲区句柄。 |
| pvRxData | out | 接收消息的目标缓冲区。 |
| xBufferLengthBytes | in | 接收缓冲最大长度。 |
| pxHigherPriorityTaskWoken | out | 初始化为 pdFALSE;若读取使更高优先级的发送任务解除阻塞,则被置为 pdTRUE。 |
返回值
读出消息的字节数;0 表示没有消息。
说明
中断里读取消息。实际使用很少(中断一般作为发送方)。
注意
- 中断里不阻塞,无超时参数。
- 接收缓冲同样必须够长,否则消息被丢弃。
9.8xMessageBufferReset()
BaseType_t xMessageBufferReset( MessageBufferHandle_t xMessageBuffer );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xMessageBuffer | in | 要复位(清空)的消息缓冲区句柄。 |
返回值
pdPASS 表示成功清空;pdFAIL 表示有任务正阻塞其上,复位被拒绝。
说明
丢弃所有未读消息,恢复为空状态,不释放内存。用于协议重同步或清理积压。
注意
- 必须没有阻塞任务时才成功,否则需先让等待方超时返回。
- 清空即丢数据,别放进正常路径。
9.9xMessageBufferSend()
size_t xMessageBufferSend( MessageBufferHandle_t xMessageBuffer,
const void *pvTxData,
size_t xDataLengthBytes,
TickType_t xTicksToWait );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xMessageBuffer | in | 消息缓冲区句柄。 |
| pvTxData | in | 消息数据起始地址。 |
| xDataLengthBytes | in | 消息长度(不含内部长度前缀)。 |
| xTicksToWait | in | 空间不足时的最长阻塞节拍数。0 表示不等待;portMAX_DELAY 表示无限等待。 |
返回值
写入成功的字节数(等于 xDataLengthBytes);0 表示未写入(空间不足或超时)。
说明
把一段数据作为一条消息写入。消息要么整条写入,要么不写——不存在“写一半”的情况,这正是它比流缓冲区更安全的地方。
注意
- 消息整条原子写入,这点对“命令/报文”场景很重要。
- 所需空间 = 消息长度 + sizeof(size_t),容量估算时要算上长度前缀。
- 单写者模型:多任务同时写会破坏内部状态。
典型用法
size_t xSent = xMessageBufferSend( xMsgBuf, pucPacket, uxLen, pdMS_TO_TICKS( 5 ) );
if( xSent == 0 )
{
/* 缓冲区满,本条报文未发送 */
}
9.10xMessageBufferSendFromISR()
size_t xMessageBufferSendFromISR( MessageBufferHandle_t xMessageBuffer,
const void *pvTxData,
size_t xDataLengthBytes,
BaseType_t *pxHigherPriorityTaskWoken );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xMessageBuffer | in | 消息缓冲区句柄。 |
| pvTxData | in | 消息数据起始地址。 |
| xDataLengthBytes | in | 消息长度。 |
| pxHigherPriorityTaskWoken | out | 初始化为 pdFALSE;若发送使更高优先级的接收任务解除阻塞,则被置为 pdTRUE。 |
返回值
写入成功的字节数;0 表示空间不足,整条未写入。
说明
中断里把一段数据作为一条消息发送。这是消息缓冲区最典型的用法:ISR 里收完一帧,整帧投递给解析任务。
注意
- 中断里不阻塞;空间不足时整条丢弃,必须按返回值判断并考虑重试或计数丢失。
- pxHigherPriorityTaskWoken 需由 portYIELD_FROM_ISR() 处理。
9.11xMessageBufferSpacesAvailable()
size_t xMessageBufferSpacesAvailable( MessageBufferHandle_t xMessageBuffer );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xMessageBuffer | in | 消息缓冲区句柄。 |
返回值
当前剩余空间(字节)。
说明
查询还能写入多少字节(含每条消息的长度前缀开销)。发送方可在“必须整条发送”的场景下先查空间,避免白等一场。
注意
- 剩余空间 ≥ 消息长度 + sizeof(size_t) 才写得进去。
- 返回值瞬时有效,中断并发写入时不可依赖。