用户态缓存：环形缓冲区（Ring Buffer）

#ifndef _ringbuffer_h
#define _ringbuffer_h

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
// #include <limits.h>  // for uint_max
#include <stdint.h>
#include <unistd.h>

typedef struct ringbuffer_s buffer_t;

buffer_t * buffer_new(uint32_t sz);

uint32_t buffer_len(buffer_t *r);

void buffer_free(buffer_t *r);

int buffer_add(buffer_t *r, const void *data, uint32_t sz);

int buffer_remove(buffer_t *r, void *data, uint32_t sz);

int buffer_drain(buffer_t *r, uint32_t sz);

int buffer_search(buffer_t *r, const char* sep, const int seplen);

uint8_t * buffer_write_atmost(buffer_t *r);

#endif

1.1 头文件保护符

#ifndef _ringbuffer_h
#define _ringbuffer_h
...
#endif

作用：防止头文件被多次包含，避免重复定义错误。

1.2 包含必要的标准库

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
// #include <limits.h>  // for uint_max
#include <stdint.h>
#include <unistd.h>

标准库：提供了内存管理（malloc、free）、字符串操作（memcpy）、固定宽度整数类型（uint32_t、uint8_t）等功能。

1.3 类型定义

typedef struct ringbuffer_s buffer_t;

作用：为 struct ringbuffer_s 定义一个别名 buffer_t，简化后续代码的书写。

2. 环形缓冲区结构体

struct ringbuffer_s {
    uint32_t size;
    uint32_t tail;
    uint32_t head;
    uint8_t * buf;
};

2.1 结构体成员解释

size (uint32_t)：缓冲区的总大小，以字节为单位。通常为2的幂次方，便于使用位运算实现环形效果。
tail (uint32_t)：指向缓冲区的写入位置。每次添加数据时，tail 会递增。
head (uint32_t)：指向缓冲区的读取位置。每次移除数据时，head 会递增。
buf (uint8_t *)：指向实际数据存储区的指针。数据以字节形式存储。

3. 辅助宏与内联函数

#define min(lth, rth) ((lth)<(rth)?(lth):(rth))

static inline int is_power_of_two(uint32_t num) {
    if (num < 2) return 0;
    return (num & (num - 1)) == 0;
}

static inline uint32_t roundup_power_of_two(uint32_t num) {
    if (num == 0) return 2;
    int i = 0;
    for (; num != 0; i++)
        num >>= 1;
    return 1U << i;
}

3.1 `min` 宏

#define min(lth, rth) ((lth)<(rth)?(lth):(rth))

作用：返回两个值中的较小者，简化代码中的条件判断。

3.2 `is_power_of_two` 内联函数

static inline int is_power_of_two(uint32_t num) {
    if (num < 2) return 0;
    return (num & (num - 1)) == 0;
}

作用：判断一个数是否为2的幂次方。
原理：2的幂次方数在二进制中只有一个1，其减1后所有位都会变为1，按位与结果为0。

3.3 `roundup_power_of_two` 内联函数

static inline uint32_t roundup_power_of_two(uint32_t num) {
    if (num == 0) return 2;
    int i = 0;
    for (; num != 0; i++)
        num >>= 1;
    return 1U << i;
}

作用：将一个数向上舍入到最近的2的幂次方。
实现：通过不断右移操作，计算出需要的位数，然后使用位移生成对应的2的幂次方数。

4. 环形缓冲区的基本操作

4.1 创建新缓冲区

buffer_t * buffer_new(uint32_t sz) {
    if (!is_power_of_two(sz)) sz = roundup_power_of_two(sz);
    buffer_t * buf = (buffer_t *)malloc(sizeof(buffer_t) + sz);
    if (!buf) {
        return NULL;
    }
    buf->size = sz;
    buf->head = buf->tail = 0;
    buf->buf = (uint8_t *)(buf + 1);
    return buf;
}