实际项目中的环形缓冲区

在实际项目中，环形缓冲区的设计要比之前讲到的原型稍微复杂一些，需要一些接口函数来实现数据结构封装。GitHub上有个大帅哥写了一个轻量的环形缓冲区库，可以学习参考，也可以直接集成到自己的项目中，功能已经非常完善。

LwRB

特点

• 使用C语言编写（C11），与size_t兼容的大小数据类型
• 独立于平台，没有特定于体系结构的代码
• 先进先出（FIFO）缓冲区实现
• 无动态内存分配，数据为静态数组
• 使用优化的内存复制而不是循环来读取/写入内存中的数据
• 在作为单个写入和单个读取条目的管道时线程安全
• 在作为单个写入和单个读取条目的管道时中断安全
• 适用于在缓冲区和应用程序内存之间进行零拷贝的DMA传输
• 支持数据的查看、读取跳过和写入前进
• 实现事件通知的支持
• 用户友好的MIT许可证

要求

• C编译器
• 少于1kB的非易失性存储器

示例代码

用于读取和写入缓冲区的简化示例代码：

/* 声明rb实例和原始数据 */
lwrb_t buff;
uint8_t buff_data[8];/* 应用程序变量 */
uint8_t data[2];
size_t len;/* 应用程序代码... */
lwrb_init(&buff, buff_data, sizeof(buff_data)); /* 初始化缓冲区 *//* 写入4个字节的数据 */
lwrb_write(&buff, "0123", 4);/* 尝试读取缓冲区 */
/* len保存读取的字节数 */
/* 当缓冲区为空时，读取直到len == 0 */
while ((len = lwrb_read(&buff, data, sizeof(data))) > 0) {printf("成功读取%d个字节\r\n", (int)len);
}

我们首先看下这个库的接口文件：

/*** \file            lwrb.h* \brief           LwRB - Lightweight ring buffer*//** Copyright (c) 2023 Tilen MAJERLE** Permission is hereby granted, free of charge, to any person* obtaining a copy of this software and associated documentation* files (the "Software"), to deal in the Software without restriction,* including without limitation the rights to use, copy, modify, merge,* publish, distribute, sublicense, and/or sell copies of the Software,* and to permit persons to whom the Software is furnished to do so,* subject to the following conditions:** The above copyright notice and this permission notice shall be* included in all copies or substantial portions of the Software.** THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES* OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE* AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,* WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING* FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR* OTHER DEALINGS IN THE SOFTWARE.** This file is part of LwRB - Lightweight ring buffer library.** Author:          Tilen MAJERLE <[e-mail]>* Version:         v3.1.0*/
#ifndef LWRB_HDR_H
#define LWRB_HDR_H#include <stddef.h>
#include <stdint.h>
#include <string.h>#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus *//*** \defgroup        LWRB Lightweight ring buffer manager* \brief           Lightweight ring buffer manager* \{*/#if !defined(LWRB_DISABLE_ATOMIC) || __DOXYGEN__
#include <stdatomic.h>/*** \brief           Atomic type for size variable.* Default value is set to be `unsigned 32-bits` type*/
typedef atomic_ulong lwrb_sz_atomic_t;/*** \brief           Size variable for all library operations.* Default value is set to be `unsigned 32-bits` type*/
typedef unsigned long lwrb_sz_t;
#else
typedef unsigned long lwrb_sz_atomic_t;
typedef unsigned long lwrb_sz_t;
#endif/*** \brief           Event type for buffer operations*/
typedef enum {LWRB_EVT_READ,  /*!< Read event */LWRB_EVT_WRITE, /*!< Write event */LWRB_EVT_RESET, /*!< Reset event */
} lwrb_evt_type_t;/*** \brief           Buffer structure forward declaration*/
struct lwrb;/*** \brief           Event callback function type* \param[in]       buff: Buffer handle for event* \param[in]       evt: Event type* \param[in]       bp: Number of bytes written or read (when used), depends on event type*/
typedef void (*lwrb_evt_fn)(struct lwrb* buff, lwrb_evt_type_t evt, lwrb_sz_t bp);/* List of flags */
#define LWRB_FLAG_READ_ALL  ((uint16_t)0x0001)
#define LWRB_FLAG_WRITE_ALL ((uint16_t)0x0001)/*** \brief           Buffer structure*/
typedef struct lwrb {uint8_t* buff;  /*!< Pointer to buffer data. Buffer is considered initialized when `buff != NULL` and `size > 0` */lwrb_sz_t size; /*!< Size of buffer data. Size of actual buffer is `1` byte less than value holds */lwrb_sz_atomic_t r; /*!< Next read pointer. Buffer is considered empty when `r == w` and full when `w == r - 1` */lwrb_sz_atomic_t w; /*!< Next write pointer. Buffer is considered empty when `r == w` and full when `w == r - 1` */lwrb_evt_fn evt_fn; /*!< Pointer to event callback function */
} lwrb_t;uint8_t lwrb_init(lwrb_t* buff, void* buffdata, lwrb_sz_t size);
uint8_t lwrb_is_ready(lwrb_t* buff);
void lwrb_free(lwrb_t* buff);
void lwrb_reset(lwrb_t* buff);
void lwrb_set_evt_fn(lwrb_t* buff, lwrb_evt_fn fn);/* Read/Write functions */
lwrb_sz_t lwrb_write(lwrb_t* buff, const void* data, lwrb_sz_t btw);
lwrb_sz_t lwrb_read(lwrb_t* buff, void* data, lwrb_sz_t btr);
lwrb_sz_t lwrb_peek(const lwrb_t* buff, lwrb_sz_t skip_count, void* data, lwrb_sz_t btp);/* Extended read/write functions */
uint8_t lwrb_write_ex(lwrb_t* buff, const void* data, lwrb_sz_t btw, lwrb_sz_t* bw, uint16_t flags);
uint8_t lwrb_read_ex(lwrb_t* buff, void* data, lwrb_sz_t btr, lwrb_sz_t* br, uint16_t flags);/* Buffer size information */
lwrb_sz_t lwrb_get_free(const lwrb_t* buff);
lwrb_sz_t lwrb_get_full(const lwrb_t* buff);/* Read data block management */
void* lwrb_get_linear_block_read_address(const lwrb_t* buff);
lwrb_sz_t lwrb_get_linear_block_read_length(const lwrb_t* buff);
lwrb_sz_t lwrb_skip(lwrb_t* buff, lwrb_sz_t len);/* Write data block management */
void* lwrb_get_linear_block_write_address(const lwrb_t* buff);
lwrb_sz_t lwrb_get_linear_block_write_length(const lwrb_t* buff);
lwrb_sz_t lwrb_advance(lwrb_t* buff, lwrb_sz_t len);/* Search in buffer */
uint8_t lwrb_find(const lwrb_t* buff, const void* bts, lwrb_sz_t len, lwrb_sz_t start_offset, lwrb_sz_t* found_idx);
lwrb_sz_t lwrb_overwrite(lwrb_t* buff, const void* data, lwrb_sz_t btw);
lwrb_sz_t lwrb_move(lwrb_t* dest, lwrb_t* src);/*** \}*/#ifdef __cplusplus
}
#endif /* __cplusplus */#endif /* LWRB_HDR_H */

