refactor: reorganize docs into plan/ and add skills/

2026-03-18 17:49:22 +08:00
parent fc7c8f6797
commit 9bad996ecf
143 changed files with 13263 additions and 0 deletions
--- a/docs/api/threading/threading-lambdatask.md
+++ b/docs/api/threading/threading-lambdatask.md
@@ -0,0 +1,53 @@
+# LambdaTask
+
+**命名空间**: `XCEngine::Threading`
+
+**类型**: `class` (template)
+
+**描述**: Lambda 任务封装模板类，允许使用 lambda 表达式创建任务，无需继承 ITask。
+
+## 概述
+
+`LambdaTask<Func>` 是一个模板封装类，将任意可调用对象（lambda、函数指针、std::function）包装为 `ITask`。这大大简化了简短任务的创建。
+
+## 模板参数
+
+| 参数 | 描述 |
+|------|------|
+| `Func` | 可调用对象类型 |
+
+## 构造方法
+
+| 方法 | 描述 |
+|------|------|
+| `explicit LambdaTask(Func&& func, TaskPriority priority = TaskPriority::Normal)` | 构造 Lambda 任务 |
+
+## 使用示例
+
+```cpp
+// 使用 lambda 创建任务
+TaskSystem::Get().Submit(
+    std::make_unique<LambdaTask<std::function<void()>>>(
+        []() {
+            printf("Hello from task!\n");
+        },
+        TaskPriority::Normal
+    )
+);
+
+// 或者直接使用 Submit 的便捷重载
+TaskSystem::Get().Submit([]() {
+    printf("Direct lambda task!\n");
+});
+
+// 带依赖的任务
+TaskSystem::Get().Submit<std::function<void()>>([]() {
+    // 任务内容
+}, TaskPriority::High);
+```
+
+## 相关文档
+
+- [ITask](./threading-task.md) - 任务基类
+- [TaskGroup](./threading-task-group.md) - 任务组
+- [TaskSystem](./threading-task-system.md) - 任务系统
--- a/docs/api/threading/threading-mutex.md
+++ b/docs/api/threading/threading-mutex.md
@@ -0,0 +1,51 @@
+# Mutex
+
+**命名空间**: `XCEngine::Threading`
+
+**类型**: `class`
+
+**描述**: 互斥锁封装类，基于 `std::mutex` 实现，提供线程安全的互斥访问。
+
+## 概述
+
+`Mutex` 是对 `std::mutex` 的简单封装，提供了标准的 Lock/Unlock/TryLock 接口。它是 XCEngine 中最基础的同步原语，适用于保护共享数据的访问。
+
+## 公共方法
+
+| 方法 | 描述 |
+|------|------|
+| `void Lock()` | 获取锁（阻塞） |
+| `void Unlock()` | 释放锁 |
+| `bool TryLock()` | 尝试获取锁（非阻塞，成功返回 true） |
+
+## STL 兼容方法
+
+支持 `lock()`、`unlock()`、`try_lock()` 以兼容 STL 的 lockable 概念。
+
+## 使用示例
+
+```cpp
+Threading::Mutex mtx;
+int sharedData = 0;
+
+// 线程安全地修改共享数据
+void SafeIncrement() {
+    mtx.Lock();
+    ++sharedData;
+    mtx.Unlock();
+}
+
+// 或使用 TryLock
+void SafeTryIncrement() {
+    if (mtx.TryLock()) {
+        ++sharedData;
+        mtx.Unlock();
+    }
+}
+```
+
+## 相关文档
+
+- [SpinLock](./threading-spinlock.md) - 自旋锁
+- [ReadWriteLock](./threading-readwritelock.md) - 读写锁
+- [TaskSystem](./threading-task-system.md) - 任务系统
--- a/docs/api/threading/threading-overview.md
+++ b/docs/api/threading/threading-overview.md
@@ -0,0 +1,74 @@
+# Threading 模块概览
+
+**命名空间**: `XCEngine::Threading`
+
+**类型**: `module`
+
+**描述**: XCEngine 的线程和并发模块，提供多线程编程所需的同步原语和任务系统。
+
+## 概述
+
+Threading 模块提供了一套完整的多线程编程工具，包括线程封装、同步原语和并行任务系统。
+
+## 模块内容
+
+### 同步原语
+
+| 组件 | 文件 | 描述 |
+|------|------|------|
+| [Mutex](./threading-mutex.md) | `Mutex.h` | 互斥锁 |
+| [SpinLock](./threading-spinlock.md) | `SpinLock.h` | 自旋锁 |
+| [ReadWriteLock](./threading-readwritelock.md) | `ReadWriteLock.h` | 读写锁 |
+
+### 线程
+
+| 组件 | 文件 | 描述 |
+|------|------|------|
+| [Thread](./threading-thread.md) | `Thread.h` | 线程封装类 |
+
+### 任务系统
+
+| 组件 | 文件 | 描述 |
+|------|------|------|
+| [ITask](./threading-task.md) | `Task.h` | 任务基类 |
+| [LambdaTask](./threading-lambdatask.md) | `LambdaTask.h` | Lambda 任务封装模板 |
+| [TaskGroup](./threading-task-group.md) | `TaskGroup.h` | 任务组 |
+| [TaskSystem](./threading-task-system.md) | `TaskSystem.h` | 并行任务调度系统 |
+| [TaskSystemConfig](./threading-tasksystemconfig.md) | `TaskSystemConfig.h` | 任务系统配置 |
+
+## 同步原语对比
+
+| 原语 | 适用场景 | 特点 |
+|------|----------|------|
+| `Mutex` | 一般互斥 | 可重入性差，开销适中 |
+| `SpinLock` | 短临界区 | 无系统调用，开销低 |
+| `ReadWriteLock` | 读多写少 | 读写分离，提高并发 |
+
+## 任务系统使用示例
+
+```cpp
+#include <XCEngine/Threading/TaskSystem.h>
+
+// 初始化任务系统
+TaskSystemConfig config;
+config.workerThreadCount = 4;
+TaskSystem::Get().Initialize(config);
+
+// 提交并行任务
+TaskSystem::Get().Submit([]() {
+    // 执行工作
+});
+
+// 使用任务组
+TaskGroup* group = TaskSystem::Get().CreateTaskGroup();
+group->AddTask([]() { /* 任务1 */ });
+group->AddTask([]() { /* 任务2 */ });
+group->Wait();
+
+// 销毁任务组
+TaskSystem::Get().DestroyTaskGroup(group);
+```
+
+## 相关文档
+
+- [Memory 模块](../memory/memory-overview.md) - 内存分配器
--- a/docs/api/threading/threading-readwritelock.md
+++ b/docs/api/threading/threading-readwritelock.md
@@ -0,0 +1,53 @@
+# ReadWriteLock
+
+**命名空间**: `XCEngine::Threading`
+
+**类型**: `class`
+
+**描述**: 读写锁实现，支持多个并发读取或单一写入，提高读多写少场景的并发性能。
+
+## 概述
+
+`ReadWriteLock` 实现了一个经典的读写锁。它允许多个线程同时持有读锁，但在有写锁时，所有读锁都必须释放，写锁为独占访问。这对于读操作远多于写操作的共享数据非常有效。
+
+## 公共方法
+
+### 读锁
+
+| 方法 | 描述 |
+|------|------|
+| `void ReadLock()` | 获取读锁（可重入，支持多个并发读者） |
+| `void ReadUnlock()` | 释放读锁 |
+
+### 写锁
+
+| 方法 | 描述 |
+|------|------|
+| `void WriteLock()` | 获取写锁（独占，阻塞所有读者和写者） |
+| `void WriteUnlock()` | 释放写锁 |
+
+## 使用示例
+
+```cpp
+Threading::ReadWriteLock rwLock;
+Containers::HashMap<String, int> sharedMap;
+
+// 读操作（多个线程可同时读）
+void ReadData(const String& key) {
+    rwLock.ReadLock();
+    int* value = sharedMap.Find(key);
+    rwLock.ReadUnlock();
+}
+
+// 写操作（独占）
+void WriteData(const String& key, int value) {
+    rwLock.WriteLock();
+    sharedMap.Insert(key, value);
+    rwLock.WriteUnlock();
+}
+```
+
+## 相关文档
+
+- [Mutex](./threading-mutex.md) - 互斥锁
+- [SpinLock](./threading-spinlock.md) - 自旋锁
--- a/docs/api/threading/threading-spinlock.md
+++ b/docs/api/threading/threading-spinlock.md
@@ -0,0 +1,46 @@
+# SpinLock
+
+**命名空间**: `XCEngine::Threading`
+
+**类型**: `class`
+
+**描述**: 自旋锁封装类，使用原子操作实现，适用于保护极短的临界区。
+
+## 概述
+
+`SpinLock` 是一个轻量级的自旋锁实现，使用 `std::atomic_flag` 的 test-and-set 操作。它在获取锁失败时不断轮询，不会导致线程切换，非常适合保护非常短的临界区（如简单的计数器递增）。
+
+## 公共方法
+
+| 方法 | 描述 |
+|------|------|
+| `void Lock()` | 获取锁（忙等待） |
+| `void Unlock()` | 释放锁 |
+| `bool TryLock()` | 尝试获取锁（非阻塞） |
+
+## 使用示例
+
+```cpp
+Threading::SpinLock spinLock;
+int counter = 0;
+
+// 保护极短的临界区
+void FastIncrement() {
+    spinLock.Lock();
+    ++counter;  // 单一操作，无需切换到内核
+    spinLock.Unlock();
+}
+
+// TryLock 用法
+void SafeIncrement() {
+    if (spinLock.TryLock()) {
+        ++counter;
+        spinLock.Unlock();
+    }
+}
+```
+
+## 相关文档
+
+- [Mutex](./threading-mutex.md) - 互斥锁
+- [ReadWriteLock](./threading-readwritelock.md) - 读写锁
--- a/docs/api/threading/threading-task-group.md
+++ b/docs/api/threading/threading-task-group.md
@@ -0,0 +1,86 @@
+# TaskGroup
+
+**命名空间**: `XCEngine::Threading`
+
+**类型**: `class`
+
+**描述**: 任务组管理类，用于组织多个任务并支持批量等待、进度跟踪和依赖管理。
+
+## 概述
+
+`TaskGroup` 提供了一种批量管理任务的机制。它允许添加多个任务、设置任务依赖关系、等待所有任务完成，并提供进度回调功能。
+
+## 公共方法
+
+### 构造/析构
+
+| 方法 | 描述 |
+|------|------|
+| `TaskGroup()` | 默认构造函数 |
+| `~TaskGroup()` | 析构函数 |
+
+### 任务添加
+
+| 方法 | 描述 |
+|------|------|
+| `uint64_t AddTask(std::unique_ptr<ITask> task)` | 添加任务对象 |
+| `uint64_t AddTask(Callback&& func, TaskPriority priority = TaskPriority::Normal)` | 添加 lambda 任务 |
+
+### 依赖管理
+
+| 方法 | 描述 |
+|------|------|
+| `void AddDependency(uint64_t taskId, uint64_t dependsOn)` | 添加任务依赖关系 |
+
+### 等待
+
+| 方法 | 描述 |
+|------|------|
+| `void Wait()` | 阻塞等待所有任务完成 |
+| `bool WaitFor(std::chrono::milliseconds timeout)` | 超时等待 |
+
+### 回调和状态
+
+| 方法 | 描述 |
+|------|------|
+| `void SetCompleteCallback(Callback&& callback)` | 设置完成回调 |
+| `bool IsComplete() const` | 检查所有任务是否完成 |
+| `float GetProgress() const` | 获取完成进度（0.0f ~ 1.0f） |
+| `void Cancel()` | 取消所有任务 |
+
+## 使用示例
+
+```cpp
+TaskGroup* group = TaskSystem::Get().CreateTaskGroup();
+
+// 添加多个任务
+uint64_t task1 = group->AddTask([]() { /* 任务1 */ });
+uint64_t task2 = group->AddTask([]() { /* 任务2 */ });
+
+// 设置依赖：task3 等待 task1 完成
+uint64_t task3 = group->AddTask([]() { /* 任务3 */ });
+group->AddDependency(task3, task1);
+
+// 设置完成回调
+group->SetCompleteCallback([]() {
+    printf("All tasks completed!\n");
+});
+
+// 等待完成
+group->Wait();
+
+// 或者超时等待
+if (group->WaitFor(std::chrono::seconds(5))) {
+    printf("Completed within 5 seconds\n");
+} else {
+    printf("Timeout, some tasks did not complete\n");
+}
+
+// 销毁
+TaskSystem::Get().DestroyTaskGroup(group);
+```
+
+## 相关文档
+
+- [ITask](./threading-task.md) - 任务基类
+- [TaskSystem](./threading-task-system.md) - 任务系统
--- a/docs/api/threading/threading-task-system.md
+++ b/docs/api/threading/threading-task-system.md
@@ -0,0 +1,110 @@
+# TaskSystem
+
+**命名空间**: `XCEngine::Threading`
+
+**类型**: `class` (singleton)
+
+**描述**: 并行任务调度系统单例，提供工作窃取式任务队列和并行 for 循环。
+
+## 概述
+
+`TaskSystem` 是 XCEngine 的核心并行任务调度系统。它创建多个工作线程，使用优先级队列和工作窃取算法调度任务。它还提供 `ParallelFor` 方法用于数据级并行，以及主线程任务队列。
+
+## 单例访问
+
+| 方法 | 描述 |
+|------|------|
+| `static TaskSystem& Get()` | 获取单例实例 |
+
+## 公共方法
+
+### 生命周期
+
+| 方法 | 描述 |
+|------|------|
+| `void Initialize(const TaskSystemConfig& config)` | 初始化任务系统 |
+| `void Shutdown()` | 关闭任务系统 |
+
+### 任务提交
+
+| 方法 | 描述 |
+|------|------|
+| `uint64_t Submit(std::unique_ptr<ITask> task)` | 提交任务对象 |
+| `uint64_t Submit(std::function<void()>&& func, TaskPriority priority = TaskPriority::Normal)` | 提交 lambda 任务 |
+
+### 任务组
+
+| 方法 | 描述 |
+|------|------|
+| `TaskGroup* CreateTaskGroup()` | 创建任务组 |
+| `void DestroyTaskGroup(TaskGroup* group)` | 销毁任务组 |
+
+### 等待
+
+| 方法 | 描述 |
+|------|------|
+| `void Wait(uint64_t taskId)` | 等待指定任务完成 |
+
+### 信息
+
+| 方法 | 描述 |
+|------|------|
+| `uint32_t GetWorkerThreadCount() const` | 获取工作线程数量 |
+
+### 并行 for
+
+| 方法 | 描述 |
+|------|------|
+| `template<typename Func> void ParallelFor(int32_t start, int32_t end, Func&& func)` | 并行执行 for 循环 |
+
+### 主线程
+
+| 方法 | 描述 |
+|------|------|
+| `void RunOnMainThread(std::function<void()>&& func)` | 将任务提交到主线程执行 |
+| `void Update()` | 在主线程中处理主线程队列 |
+
+## 使用示例
+
+```cpp
+// 初始化（4 个工作线程）
+TaskSystemConfig config;
+config.workerThreadCount = 4;
+TaskSystem::Get().Initialize(config);
+
+// 提交任务
+TaskSystem::Get().Submit([]() {
+    printf("Task 1 running\n");
+});
+
+TaskSystem::Get().Submit([]() {
+    printf("Task 2 running\n");
+}, TaskPriority::High);
+
+// 并行 for
+TaskSystem::Get().ParallelFor(0, 1000, [](int32_t i) {
+    // 每个 i 独立处理
+    process(i);
+});
+
+// 主线程任务
+TaskSystem::Get().RunOnMainThread([]() {
+    // 更新 UI 或其他主线程操作
+});
+
+// 主循环中调用 Update
+while (running) {
+    TaskSystem::Get().Update();  // 处理主线程任务
+    // 其他渲染...
+}
+
+// 关闭
+TaskSystem::Get().Shutdown();
+```
+
+## 相关文档
+
+- [ITask](./threading-task.md) - 任务基类
+- [LambdaTask](./threading-lambdatask.md) - Lambda 任务
+- [TaskGroup](./threading-task-group.md) - 任务组
+- [TaskSystemConfig](./threading-tasksystemconfig.md) - 配置
--- a/docs/api/threading/threading-task.md
+++ b/docs/api/threading/threading-task.md
@@ -0,0 +1,96 @@
+# ITask / Task
+
+**命名空间**: `XCEngine::Threading`
+
+**类型**: `class` (abstract) / `enum`
+
+**描述**: 任务基类抽象接口和任务状态/优先级枚举定义。
+
+## 概述
+
+`ITask` 是任务系统的核心抽象基类。用户需要继承此类并实现 `Execute()` 方法来定义具体的任务逻辑。任务系统通过引用计数自动管理任务生命周期。
+
+## TaskPriority 枚举
+
+任务优先级枚举（数值越小优先级越高）。
+
+| 值 | 描述 |
+|----|------|
+| `Critical` | 关键优先级（0） |
+| `High` | 高优先级（1） |
+| `Normal` | 普通优先级（2） |
+| `Low` | 低优先级（3） |
+| `Idle` | 空闲优先级（4） |
+
+## TaskStatus 枚举
+
+任务状态枚举。
+
+| 值 | 描述 |
+|----|------|
+| `Pending` | 等待中 |
+| `Scheduled` | 已调度 |
+| `Running` | 运行中 |
+| `Completed` | 已完成 |
+| `Failed` | 失败 |
+| `Canceled` | 已取消 |
+
+## ITask 公共方法
+
+### 生命周期
+
+| 方法 | 描述 |
+|------|------|
+| `virtual void Execute() = 0` | 任务执行逻辑（纯虚） |
+| `virtual void OnComplete() {}` | 任务完成回调（可重写） |
+| `virtual void OnCancel() {}` | 任务取消回调（可重写） |
+
+### 属性
+
+| 方法 | 描述 |
+|------|------|
+| `TaskPriority GetPriority() const` | 获取优先级 |
+| `TaskStatus GetStatus() const` | 获取状态 |
+| `uint64_t GetId() const` | 获取任务 ID |
+| `void SetId(uint64_t id)` | 设置任务 ID |
+| `void SetPriority(TaskPriority priority)` | 设置优先级 |
+| `void SetStatus(TaskStatus status)` | 设置状态 |
+
+### 引用计数
+
+| 方法 | 描述 |
+|------|------|
+| `void AddRef()` | 增加引用计数 |
+| `void Release()` | 减少引用计数（自动 delete 引用归零时） |
+
+## 使用示例
+
+```cpp
+class MyTask : public ITask {
+public:
+    explicit MyTask(int data) : m_data(data) {}
+    
+    void Execute() override {
+        // 执行任务逻辑
+        printf("Task executed with data: %d\n", m_data);
+    }
+    
+    void OnComplete() override {
+        // 任务完成后的清理
+    }
+    
+private:
+    int m_data;
+};
+
+// 使用
+auto task = new MyTask(42);
+task->SetPriority(TaskPriority::High);
+TaskSystem::Get().Submit(std::unique_ptr<ITask>(task));
+```
+
+## 相关文档
+
+- [LambdaTask](./threading-lambdatask.md) - Lambda 任务封装
+- [TaskGroup](./threading-task-group.md) - 任务组
+- [TaskSystem](./threading-task-system.md) - 任务系统
--- a/docs/api/threading/threading-tasksystemconfig.md
+++ b/docs/api/threading/threading-tasksystemconfig.md
@@ -0,0 +1,33 @@
+# TaskSystemConfig
+
+**命名空间**: `XCEngine::Threading`
+
+**类型**: `struct`
+
+**描述**: 任务系统配置结构体。
+
+## 结构体成员
+
+| 成员 | 类型 | 描述 | 默认值 |
+|------|------|------|--------|
+| `workerThreadCount` | `uint32_t` | 工作线程数量（0=自动检测） | 0 |
+| `enableTaskProfiling` | `bool` | 启用任务性能分析 | true |
+| `stealTasks` | `bool` | 启用工作窃取 | true |
+| `maxTaskQueueSize` | `uint32_t` | 最大任务队列大小 | 1024 |
+| `threadStackSize` | `uint32_t` | 线程栈大小（0=默认） | 0 |
+
+## 使用示例
+
+```cpp
+TaskSystemConfig config;
+config.workerThreadCount = std::thread::hardware_concurrency();
+config.enableTaskProfiling = true;
+config.stealTasks = true;
+config.maxTaskQueueSize = 2048;
+
+TaskSystem::Get().Initialize(config);
+```
+
+## 相关文档
+
+- [TaskSystem](./threading-task-system.md) - 任务系统
--- a/docs/api/threading/threading-thread.md
+++ b/docs/api/threading/threading-thread.md
@@ -0,0 +1,77 @@
+# Thread
+
+**命名空间**: `XCEngine::Threading`
+
+**类型**: `class`
+
+**头文件**: `XCEngine/Threading/Thread.h`
+
+**描述**: 线程封装类，提供跨平台线程创建和管理功能。
+
+## 概述
+
+`Thread` 类封装了 `std::thread`，提供统一的线程管理接口，包括启动、加入、分离等操作。
+
+## 公共类型
+
+| 类型 | 描述 |
+|------|------|
+| `using Id = uint64_t` | 线程唯一标识符类型 |
+
+## 公共方法
+
+### 生命周期
+
+| 方法 | 描述 |
+|------|------|
+| `Thread()` | 默认构造函数 |
+| `~Thread()` | 析构函数 |
+
+### 线程控制
+
+| 方法 | 描述 |
+|------|------|
+| `template<typename Func> void Start(Func&& func, const Containers::String& name = "Thread")` | 启动线程，执行传入的函数 |
+| `void Join()` | 等待线程结束 |
+| `void Detach()` | 分离线程，使其独立运行 |
+
+### 属性访问
+
+| 方法 | 描述 |
+|------|------|
+| `Id GetId() const` | 获取线程 ID |
+| `const Containers::String& GetName() const` | 获取线程名称 |
+
+### 静态方法
+
+| 方法 | 描述 |
+|------|------|
+| `static Id GetCurrentId()` | 获取当前线程 ID |
+| `static void Sleep(uint32_t milliseconds)` | 线程休眠指定毫秒数 |
+| `static void Yield()` | 让出当前线程的时间片 |
+
+## 使用示例
+
+```cpp
+#include <XCEngine/Threading/Thread.h>
+
+// 创建并启动线程
+Thread thread;
+thread.Start([]() {
+    // 线程工作
+    printf("Worker thread running\n");
+}, "WorkerThread");
+
+// 等待线程结束
+thread.Join();
+
+// 使用静态方法
+Thread::Sleep(1000); // 休眠1秒
+Thread::Yield();      // 让出时间片
+auto currentId = Thread::GetCurrentId();
+```
+
+## 相关文档
+
+- [Mutex](./threading-mutex.md) - 互斥锁
+- [TaskSystem](./threading-task-system.md) - 任务调度系统