在实际项目中,环形缓冲区的设计要比之前讲到的原型稍微复杂一些,需要一些接口函数来实现数据结构封装。GitHub上有个大帅哥写了一个轻量的环形缓冲区库,可以学习参考,也可以直接集成到自己的项目中,功能已经非常完善。
特点
- 使用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 <tilen@majerle.eu>
* 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 buffer
lwrb_t buffer;
uint8_t data[16];
lwrb_init(&buffer, data, sizeof(data));
// Set the event callback function
lwrb_set_event_callback(&buffer, example_event_callback);
// Example operations on the buffer
lwrb_write(&buffer, (uint8_t*)"Hello", 5);
lwrb_read(&buffer, data, 3);
lwrb_reset(&buffer);
return 0;
}
上述代码演示了如何设置 LwRB 缓冲区的事件回调函数以获取关于读取、写入和重置操作的通知。在每次读取或写入时,将调用相应的事件回调函数。
公众号 | FunIO
微信搜一搜 “funio”,发现更多精彩内容。
个人博客 | blog.boringhex.top