实际项目中的环形缓冲区

发表于 更新于 阅读次数： 本文字数： 1.7k 阅读时长 ≈ 6 分钟

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

LwRB

特点

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

要求

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

示例代码

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
/* 声明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);
}

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
/**
 * \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。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
#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 缓冲区的事件回调函数以获取关于读取、写入和重置操作的通知。在每次读取或写入时，将调用相应的事件回调函数。