第 8 章 · 原书 353–376 页 · 13 个函数流缓冲区 API
流缓冲区(stream buffer)是 FreeRTOS 提供的一种字节流容器,可以理解为“变长的环形缓冲”:写入方按字节往里塞,读取方按字节往外取,不要求“一条消息一个长度”,因此非常适合“一边产、一边消”的场景,例如串口接收数据交给解析任务,或中断以不固定长度写入、任务批量读出。
它和队列的关键差异:
| 对比项 | 队列 Queue | 流缓冲区 Stream Buffer |
|---|---|---|
| 数据单位 | 定长元素,逐个拷贝 | 字节流,可一次写多个、一次读多个 |
| 长度 | 每个元素长度在创建时固定 | 写入/读取长度任意,只要不超过容量 |
| 并发 | 多任务可同时发送、同时接收 | 仅支持单写者、单读者(一写一读) |
| 阻塞条件 | 队列满/空 | 达到触发级别(trigger level)才算“有数据可读” |
触发级别(trigger level)是流缓冲区的核心概念:读取方在 xStreamBufferReceive() 里阻塞时,只有当缓冲区中的数据量达到或超过触发级别,才会被唤醒;但如果读取方已经在等待,那么即使后续写入的量没到触发级别,也会被唤醒(避免“永远等不到”)。默认触发级别等于创建时传入的值)。
消息缓冲区(第 9 章)是流缓冲区的上层封装:它给每段数据加一个长度前缀,从而能按“消息”边界读取,而流缓冲区只能按字节数读取。
8.1xStreamBufferBytesAvailable()
size_t xStreamBufferBytesAvailable( StreamBufferHandle_t xStreamBuffer );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xStreamBuffer | in | 流缓冲区句柄。 |
返回值
当前缓冲区中可读取的字节数。
说明
查询流缓冲区里现有的字节数量,用于判断“现在读一次能读到多少”,或做水位监控。
注意
- 返回值是瞬时值,下一刻可能被写入方改变。
- 要判断“是否为空”可用 xStreamBufferIsEmpty(),语义更清楚。
8.2xStreamBufferCreate()
StreamBufferHandle_t xStreamBufferCreate( size_t xBufferSizeBytes,
size_t xTriggerLevelBytes );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xBufferSizeBytes | in | 缓冲区总字节数(内部会额外占用少量控制结构)。 |
| xTriggerLevelBytes | in | 触发级别:数据量达到该值才唤醒阻塞的读取方。传 0 表示自动取 1。 |
返回值
创建成功返回句柄;堆内存不足返回 NULL。
说明
动态创建流缓冲区。写入方用 xStreamBufferSend() 写入,读取方用 xStreamBufferReceive() 读取。
触发级别的意义:让读取方“攒够一批再处理”,避免频繁被单个字节唤醒导致切换开销过大。
注意
- configSUPPORT_DYNAMIC_ALLOCATION 必须为 1。
- xBufferSizeBytes 必须大于 0,且应明显大于触发级别,否则几乎每次写入都立刻触发唤醒,失去批处理意义。
- 容量并非必须是 2 的幂(内部按字节管理),但留余量仍然重要。
典型用法
/* 256 字节缓冲,攒够 32 字节再唤醒读取任务 */ StreamBufferHandle_t xStream = xStreamBufferCreate( 256, 32 );
8.3xStreamBufferCreateStatic()
StreamBufferHandle_t xStreamBufferCreateStatic( size_t xBufferSizeBytes,
size_t xTriggerLevelBytes,
uint8_t *pucStreamBufferStorageArea,
StaticStreamBuffer_t *pxStaticStreamBuffer );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xBufferSizeBytes | in | 缓冲区字节数,必须与 pucStreamBufferStorageArea 的实际大小匹配。 |
| xTriggerLevelBytes | in | 触发级别。 |
| pucStreamBufferStorageArea | in | 应用提供的字节数组,作为缓冲区存储区。 |
| pxStaticStreamBuffer | in | 应用提供的 StaticStreamBuffer_t 结构,作为控制块。 |
返回值
创建成功返回句柄;任一指针为 NULL 或参数非法时返回 NULL。
说明
静态创建流缓冲区,存储区与控制块都由应用提供,不依赖 FreeRTOS 堆。
注意
- configSUPPORT_STATIC_ALLOCATION 必须为 1。
- 存储区大小必须 ≥ xBufferSizeBytes,且不要与其它用途复用同一块内存。
8.4vStreamBufferDelete()
void vStreamBufferDelete( StreamBufferHandle_t xStreamBuffer );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xStreamBuffer | in | 要删除的流缓冲区句柄。 |
说明
删除流缓冲区并释放内存(静态创建的只复位状态,不释放外部内存)。正阻塞在 Send/Receive 上的任务会被解除阻塞。
注意
- 删除后句柄失效,切勿再用。
- 若还有任务可能访问它,应先把任务停掉或确保其阻塞已返回,再删除。
8.5xStreamBufferIsEmpty()
BaseType_t xStreamBufferIsEmpty( StreamBufferHandle_t xStreamBuffer );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xStreamBuffer | in | 流缓冲区句柄。 |
返回值
pdTRUE 表示没有可读数据;pdFALSE 表示还有数据。
说明
判断缓冲区是否为空。
注意
- 瞬时状态,只适合粗略判断或调试;需要“有数据就取”请直接用 Receive 的 0 超时。
8.6xStreamBufferIsFull()
BaseType_t xStreamBufferIsFull( StreamBufferHandle_t xStreamBuffer );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xStreamBuffer | in | 流缓冲区句柄。 |
返回值
pdTRUE 表示缓冲区已满;pdFALSE 表示还能写入。
说明
判断缓冲区是否已满(没有剩余空间)。
注意
- 注意“满”是按存储区容量判定,不考虑触发级别。
- 同样的瞬时性问题:下一刻读取方可能已经把数据取走。
8.7xStreamBufferReceive()
size_t xStreamBufferReceive( StreamBufferHandle_t xStreamBuffer,
void *pvRxData,
size_t xBufferLengthBytes,
TickType_t xTicksToWait );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xStreamBuffer | in | 流缓冲区句柄。 |
| pvRxData | out | 接收数据的目标缓冲区。 |
| xBufferLengthBytes | in | 本次最多接收的字节数(一般等于目标缓冲区大小)。 |
| xTicksToWait | in | 无满足触发级别数据时的最长阻塞节拍数。0 表示立即返回;portMAX_DELAY 表示无限等待。 |
返回值
实际读取到的字节数;0 表示没有数据(超时或缓冲区空)。
说明
从流缓冲区读取数据。读到的是从最旧字节开始的一段连续字节,长度最多 xBufferLengthBytes——不必一次读空,因此读取方必须用返回值判断本次读了多少。
阻塞语义:若当前数据量未达触发级别,则阻塞等待;一旦被唤醒,就读取当前可用的字节(可能多于、也可能等于触发级别)。
注意
- 同一时刻只能有一个读取方;多任务读会破坏内部状态。
- 读到的长度可能小于 xBufferLengthBytes,必须按返回值处理,不能假设一次读满。
- portMAX_DELAY 需要 INCLUDE_vTaskSuspend 为 1。
典型用法
uint8_t ucBuf[64];
size_t xRead;
xRead = xStreamBufferReceive( xStream, ucBuf, sizeof( ucBuf ), portMAX_DELAY );
if( xRead > 0 )
{
/* 只有前 xRead 个字节有效 */
}
8.8xStreamBufferReceiveFromISR()
size_t xStreamBufferReceiveFromISR( StreamBufferHandle_t xStreamBuffer,
void *pvRxData,
size_t xBufferLengthBytes,
BaseType_t *pxHigherPriorityTaskWoken );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xStreamBuffer | in | 流缓冲区句柄。 |
| pvRxData | out | 接收数据的目标缓冲区。 |
| xBufferLengthBytes | in | 本次最多接收的字节数。 |
| pxHigherPriorityTaskWoken | out | 初始化为 pdFALSE;若读取动作使更高优先级的写入任务解除阻塞,则被置为 pdTRUE。 |
返回值
实际读取到的字节数。
说明
中断里从流缓冲区读取。实际工程中很少这样用(中断通常作为写入方),主要用于特殊的数据回灌场景。
注意
- 中断里不阻塞,无超时参数。
- 读写职责最好固定:中断只写、任务只读,避免复杂的中断/任务并发。
8.9xStreamBufferReset()
BaseType_t xStreamBufferReset( StreamBufferHandle_t xStreamBuffer );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xStreamBuffer | in | 要复位的流缓冲区句柄。 |
返回值
pdPASS 表示复位成功;pdFAIL 表示有任务正阻塞在该缓冲区上,复位被拒绝。
说明
清空缓冲区(丢弃所有未读数据),恢复到初始的“空”状态,但不释放内存。
用于协议出错后的重同步:发现帧校验失败,直接 Reset 丢弃脏数据,重新收帧。
注意
- 有阻塞任务时复位会失败——需要先让阻塞返回(例如用超时),再复位。
- 复位会丢弃数据,别在正常接收路径里盲目调用。
8.10xStreamBufferSend()
size_t xStreamBufferSend( StreamBufferHandle_t xStreamBuffer,
const void *pvTxData,
size_t xDataLengthBytes,
TickType_t xTicksToWait );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xStreamBuffer | in | 流缓冲区句柄。 |
| pvTxData | in | 要写入的数据起始地址。 |
| xDataLengthBytes | in | 要写入的字节数。 |
| xTicksToWait | in | 空间不足时的最长阻塞节拍数。0 表示不等待;portMAX_DELAY 表示无限等待。 |
返回值
实际写入的字节数;0 表示一字节也没写进去(空间不足且超时)。
说明
向流缓冲区写入数据。若剩余空间不足,按 xTicksToWait 等待;被唤醒后尽可能写入,但可能只写入一部分——返回值告诉实际成功了多少。
典型用法:中断里以不固定长度写入串口收到的字节,任务侧按批读出解析。
注意
- 只能有一个写入方;多任务写需要外层加锁。
- 必须处理“部分写入”的情况:对于要求整帧完整写入的协议,写一半会破坏数据。可先用 xStreamBufferSpacesAvailable() 判断空间是否够,或改用消息缓冲区。
- portMAX_DELAY 需要 INCLUDE_vTaskSuspend 为 1。
典型用法
size_t xWritten;
xWritten = xStreamBufferSend( xStream, pucFrame, uxFrameLen, pdMS_TO_TICKS( 10 ) );
if( xWritten != uxFrameLen )
{
/* 未写全:丢弃该帧或重试 */
}
8.11xStreamBufferSendFromISR()
size_t xStreamBufferSendFromISR( StreamBufferHandle_t xStreamBuffer,
const void *pvTxData,
size_t xDataLengthBytes,
BaseType_t *pxHigherPriorityTaskWoken );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xStreamBuffer | in | 流缓冲区句柄。 |
| pvTxData | in | 要写入的数据起始地址。 |
| xDataLengthBytes | in | 要写入的字节数。 |
| pxHigherPriorityTaskWoken | out | 初始化为 pdFALSE;若写入使更高优先级的读取任务解除阻塞,则被置为 pdTRUE。 |
返回值
实际写入的字节数;空间不足时可能小于请求长度,甚至为 0。
说明
中断里向流缓冲区写入,这是流缓冲区最主要的落地场景:ISR 收数据,任务做解析。
注意
- 中断里不阻塞,因此空间不够就直接少写,必须按返回值判断。
- 若返回值小于请求长度,说明数据丢了——串口这种“丢字节”会导致帧错位,此时应考虑加大缓冲区或改用 DMA + 消息缓冲区。
- pxHigherPriorityTaskWoken 需由 portYIELD_FROM_ISR() 处理。
8.12xStreamBufferSetTriggerLevel()
BaseType_t xStreamBufferSetTriggerLevel( StreamBufferHandle_t xStreamBuffer, size_t xTriggerLevel );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xStreamBuffer | in | 流缓冲区句柄。 |
| xTriggerLevel | in | 新的触发级别(字节数)。传 0 表示取 1。 |
返回值
pdPASS 表示设置成功;pdFAIL 表示触发级别超过缓冲区容量。
说明
运行期修改触发级别。例如协议切换后,一帧最小长度变化,需要对应调整批处理阈值。
注意
- 触发级别不能大于缓冲区总容量。
- 触发级别只影响“唤醒条件”,不影响实际可读的数据量。
8.13xStreamBufferSpacesAvailable()
size_t xStreamBufferSpacesAvailable( StreamBufferHandle_t xStreamBuffer );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xStreamBuffer | in | 流缓冲区句柄。 |
返回值
当前还可写入的字节数。
说明
查询剩余空间。写入方在“必须整块写入”的场景下,先查空间再写,可避免部分写入破坏数据。
注意
- 返回值是瞬时值,查询与写入之间别的写入方可能已经占用空间(单写者模型下一般安全,中断里写入时需当心)。
- 返回值不含控制结构开销,就是可用字节数。