Update structure.

Author: Jiu-xiao

docs/basic_coding/structure/README.md

@@ -6,4 +6,23 @@ sidebar_position: 2
 
 # 数据结构
 
-本模块汇总了 LibXR 中的数据结构，涵盖队列、栈、链表、红黑树、双缓冲区等，适用于嵌入式系统中的任务调度、数据通信与资源管理。每个数据结构根据用途和平台约束设计，有的具备线程安全性，有的为性能优化采用无锁机制，具体信息请查阅各子页面说明。
+本模块汇总了 LibXR 中用于任务调度、数据通信、资源管理等场景的通用数据结构，设计充分考虑嵌入式系统中的内存限制、并发访问与平台差异，涵盖如下内容：
+
+## 模块特性
+
+- **平台独立**：所有接口均采用平台无关的抽象，支持移植。
+- **内存可控**：多数结构支持外部缓冲或固定容量，避免运行时分配。
+- **线程/中断安全**：部分结构使用互斥锁或无锁算法设计，适配多线程/中断上下文。
+- **结构清晰**：每种结构均封装基础节点、模板节点与核心操作接口，易于扩展。
+
+## 快速导航
+
+- [Queue（队列）](./queue.md)
+- [LockFreeQueue（无锁队列）](./lockfree_queue.md)
+- [Stack（栈）](./stack.md)
+- [List（链表）](./list.md)
+- [LockFreeList（无锁链表）](./lockfree_list.md)
+- [RBTree（红黑树）](./rbt.md)
+- [DoubleBuffer（双缓冲区）](./double_buffer.md)
+
+更多使用方式、性能差异与适用场景，请参考各页面的详细说明及设计思想。

docs/basic_coding/structure/double_buffer.md

@@ -0,0 +1,69 @@
+---
+id: double_buffer
+title: 双缓冲区
+sidebar_position: 7
+---
+
+# 双缓冲区（DoubleBuffer）
+
+`LibXR::DoubleBuffer` 是一个嵌入式场景下的双缓冲数据结构，主要用于 DMA、USB 等高速传输中数据的无缝切换与填充控制。支持主动与备用缓冲的数据管理机制，在性能要求高的数据发送任务中尤为适用。
+
+## 核心特性
+
+- 将一块连续内存分为两个缓冲区。
+- 支持主动缓冲（active）与备用缓冲（pending）之间切换。
+- 提供对两个缓冲区的直接访问与数据填充接口。
+- 支持手动切换与自动有效性检测。
+- 可查询备用区是否准备好、已填充长度。
+
+## 接口概览
+
+### 构造函数
+
+```cpp
+explicit DoubleBuffer(const LibXR::RawData& raw_data);
+```
+
+- 接收一段连续内存，并自动划分为两个缓冲区。
+
+### 数据操作接口
+
+- `uint8_t* ActiveBuffer()`：获取当前使用的缓冲区。
+- `uint8_t* PendingBuffer()`：获取备用缓冲区。
+- `bool FillActive(const uint8_t* data, size_t len)`：写入当前缓冲区。
+- `bool FillPending(const uint8_t* data, size_t len)`：写入备用缓冲区。
+- `void EnablePending()`：手动标记备用区为有效（与 FillActive 配合使用）。
+- `bool HasPending() const`：是否存在准备切换的缓冲区。
+- `void Switch()`：切换 active/pending 缓冲。
+- `size_t PendingLength() const`：获取备用缓冲中的有效数据长度。
+- `size_t Size() const`：每个缓冲区的容量。
+
+## 使用示例
+
+```cpp
+LibXR::RawData mem{malloc(512), 512};
+LibXR::DoubleBuffer buf(mem);
+
+// 第一次写入备用缓冲区
+buf.FillPending(data1, len1);
+if (buf.HasPending()) {
+    buf.Switch();  // 切换为新的 active 缓冲
+}
+
+// 填充当前 active 区用于初始传输
+buf.FillActive(data2, len2);
+buf.EnablePending();  // 标记当前 active 将作为 pending 切换
+```
+
+## 注意事项
+
+- 填充备用区后需调用 `Switch()` 才能激活其数据。
+- 不支持动态分配，内存必须在构造前准备。
+- `FillPending` 不可重入，调用前应确认 pending 状态为 false。
+- `EnablePending()` 与 `FillActive()` 配合实现主动缓存切换。
+
+## 应用场景
+
+- USB CDC / Audio 数据发送
+- DMA 数据流优化
+- 双缓存 ping-pong 通信机制

