实际项目中的环形缓冲区

在实际项目中，环形缓冲区的设计要比之前讲到的原型稍微复杂一些，需要一些接口函数来实现数据结构封装。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 <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