📘 PingPong Buffer 设计文档

一、设计目标

PingPongBuffer（双缓冲区）旨在解决生产者与消费者异步处理数据时的数据一致性与性能问题。适用于实时数据传输、中断采集、多线程通信等场景，具备如下核心目标：

• 保证读写互不干扰
• 支持高吞吐、低延迟
• 能够应对速率不匹配
• 可维护、可调试、可扩展

二、核心设计理念

2.1 双缓冲结构

使用两个固定大小的缓冲区 buffer[0] 和 buffer[1]，通过索引或标志位控制读写指向不同缓冲区。

通过原子操作（或锁）切换这两个缓冲区，实现无锁或低锁竞争的数据交替使用。

2.2 原子切换机制

采用 std::atomic<int> 索引变量配合 memory_order_release/acquire 保证跨线程或中断的数据可见性与一致性。

write_idx.store(new_index, std::memory_order_release);
read_idx.store(old_write_index, std::memory_order_acquire);

2.3 数据完整性控制

• 使用 BeginWrite/EndWrite 和 BeginRead/EndRead 保障帧级数据完整性
• 使用 frame_valid 标志位标识 buffer 是否写满可读
• 支持 frame_id、时间戳等附加信息追踪数据来源及一致性

三、异常与过载处理机制

3.1 生产者快于消费者（overrun）

• 当前写 buffer flip 后，若旧 buffer 尚未消费 → 记录覆盖行为
• 引入 overrun_counter，并提供异常提示接口

if (!buffer_valid[read_idx]) {
    overrun_counter++;
}

3.2 异常帧检测

• frame_id 不连续时提示丢帧
• 时间戳差距过大可认为数据阻塞

四、状态重置与配置变更

支持 reset() 操作，在底层硬件重配置（如分辨率、频率）或系统热切换场景中清空缓冲状态，防止旧数据干扰：

• 清空两个缓冲区
• 重置索引、标志位、计数器
• 提供 flush() 或 sync() 接口供消费者同步状态

五、调试与可测试性设计

5.1 状态查询接口

• 当前读/写 buffer 索引
• 是否有新数据
• 覆盖次数统计
• 帧 ID 与时间戳获取

5.2 测试接口

• 支持注入写数据并读取验证
• 提供 mock 驱动或生产者/消费者回调封装

六、接口定义（C++11 示例）

template <typename T>
class PingPongBuffer {
public:
    bool write(const T& data);      // 写入并 flip
    bool read(T& data);             // 读取 buffer
    void reset();                   // 重置状态
    bool isFresh() const;           // 是否有新数据
    uint64_t getFrameId() const;
    size_t getOverrunCount() const;

private:
    T buffers_[2];
    std::atomic<int> write_idx_{0};
    std::atomic<int> read_idx_{1};
    std::atomic<bool> valid_[2];
    std::atomic<size_t> overrun_counter_{0};
    std::atomic<uint64_t> frame_id_{0};
};

七、实际工程需额外考虑的问题

八、典型应用场景

九、总结与推荐