docs/basic_coding/structure/list.md

@@ -0,0 +1,80 @@
+---
+id: list
+title: 链表
+sidebar_position: 4
+---
+
+# 链表（List）
+
+`LibXR::List` 是一个线程安全的通用链表容器，支持动态添加、删除和遍历节点。每个节点均继承自 `BaseNode`，可以通过模板 `Node<T>` 封装任意数据类型。适用于事件回调、资源管理等灵活数据结构需求。
+
+## 核心特性
+
+- 所有节点继承自 `BaseNode`，统一结构。
+- 提供 `Node<T>` 模板类封装数据。
+- 支持线程安全的添加、删除和遍历。
+- 内部使用循环链表结构，避免空指针问题。
+- 遍历时支持结构大小校验，保障类型安全。
+
+## 类结构
+
+- `BaseNode`：所有节点基类，记录大小与指针。
+- `Node<T>`：模板节点类，封装用户数据。
+- `List`：容器本体，提供 Add / Delete / Foreach 接口。
+
+## 接口说明
+
+### 节点类
+
+```cpp
+class BaseNode {
+  BaseNode* next_;
+  size_t size_;
+};
+
+template <typename T>
+class Node : public BaseNode {
+  T data_;
+};
+```
+
+### 构造与析构
+
+- `List()`：初始化循环链表头。
+- `~List()`：销毁链表并清空所有节点指针。
+
+### 插入与删除
+
+- `void Add(BaseNode& node)`：将节点加入链表头部。
+- `ErrorCode Delete(BaseNode& node)`：从链表中移除指定节点。
+
+### 查询与遍历
+
+- `uint32_t Size()`：获取链表中节点数。
+- `ErrorCode Foreach(Func func)`：遍历所有节点并调用函数。
+  - lambda中返回 `ErrorCode::OK` 时继续遍历，返回 `ErrorCode::ERROR` 时中断遍历。
+
+### Foreach 使用示例
+
+```cpp
+LibXR::List list;
+LibXR::List::Node<int> node1(42);
+list.Add(node1);
+
+list.Foreach<int>([](int& data) {
+  // 访问每个节点数据
+  return LibXR::ErrorCode::OK;
+});
+```
+
+## 注意事项
+
+- 节点由用户申请与释放，`List` 不负责内存管理。
+- 每个节点只能同时存在于一个链表中。
+- `Foreach` 支持结构校验，确保类型匹配。
+
+## 典型应用
+
+- 动态注册的回调列表
+- 插件或模块管理
+- 系统资源追踪

docs/basic_coding/structure/lockfree_list.md

