# ringbuffer

**Repository Path**: YaHuiJJo/ringbuffer

## Basic Information

- **Project Name**: ringbuffer
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-04
- **Last Updated**: 2026-08-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ringbuffer

从RTThread中提取一个可移植的字节环形缓冲区（ring buffer）实现，面向裸机与嵌入式场景。

- 纯 C99，仅依赖 `<stddef.h>`、`<stdint.h>`、`<string.h>`
- 不做任何动态内存分配，缓冲区对象与底层存储区均由调用者提供
- 通过读写索引 + 镜像位区分空 / 满状态
- 支持普通写入、强制覆盖写入、拷贝读取，以及零拷贝的连续区间访问
- 临界区通过可覆盖的宏实现，默认空操作，方便适配中断保护

## 目录结构

```
ringbuffer.c            环形缓冲区实现
ringbuffer.h            公共 API
tests/
    test_ringbuffer.c   主机端单元测试
    critical_hooks.h    注入计数型临界区钩子
    run_tests.ps1       用 GCC 构建并运行测试
```

## 核心概念

`read_index` / `write_index` 与各自的镜像位共同编码缓冲区状态：

- 索引相等且镜像位相同 → 空
- 索引相等且镜像位不同 → 满

每当索引在 `buffer_size` 处回绕，索引归零并翻转对应镜像位。

有效容量即 `buffer_size`：初始化时按请求大小使用，不做对齐，拒绝 `0` 与大于 `0x7FFFFFFF` 的值。

## 快速开始

```c
#include "ringbuffer.h"

static uint8_t storage[64];
static ringbuffer_t rb;

void example(void)
{
    ringbuffer_init(&rb, storage, sizeof(storage));

    const uint8_t tx[] = {1, 2, 3, 4};
    ringbuffer_put(&rb, tx, sizeof(tx));      /* 空间不足时截断 */

    uint8_t rx[4];
    size_t n = ringbuffer_get(&rb, rx, sizeof(rx));  /* n 为实际读取字节数 */

    (void)n;
}
```

## API 概览

| 函数 | 说明 |
| --- | --- |
| `ringbuffer_init` | 绑定对象与存储区并复位游标 |
| `ringbuffer_reset` | 仅复位读写游标，不清除存储区内容 |
| `ringbuffer_put` | 写入一块数据，空间不足时截断 |
| `ringbuffer_put_force` | 强制写入，空间不足时覆盖最旧数据；超容量时仅保留末尾 `buffer_size` 字节 |
| `ringbuffer_putchar` | 写入单字节，已满时失败 |
| `ringbuffer_putchar_force` | 强制写入单字节，已满时覆盖最旧字节 |
| `ringbuffer_get` | 拷贝并消费数据 |
| `ringbuffer_get_direct` | 返回一段连续内部区间并立即消费（零拷贝） |
| `ringbuffer_peek` | 返回一段连续内部区间但不消费 |
| `ringbuffer_getchar` | 读取并消费单字节 |
| `ringbuffer_data_len` | 当前可读字节数 |
| `ringbuffer_space_len` | 当前剩余可写字节数 |
| `ringbuffer_get_size` | 缓冲区容量（内联函数） |

`get_direct` 与 `peek` 每次只返回一个连续区间；数据发生回绕时需再次调用以获取剩余部分。返回的内部指针可能被后续写入覆盖，调用者应在再次修改缓冲区前完成访问。

## 并发与临界区

游标的读取（快照）与提交通过以下可覆盖的宏保护，默认均为空操作：

```c
#define RINGBUFFER_CRITICAL_DECLARE()
#define RINGBUFFER_CRITICAL_ENTER()
#define RINGBUFFER_CRITICAL_EXIT()
```

需要中断保护的目标平台应在包含 `ringbuffer.h` 前定义这三个宏，并在实现中**保存并恢复进入临界区前的中断状态**（不要以无条件开中断作为退出实现）。

临界区仅保护游标字段，数据拷贝在临界区之外进行：

- 普通 `put` / `get` 支持单生产者 / 单消费者模型
- 多生产者、多消费者、强制覆盖写入、并发 `reset` 需要调用者对整个操作自行串行化

## 构建

作为源码直接加入工程即可。以 C99 与严格告警编译示例：

```powershell
gcc -std=c99 -Wall -Wextra -Werror -pedantic -c ringbuffer.c
```

## 测试

在 Windows 上运行主机端单元测试：

```powershell
powershell -ExecutionPolicy Bypass -File tests/run_tests.ps1
```

测试构建会注入计数型临界区钩子，若出现 enter / exit 调用不平衡将判定失败。用例覆盖非法参数、空 / 满状态、精确边界与回绕读写、截断写入、强制覆盖、超容量强制写入、单字节操作、`get_direct`、`peek`、`reset` 的存储保留以及临界区平衡性。