首先，代码包含了一些必要的头文件，并检查是否在C++环境中。如果是，就使用extern "C"来确保C++编译器以C语言的方式处理这个库。

然后，定义了一些类型和枚举。例如，lwrb_sz_t和lwrb_sz_atomic_t用于表示缓冲区的大小，lwrb_evt_type_t是一个枚举，表示缓冲区操作的事件类型。

lwrb_t是主要的数据结构，表示一个环形缓冲区。它包含了指向缓冲区数据的指针、缓冲区的大小、读写指针以及一个事件回调函数。与之前介绍的最简化的环形缓冲区相比，这个结构中还包含了一个缓冲区大小和一个事件回调函数。事件回调函数用于在缓冲区操作时通知应用程序。

接下来是一系列的函数声明，这些函数用于操作环形缓冲区。例如，lwrb_init用于初始化一个环形缓冲区，lwrb_write和lwrb_read用于向缓冲区写入数据和从缓冲区读取数据。

最后，代码检查是否在C++环境中。如果是，就结束extern "C"。

事件

在应用程序中使用 LwRB 时，获取有关不同事件的通知可能会很有用，例如在向缓冲区写入或读取数据时获得通知。

该库支持在缓冲区数据发生修改时调用的事件，这意味着在每次读取或写入操作时都会触发事件。

一些用例：

• 通知应用程序层 LwRB 操作已被执行并发送调试消息
• 当应用程序使用操作系统时，当已写入/读取足够数量的字节到/从缓冲区时，解锁信号量
• 在操作系统级别的消息队列中写入通知以唤醒另一个任务

注意： 每个修改 read 或 write 内部指针的操作都被视为读取或写入操作。唯一的例外是 重置 事件，它将两个内部指针都设置为 0。

#include <stdio.h>
#include "lwrb/lwrb.h"// Example callback function for LwRB events
void example_event_callback(lwrb_t* buffer, lwrb_event_t event, size_t length) {switch (event) {case LWRB_EVENT_READ:printf("Read event: %zu bytes read from buffer\n", length);break;case LWRB_EVENT_WRITE:printf("Write event: %zu bytes written to buffer\n", length);break;case LWRB_EVENT_RESET:printf("Reset event: Buffer has been reset\n");break;default:break;}
}int main() {// Initialize LwRB bufferlwrb_t buffer;uint8_t data[16];lwrb_init(&buffer, data, sizeof(data));// Set the event callback functionlwrb_set_event_callback(&buffer, example_event_callback);// Example operations on the bufferlwrb_write(&buffer, (uint8_t*)"Hello", 5);lwrb_read(&buffer, data, 3);lwrb_reset(&buffer);return 0;
}

上述代码演示了如何设置 LwRB 缓冲区的事件回调函数以获取关于读取、写入和重置操作的通知。在每次读取或写入时，将调用相应的事件回调函数。

公众号 | FunIO
微信搜一搜 “funio”，发现更多精彩内容。
个人博客 | blog.boringhex.top