@@ -0,0 +1,78 @@
+---
+id: lockfree_list
+title: 无锁链表
+sidebar_position: 5
+---
+
+# LockFreeList（无锁链表）
+
+`LibXR::LockFreeList` 是一个线程安全的无锁链表容器，基于原子操作实现，适用于高并发场景下的事件注册、回调管理、资源追踪等。
+
+## 核心特性
+
+- 使用 C++11 原子操作实现的单向链表。
+- 所有节点继承自 `BaseNode`，具有统一结构与大小标识。
+- 支持任意数据类型节点：通过模板 `Node<T>` 封装。
+- 支持无锁添加与安全遍历（不可删除）。
+- 遍历时自动进行结构大小检查，确保类型安全。
+- 不涉及动态内存分配，节点由用户管理。
+
+## 类结构
+
+- `BaseNode`：抽象节点类型，提供 `next_` 原子指针和 `size_` 成员。
+- `Node<T>`：模板节点类，内嵌用户数据成员 `data_`。
+- `LockFreeList`：容器本体，提供 `Add` 和 `Foreach` 接口。
+
+## 接口说明
+
+### 添加节点
+
+```cpp
+void Add(BaseNode& node);
+```
+
+- 将新节点插入链表头部（LIFO 顺序），线程安全。
+
+### 遍历节点
+
+```cpp
+template <typename Data, typename Func, SizeLimitMode LimitMode = MORE>
+ErrorCode Foreach(Func func);
+```
+
+- 遍历链表中所有节点，对数据调用回调 `func(Data&)`。
+- 使用 `SizeLimitMode` 模式检查节点数据类型。
+  - lambda中返回 `ErrorCode::OK` 时继续遍历，返回 `ErrorCode::ERROR` 时中断遍历。
+
+### 获取大小
+
+```cpp
+uint32_t Size();
+```
+
+- 返回链表中当前节点个数。
+
+### 使用示例
+
+```cpp
+LibXR::LockFreeList list;
+LibXR::LockFreeList::Node<int> node1(123);
+list.Add(node1);
+
+list.Foreach<int>([](int& val) {
+  // 访问 val
+  return LibXR::ErrorCode::OK;
+});
+```
+
+## 注意事项
+
+- 本链表不支持删除节点，适合“只增不删”的注册场景。
+- 节点生命周期由用户控制，需避免重复添加或早期析构。
+- 遍历过程中不可修改链表结构。
+
+## 典型应用
+
+- 中断/任务中注册的异步回调
+- 模块注册与状态追踪
+- 不可变注册表或只增表结构

docs/basic_coding/structure/lockfree_queue.md

@@ -0,0 +1,77 @@
+---
+id: lockfree_queue
+title: 无锁队列
+sidebar_position: 2
+---
+
+# LockFreeQueue（无锁队列）
+
+`LibXR::LockFreeQueue<T>` 是一个高性能单生产者多消费者（SPMC）无锁队列，适用于实时性要求高、并发访问频繁的嵌入式系统中。
+
+## 类结构与原理
+
+- 使用原子变量 `head_` 和 `tail_` 管理队列索引。
+- 所有操作使用 C++11 原子内存序保证线程安全。
+- 环形缓冲结构支持批量读写，避免频繁中断。
+- 多个消费者可以并发 Pop，生产者唯一。
+
+## 特性概览
+
+| 特性 | 支持 |
+|------|------|
+| 单生产者 | ✅ |
+| 多消费者 | ✅ |
+| 批量操作 | ✅ |
+| Peek/Pop 分离 | ✅ |
+| 动态容量 | ❌（固定容量） |
+| 无锁保证 | ✅（C++11 atomic） |
+
+## 接口函数
+
+### 构造与销毁
+
+- `LockFreeQueue(size_t length)`
+- `~LockFreeQueue()`
+
+### 数据操作
+
+- `ErrorCode Push(const T&)`
+- `ErrorCode Pop(T&)`
+- `ErrorCode Pop()`（丢弃头部元素）
+- `ErrorCode Peek(T&)`
+
+### 批量操作
+
+- `PushBatch(const T* data, size_t size)`
+- `PopBatch(T* data, size_t size)`
+- `PeekBatch(T* data, size_t size)`
+
+### 工具接口
+
+- `Size()`：当前元素数量
+- `EmptySize()`：剩余空间
+- `Reset()`：重置队列为空
+
+## 使用示例
+
+```cpp
+LibXR::LockFreeQueue<int> q(128);
+q.Push(10);
+
+int value;
+if (q.Pop(value) == LibXR::ErrorCode::OK) {
+    // 使用 value
+}
+```
+
+## 注意事项
+
+- 仅适用于 **单生产者** 场景，多生产者需使用外部同步或其他队列方案。
+- 容量固定，构造时需明确所需大小。
+- 数据结构对齐至 cache line，可减少伪共享带来的性能损失。
+
+## 适用场景
+
+- 中断与任务线程间的数据通信
+- 实时日志收集
+- 多线程传感器数据采样