docs: 重构 API 文档结构并修正源码准确性

- 重组文档目录结构: 每个模块的概述页移动到模块子目录 - 重命名 index.md 为 main.md - 修正所有模块文档中的错误: - math: FromEuler→FromEulerAngles, TransformDirection 包含缩放, Box 是 OBB, Color::ToRGBA 格式 - containers: 新增 operator==/!= 文档, 补充 std::hash DJB 算法细节 - core: 修复 types 链接错误 - debug: LogLevelToString 返回大写, timestamp 是秒, Profiler 空实现标注, Windows API vs ANSI - memory: 修复头文件路径, malloc vs operator new, 新增方法文档 - resources: 修复 Shader/Texture 链接错误 - threading: TaskSystem::Wait 空实现标注, ReadWriteLock 重入描述, LambdaTask 链接 - 验证: fix_links.py 确认 0 个断裂引用
2026-03-19 00:22:30 +08:00
parent d0e16962c8
commit dc850d7739
1012 changed files with 26673 additions and 9222 deletions
--- a/docs/api/threading/task-system/createtaskgroup.md
+++ b/docs/api/threading/task-system/createtaskgroup.md
@@ -0,0 +1,39 @@
+# TaskSystem::CreateTaskGroup
+
+```cpp
+TaskGroup* CreateTaskGroup()
+```
+
+创建一个任务组用于批量管理多个任务。
+
+**参数：** 无
+
+**返回：** `TaskGroup*` - 新创建的任务组指针
+
+**复杂度：** O(1)
+
+**注意：**
+- 任务组必须通过 DestroyTaskGroup 显式销毁。
+- 任务组的所有权归调用者，TaskSystem 不负责销毁。
+
+**示例：**
+
+```cpp
+TaskGroup* group = TaskSystem::Get().CreateTaskGroup();
+
+group->AddTask([]() { LoadTextures(); });
+group->AddTask([]() { LoadModels(); });
+group->AddTask([]() { LoadAudio(); });
+
+group->SetCompleteCallback([]() {
+    printf("All resources loaded!\n");
+});
+
+group->Wait();
+TaskSystem::Get().DestroyTaskGroup(group);
+```
+
+## 相关文档
+
+- [TaskSystem 总览](task-system.md) - 返回类总览
+- [DestroyTaskGroup](destroytaskgroup.md) - 销毁任务组
--- a/docs/api/threading/task-system/destroytaskgroup.md
+++ b/docs/api/threading/task-system/destroytaskgroup.md
@@ -0,0 +1,32 @@
+# TaskSystem::DestroyTaskGroup
+
+```cpp
+void DestroyTaskGroup(TaskGroup* group)
+```
+
+销毁一个任务组并释放其资源。
+
+**参数：**
+- `group` - 要销毁的任务组指针
+
+**返回：** 无
+
+**复杂度：** O(1)
+
+**注意：**
+- 销毁时如果还有未完成的任务，这些任务将被取消。
+- 传入 nullptr 无效果。
+
+**示例：**
+
+```cpp
+TaskGroup* group = TaskSystem::Get().CreateTaskGroup();
+// ... 添加任务 ...
+
+TaskSystem::Get().DestroyTaskGroup(group);
+```
+
+## 相关文档
+
+- [TaskSystem 总览](task-system.md) - 返回类总览
+- [CreateTaskGroup](createtaskgroup.md) - 创建任务组
--- a/docs/api/threading/task-system/get.md
+++ b/docs/api/threading/task-system/get.md
@@ -0,0 +1,26 @@
+# TaskSystem::Get
+
+```cpp
+static TaskSystem& Get()
+```
+
+获取 TaskSystem 单例实例。第一次调用时创建单例。
+
+**参数：** 无
+
+**返回：** `TaskSystem&` - 单例实例的引用
+
+**复杂度：** O(1)
+
+**线程安全：** 线程安全
+
+**示例：**
+
+```cpp
+TaskSystem& system = TaskSystem::Get();
+system.Initialize(config);
+```
+
+## 相关文档
+
+- [TaskSystem 总览](task-system.md) - 返回类总览
--- a/docs/api/threading/task-system/getworkerthreadcount.md
+++ b/docs/api/threading/task-system/getworkerthreadcount.md
@@ -0,0 +1,25 @@
+# TaskSystem::GetWorkerThreadCount
+
+```cpp
+uint32_t GetWorkerThreadCount() const
+```
+
+获取工作线程的数量。
+
+**参数：** 无
+
+**返回：** `uint32_t` - 工作线程数量
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+TaskSystem::Get().Initialize(config);
+uint32_t count = TaskSystem::Get().GetWorkerThreadCount();
+printf("Worker threads: %u\n", count);
+```
+
+## 相关文档
+
+- [TaskSystem 总览](task-system.md) - 返回类总览
--- a/docs/api/threading/task-system/initialize.md
+++ b/docs/api/threading/task-system/initialize.md
@@ -0,0 +1,37 @@
+# TaskSystem::Initialize
+
+```cpp
+void Initialize(const TaskSystemConfig& config)
+```
+
+初始化任务系统，创建工作线程并启动任务调度。
+
+**参数：**
+- `config` - 任务系统配置（参见 TaskSystemConfig）
+
+**返回：** 无
+
+**复杂度：** O(n)，n 为 workerThreadCount
+
+**注意：**
+- 多次调用将先关闭已有系统再重新初始化。
+- 应在主线程中调用，在任何任务提交之前完成初始化。
+
+**示例：**
+
+```cpp
+TaskSystemConfig config;
+config.workerThreadCount = std::thread::hardware_concurrency();
+config.enableTaskProfiling = true;
+config.stealTasks = true;
+config.maxTaskQueueSize = 2048;
+
+TaskSystem::Get().Initialize(config);
+printf("TaskSystem started with %u workers\n", 
+    TaskSystem::Get().GetWorkerThreadCount());
+```
+
+## 相关文档
+
+- [TaskSystem 总览](task-system.md) - 返回类总览
+- [Shutdown](shutdown.md) - 关闭任务系统
--- a/docs/api/threading/task-system/parallelfor.md
+++ b/docs/api/threading/task-system/parallelfor.md
@@ -0,0 +1,46 @@
+# TaskSystem::ParallelFor
+
+```cpp
+template<typename Func>
+void ParallelFor(int32_t start, int32_t end, Func&& func)
+```
+
+并行执行 for 循环。将循环范围划分为多个块，分配给多个工作线程并行处理。
+
+**模板参数：**
+- `Func` - 可调用对象类型，签名为 `void(int32_t)`
+
+**参数：**
+- `start` - 循环起始索引（包含）
+- `end` - 循环结束索引（不包含）
+- `func` - 对每个索引执行的函数
+
+**返回：** 无
+
+**复杂度：** O(n)
+
+**分区策略：**
+- 根据 `std::thread::hardware_concurrency()` 确定线程数。
+- 将范围均分给各线程，每个线程处理连续的块。
+
+**示例：**
+
+```cpp
+// 并行处理 10000 个元素
+std::vector<float> data(10000, 0.0f);
+
+TaskSystem::Get().ParallelFor(0, 10000, [&data](int32_t i) {
+    data[i] = std::sin(i * 0.01f) * std::cos(i * 0.007f);
+});
+
+// 并行矩阵乘法
+TaskSystem::Get().ParallelFor(0, N, [&matrix](int32_t row) {
+    for (int32_t col = 0; col < N; ++col) {
+        matrix[row * N + col] = Compute(row, col);
+    }
+});
+```
+
+## 相关文档
+
+- [TaskSystem 总览](task-system.md) - 返回类总览
--- a/docs/api/threading/task-system/runonmainthread.md
+++ b/docs/api/threading/task-system/runonmainthread.md
@@ -0,0 +1,43 @@
+# TaskSystem::RunOnMainThread
+
+```cpp
+void RunOnMainThread(std::function<void()>&& func)
+```
+
+将任务提交到主线程队列。在主线程中调用 Update 时执行。
+
+**参数：**
+- `func` - 要在主线程执行的函数
+
+**返回：** 无
+
+**复杂度：** O(1)
+
+**使用场景：**
+- 从工作线程回调需要更新 UI 或访问主线程资源。
+- 避免跨线程数据竞争。
+
+**示例：**
+
+```cpp
+// 在工作线程中
+void WorkerThreadCode() {
+    int result = HeavyCompute();
+    
+    // 将结果发送到主线程更新 UI
+    TaskSystem::Get().RunOnMainThread([result]() {
+        UI.UpdateResult(result);
+    });
+}
+
+// 在主线程中
+while (running) {
+    TaskSystem::Get().Update(); // 处理主线程任务
+    RenderFrame();
+}
+```
+
+## 相关文档
+
+- [TaskSystem 总览](task-system.md) - 返回类总览
+- [Update](update.md) - 处理主线程队列
--- a/docs/api/threading/task-system/shutdown.md
+++ b/docs/api/threading/task-system/shutdown.md
@@ -0,0 +1,33 @@
+# TaskSystem::Shutdown
+
+```cpp
+void Shutdown()
+```
+
+关闭任务系统，停止所有工作线程并清理资源。
+
+**参数：** 无
+
+**返回：** 无
+
+**复杂度：** O(n)
+
+**注意：**
+- 调用后应等待所有提交的任务执行完毕，或确保不再需要未完成的任务。
+- 关闭后不可再次使用，必须重新 Initialize。
+
+**示例：**
+
+```cpp
+TaskSystem::Get().Initialize(config);
+
+// ... 使用任务系统 ...
+
+TaskSystem::Get().Shutdown();
+printf("TaskSystem stopped\n");
+```
+
+## 相关文档
+
+- [TaskSystem 总览](task-system.md) - 返回类总览
+- [Initialize](initialize.md) - 初始化任务系统
--- a/docs/api/threading/task-system/submit.md
+++ b/docs/api/threading/task-system/submit.md
@@ -0,0 +1,63 @@
+# TaskSystem::Submit
+
+将任务提交到任务系统调度执行。有两个重载版本。
+
+## 重载 1: 提交 ITask 对象
+
+```cpp
+uint64_t Submit(std::unique_ptr<ITask> task)
+```
+
+提交一个 ITask 对象到任务队列。
+
+**参数：**
+- `task` - 要提交的任务对象
+
+**返回：** `uint64_t` - 分配的任务 ID
+
+**复杂度：** O(log n)
+
+## 重载 2: 提交 lambda 任务
+
+```cpp
+uint64_t Submit(std::function<void()>&& func, TaskPriority priority = TaskPriority::Normal)
+```
+
+将可调用对象包装为任务提交。
+
+**参数：**
+- `func` - 要执行的可调用对象
+- `priority` - 任务优先级，默认 TaskPriority::Normal
+
+**返回：** `uint64_t` - 分配的任务 ID
+
+**复杂度：** O(log n)
+
+**示例：**
+
+```cpp
+// 提交自定义任务
+class MyTask : public ITask {
+public:
+    void Execute() override { printf("MyTask running\n"); }
+};
+uint64_t id1 = TaskSystem::Get().Submit(std::make_unique<MyTask>());
+
+// 提交 lambda
+uint64_t id2 = TaskSystem::Get().Submit([]() {
+    printf("Lambda task\n");
+});
+
+uint64_t id3 = TaskSystem::Get().Submit([]() {
+    HeavyCompute();
+}, TaskPriority::High);
+
+// 等待任务完成
+TaskSystem::Get().Wait(id1);
+TaskSystem::Get().Wait(id2);
+TaskSystem::Get().Wait(id3);
+```
+
+## 相关文档
+
+- [TaskSystem 总览](task-system.md) - 返回类总览
--- a/docs/api/threading/task-system/task-system.md
+++ b/docs/api/threading/task-system/task-system.md
@@ -0,0 +1,111 @@
+# TaskSystem
+
+**命名空间**: `XCEngine::Threading`
+
+**类型**: `class` (singleton)
+
+**头文件**: `XCEngine/Threading/TaskSystem.h`
+
+**描述**: 并行任务调度系统单例，提供工作窃取式任务队列和并行 for 循环。
+
+## 概述
+
+`TaskSystem` 是 XCEngine 的核心并行任务调度系统。它创建多个工作线程，使用优先级队列和工作窃取算法调度任务。它还提供 `ParallelFor` 方法用于数据级并行，以及主线程任务队列。
+
+## 单例访问
+
+| 方法 | 描述 |
+|------|------|
+| [`Get`](get.md) | 获取单例实例 |
+
+## 公共方法
+
+### 生命周期
+
+| 方法 | 描述 |
+|------|------|
+| [`Initialize`](initialize.md) | 初始化任务系统 |
+| [`Shutdown`](shutdown.md) | 关闭任务系统 |
+
+### 任务提交
+
+| 方法 | 描述 |
+|------|------|
+| [`Submit(unique_ptr)`](submit.md) | 提交任务对象 |
+| [`Submit(callback)`](submit.md) | 提交 lambda 任务 |
+
+### 任务组
+
+| 方法 | 描述 |
+|------|------|
+| [`CreateTaskGroup`](createtaskgroup.md) | 创建任务组 |
+| [`DestroyTaskGroup`](destroytaskgroup.md) | 销毁任务组 |
+
+### 等待
+
+| 方法 | 描述 |
+|------|------|
+| [`Wait`](wait.md) | 等待指定任务完成 |
+
+### 信息
+
+| 方法 | 描述 |
+|------|------|
+| [`GetWorkerThreadCount`](getworkerthreadcount.md) | 获取工作线程数量 |
+
+### 并行 for
+
+| 方法 | 描述 |
+|------|------|
+| [`ParallelFor`](parallelfor.md) | 并行执行 for 循环 |
+
+### 主线程
+
+| 方法 | 描述 |
+|------|------|
+| [`RunOnMainThread`](runonmainthread.md) | 将任务提交到主线程执行 |
+| [`Update`](update.md) | 在主线程中处理主线程队列 |
+
+## 使用示例
+
+```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) {
+    process(i);
+});
+
+// 主线程任务
+TaskSystem::Get().RunOnMainThread([]() {
+    // 更新 UI 或其他主线程操作
+});
+
+// 主循环中调用 Update
+while (running) {
+    TaskSystem::Get().Update();  // 处理主线程任务
+}
+
+// 关闭
+TaskSystem::Get().Shutdown();
+```
+
+## 相关文档
+
+- [ITask](../task/task.md) - 任务基类
+- [LambdaTask](../lambdatask/lambdatask.md) - Lambda 任务
+- [TaskGroup](../task-group/task-group.md) - 任务组
+- [TaskSystemConfig](../tasksystemconfig/tasksystemconfig.md) - 配置
+- [../threading/threading.md](../threading.md) - 模块总览
--- a/docs/api/threading/task-system/update.md
+++ b/docs/api/threading/task-system/update.md
@@ -0,0 +1,36 @@
+# TaskSystem::Update
+
+```cpp
+void Update()
+```
+
+在主线程中处理主线程队列。执行所有通过 RunOnMainThread 提交的任务。
+
+**参数：** 无
+
+**返回：** 无
+
+**复杂度：** O(n)，n 为队列中待执行任务数
+
+**使用场景：**
+- 在主循环中调用，确保 RunOnMainThread 提交的任务能够执行。
+- 应在渲染前调用。
+
+**示例：**
+
+```cpp
+// 主循环
+while (application.IsRunning()) {
+    TaskSystem::Get().Update();  // 处理主线程任务
+    
+    // 渲染
+    Renderer.BeginFrame();
+    RenderScene();
+    Renderer.EndFrame();
+}
+```
+
+## 相关文档
+
+- [TaskSystem 总览](task-system.md) - 返回类总览
+- [RunOnMainThread](runonmainthread.md) - 提交主线程任务
--- a/docs/api/threading/task-system/wait.md
+++ b/docs/api/threading/task-system/wait.md
@@ -0,0 +1,37 @@
+# TaskSystem::Wait
+
+```cpp
+void Wait(uint64_t taskId)
+```
+
+**注意：** 此方法当前为空实现，不执行任何操作。
+
+阻塞当前线程，等待指定任务完成（功能暂未实现）。
+
+**参数：**
+- `taskId` - 要等待的任务 ID
+
+**返回：** 无
+
+**复杂度：** N/A（空实现）
+
+**建议：** 建议使用 `TaskGroup::Wait` 代替此方法。
+
+**示例：**
+
+```cpp
+uint64_t id = TaskSystem::Get().Submit([]() {
+    for (int i = 0; i < 1000000; ++i) {
+        Compute(i);
+    }
+});
+
+printf("Waiting for task...\n");
+// 注意：当前实现为空，建议使用 TaskGroup 来等待任务完成
+TaskSystem::Get().Wait(id);
+printf("Task completed\n");
+```
+
+## 相关文档
+
+- [TaskSystem 总览](task-system.md) - 返回类总览