docs: update memory and threading API docs

docs/api/threading/lambdatask/execute.md

@@ -0,0 +1,40 @@
+# LambdaTask::Execute
+
+```cpp
+void Execute() override
+```
+
+执行封装的可调用对象。调用时执行构造时传入的 lambda 或可调用函数。
+
+**参数：** 无
+
+**返回：** 无
+
+**注意：**
+- 如果封装的可调用对象抛出异常，异常会向上传播到 TaskSystem。
+- 任务系统的工作线程不会捕获此类异常。
+
+**示例：**
+
+```cpp
+// 创建并提交 LambdaTask
+TaskSystem::Get().Submit(
+    std::make_unique<LambdaTask<std::function<void()>>>(
+        []() {
+            printf("Task executed!\n");
+        },
+        TaskPriority::Normal
+    )
+);
+
+// 使用便捷重载直接提交
+TaskSystem::Get().Submit([]() {
+    int result = ComputeHeavyWork();
+    printf("Result: %d\n", result);
+}, TaskPriority::High);
+```
+
+## 相关文档
+
+- [LambdaTask 总览](lambdatask.md) - 返回类总览
+- [ITask::Execute](../task/execute.md) - 基类方法文档

docs/api/threading/lambdatask/lambdatask.md

@@ -28,7 +28,7 @@
 
 | 方法 | 描述 |
 |------|------|
-| `Execute()` | 执行封装的可调用对象（继承自 ITask，可重写） |
+| [`Execute()`](execute.md) | 执行封装的可调用对象（继承自 ITask，纯虚方法重写） |
 
 ## 使用示例
 

docs/api/threading/mutex/lock.md

@@ -19,7 +19,7 @@ void Lock()
 **示例：**
 
 ```cpp
-Threading::Mutex mtx;
+XCEngine::Threading::Mutex mtx;
 int counter = 0;
 
 void Increment() {

docs/api/threading/mutex/lock_const.md

@@ -0,0 +1,43 @@
+# Mutex::lock
+
+```cpp
+void lock() const;
+```
+
+获取互斥锁（const 版本）。如果锁已被其他线程持有，则阻塞当前线程直到锁可用。
+
+该方法是 `std::lockable` 接口的实现，可与 `std::lock_guard`、`std::unique_lock` 等 RAII 工具配合使用。
+
+**参数：** 无
+
+**返回：** 无
+
+**线程安全：** ✅
+
+**复杂度：** 平均 O(1)，最坏情况 O(n)，n 为竞争线程数
+
+**示例：**
+
+```cpp
+#include "XCEngine/Threading/Mutex.h"
+#include <mutex>
+
+XCEngine::XCEngine::Threading::Mutex mtx;
+int counter = 0;
+
+void Increment() {
+    mtx.lock();
+    ++counter;
+    mtx.unlock();
+}
+
+// 使用 RAII 自动管理锁
+void SafeIncrement() {
+    std::lock_guard<XCEngine::Threading::Mutex> guard(mtx);
+    ++counter;
+}
+```
+
+## 相关文档
+
+- [Mutex 总览](mutex.md) - 返回类总览

docs/api/threading/mutex/mutex.md

@@ -6,43 +6,52 @@
 
 **头文件**: `XCEngine/Threading/Mutex.h`
 
-**描述**: 互斥锁封装类，基于 `std::mutex` 实现，提供线程安全的互斥访问。
+**描述**: 互斥锁，封装 std::mutex 提供线程同步
 
 ## 概述
 
-`Mutex` 是对 `std::mutex` 的简单封装，提供了标准的 Lock/Unlock/TryLock 接口。它是 XCEngine 中最基础的同步原语，适用于保护共享数据的访问。
+Mutex 类是对 std::mutex 的封装，提供线程安全的互斥访问机制。该类确保同一时刻只有一个线程可以访问受保护的资源，防止数据竞争和竞态条件。
+
+该类提供两套接口：
+- `Lock/Unlock/TryLock`：XCEngine 风格接口
+- `lock/unlock/try_lock`：STL 兼容接口（const 成员函数）
 
 ## 公共方法
 
 | 方法 | 描述 |
 |------|------|
-| [`Lock`](lock.md) | 获取锁（阻塞） |
-| [`Unlock`](unlock.md) | 释放锁 |
-| [`TryLock`](trylock.md) | 尝试获取锁（非阻塞，成功返回 true） |
-
-## STL 兼容方法
-
-支持 `lock()`, `unlock()`, `try_lock()` 以兼容 STL 的 lockable 概念。**注意**：这些方法为 `const` 成员函数。
+| [`Lock`](lock.md) | 获取互斥锁（非 const） |
+| [`Unlock`](unlock.md) | 释放互斥锁（非 const） |
+| [`TryLock`](trylock.md) | 尝试获取互斥锁（非 const） |
+| [`lock`](lock_const.md) | 获取互斥锁（const，STL 兼容） |
+| [`unlock`](unlock_const.md) | 释放互斥锁（const，STL 兼容） |
+| [`try_lock`](try_lock_const.md) | 尝试获取互斥锁（const，STL 兼容） |
 
 ## 使用示例
 
 ```cpp
-Threading::Mutex mtx;
+#include "XCEngine/Threading/Mutex.h"
+#include <thread>
+#include <iostream>
+
+XCEngine::Threading::Mutex mutex;
 int sharedData = 0;
 
-// 线程安全地修改共享数据
-void SafeIncrement() {
-    mtx.Lock();
+void increment() {
+    mutex.lock();
     ++sharedData;
-    mtx.Unlock();
+    mutex.unlock();
 }
 
-// 或使用 TryLock
-void SafeTryIncrement() {
-    if (mtx.TryLock()) {
-        ++sharedData;
-        mtx.Unlock();
-    }
+int main() {
+    std::thread t1(increment);
+    std::thread t2(increment);
+
+    t1.join();
+    t2.join();
+
+    std::cout << "sharedData = " << sharedData << std::endl;
+    return 0;
 }
 ```
 

docs/api/threading/mutex/try_lock.md

@@ -0,0 +1,36 @@
+# Mutex::try_lock
+
+```cpp
+bool try_lock() const;
+```
+
+尝试获取互斥锁，非阻塞。如果锁不可用，调用线程不会阻塞，而是立即返回。
+
+**参数：** 无
+
+**返回：** `bool` - 如果成功获取锁返回 `true`，否则返回 `false`
+
+**线程安全：** ✅
+
+**示例：**
+
+```cpp
+#include "XCEngine/Threading/Mutex.h"
+#include <iostream>
+
+XCEngine::Threading::Mutex mutex;
+
+void tryOperation() {
+    if (mutex.try_lock()) {
+        // 获取锁成功
+        mutex.unlock();
+    } else {
+        // 锁已被其他线程持有
+        std::cout << "Lock not available" << std::endl;
+    }
+}
+```
+
+## 相关文档
+
+- [Mutex 类总览](mutex.md) - 返回类总览

docs/api/threading/mutex/try_lock_const.md

@@ -0,0 +1,41 @@
+# Mutex::try_lock
+
+```cpp
+bool try_lock() const;
+```
+
+尝试获取互斥锁（非阻塞，const 版本）。如果锁可用则立即获取并返回 `true`，否则立即返回 `false` 而不阻塞。
+
+该方法是 `std::lockable` 接口的实现。
+
+**参数：** 无
+
+**返回：** `bool` - 获取成功返回 `true`，锁不可用返回 `false`
+
+**线程安全：** ✅
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include "XCEngine/Threading/Mutex.h"
+#include <iostream>
+
+XCEngine::XCEngine::Threading::Mutex mtx;
+volatile bool updated = false;
+
+void TryUpdate() {
+    if (mtx.try_lock()) {
+        updated = true;
+        mtx.unlock();
+        std::cout << "Update succeeded" << std::endl;
+    } else {
+        std::cout << "Update skipped (lock held)" << std::endl;
+    }
+}
+```
+
+## 相关文档
+
+- [Mutex 总览](mutex.md) - 返回类总览

docs/api/threading/mutex/trylock.md

@@ -17,7 +17,7 @@ bool TryLock()
 **示例：**
 
 ```cpp
-Threading::Mutex mtx;
+XCEngine::Threading::Mutex mtx;
 volatile bool updated = false;
 
 void TryUpdate() {

docs/api/threading/mutex/unlock.md

@@ -17,7 +17,7 @@ void Unlock()
 **示例：**
 
 ```cpp
-Threading::Mutex mtx;
+XCEngine::Threading::Mutex mtx;
 std::vector<int> data;
 
 void SafePush(int value) {

docs/api/threading/mutex/unlock_const.md

@@ -0,0 +1,34 @@
+# Mutex::unlock
+
+```cpp
+void unlock() const;
+```
+
+释放互斥锁（const 版本），允许其他等待中的线程获取该锁。
+
+**参数：** 无
+
+**返回：** 无
+
+**线程安全：** ✅
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include "XCEngine/Threading/Mutex.h"
+
+XCEngine::XCEngine::Threading::Mutex mtx;
+std::vector<int> data;
+
+void SafePush(int value) {
+    mtx.lock();
+    data.push_back(value);
+    mtx.unlock();
+}
+```
+
+## 相关文档
+
+- [Mutex 总览](mutex.md) - 返回类总览

docs/api/threading/readwritelock/constructor.md

@@ -0,0 +1,35 @@
+# ReadWriteLock::ReadWriteLock
+
+```cpp
+ReadWriteLock() = default;
+```
+
+默认构造函数。构造一个未锁定的读写锁。
+
+**参数：** 无
+
+**返回：** 无
+
+**线程安全：** ✅
+
+**复杂度：** O(1)
+
+**注意：**
+- 构造后的锁处于未锁定状态。
+- 多个线程可以同时获取读锁。
+
+**示例：**
+
+```cpp
+#include "XCEngine/Threading/ReadWriteLock.h"
+
+XCEngine::Threading::ReadWriteLock rwLock;
+```
+
+## 相关文档
+
+- [`ReadWriteLock`](readwritelock.md) - 返回类总览
+- [`ReadLock`](readlock.md) - 获取读锁
+- [`ReadUnlock`](readunlock.md) - 释放读锁
+- [`WriteLock`](writelock.md) - 获取写锁
+- [`WriteUnlock`](writeunlock.md) - 释放写锁

docs/api/threading/readwritelock/destructor.md

@@ -0,0 +1,40 @@
+# ReadWriteLock::~ReadWriteLock
+
+```cpp
+~ReadWriteLock() = default;
+```
+
+默认析构函数。销毁读写锁。
+
+**参数：** 无
+
+**返回：** 无
+
+**线程安全：** ⚠️
+
+**复杂度：** O(1)
+
+**注意：**
+- 析构前必须确保锁处于未锁定状态。
+- 如果在持有锁的状态下销毁行为未定义。
+
+**示例：**
+
+```cpp
+#include "XCEngine/Threading/ReadWriteLock.h"
+
+{
+    XCEngine::Threading::ReadWriteLock rwLock;
+    rwLock.ReadLock();
+    // ... 使用共享数据 ...
+    rwLock.ReadUnlock();
+} // rwLock 在这里销毁
+```
+
+## 相关文档
+
+- [`ReadWriteLock`](readwritelock.md) - 返回类总览
+- [`ReadLock`](readlock.md) - 获取读锁
+- [`ReadUnlock`](readunlock.md) - 释放读锁
+- [`WriteLock`](writelock.md) - 获取写锁
+- [`WriteUnlock`](writeunlock.md) - 释放写锁

docs/api/threading/readwritelock/readlock.md

@@ -10,17 +10,21 @@ void ReadLock()
 
 **返回：** 无
 
+**线程安全：** ✅
+
 **复杂度：** 平均 O(1)
 
 **注意：**
 - 多个读者可以同时持有读锁。
 - 写锁具有优先权——正在等待的写者会阻塞新的读者，防止写者饥饿。
-- 读锁不可重入，同一线程不可嵌套持有读锁（会导致死锁）。
+- 读锁不可重入，同一线程不可嵌套持有读锁。
 
 **示例：**
 
 ```cpp
-ReadWriteLock rwLock;
+#include "XCEngine/Threading/ReadWriteLock.h"
+
+XCEngine::Threading::ReadWriteLock rwLock;
 int sharedValue = 0;
 
 int ReadValue() {
@@ -33,4 +37,5 @@ int ReadValue() {
 
 ## 相关文档
 
-- [ReadWriteLock 总览](readwritelock.md) - 返回类总览
+- [`ReadWriteLock`](readwritelock.md) - 返回类总览
+- [`ReadUnlock`](readunlock.md) - 释放读锁

docs/api/threading/readwritelock/readunlock.md

@@ -10,6 +10,8 @@ void ReadUnlock()
 
 **返回：** 无
 
+**线程安全：** ✅
+
 **复杂度：** O(1)
 
 **注意：** 必须与 ReadLock 配对使用，且在持有读锁的线程中调用。
@@ -17,7 +19,9 @@ void ReadUnlock()
 **示例：**
 
 ```cpp
-ReadWriteLock rwLock;
+#include "XCEngine/Threading/ReadWriteLock.h"
+
+XCEngine::Threading::ReadWriteLock rwLock;
 float sharedData = 0.0f;
 
 float GetData() {
@@ -30,4 +34,5 @@ float GetData() {
 
 ## 相关文档
 
-- [ReadWriteLock 总览](readwritelock.md) - 返回类总览
+- [`ReadWriteLock`](readwritelock.md) - 返回类总览
+- [`ReadLock`](readlock.md) - 获取读锁

docs/api/threading/readwritelock/readwritelock.md

@@ -6,52 +6,86 @@
 
 **头文件**: `XCEngine/Threading/ReadWriteLock.h`
 
-**描述**: 读写锁实现，支持多个并发读取或单一写入，提高读多写少场景的并发性能。
+**描述**: 读写锁，允许多个读者或单个写者
 
 ## 概述
 
 `ReadWriteLock` 实现了一个经典的读写锁。它允许多个线程同时持有读锁，但在有写锁时，所有读锁都必须释放，写锁为独占访问。这对于读操作远多于写操作的共享数据非常有效。
 
+### 设计目的
+
+- 提供比普通互斥锁更高的并发性能
+- 允许多个线程同时读取共享数据
+- 确保写入操作时的独占性访问
+- 防止写者饥饿（通过写者优先策略）
+
+### 使用场景
+
+- 读多写少的共享数据访问
+- 需要保护长时间读取的数据结构
+- 数据库、缓存、配置等共享资源访问
+
 ## 公共方法
 
-### 读锁
-
 | 方法 | 描述 |
 |------|------|
-| [`ReadLock`](readlock.md) | 获取读锁（可重入，支持多个并发读者） |
+| [`ReadWriteLock`](constructor.md) | 构造一个读写锁 |
+| [`~ReadWriteLock`](destructor.md) | 销毁读写锁 |
+| [`ReadLock`](readlock.md) | 获取读锁（支持多个并发读者） |
 | [`ReadUnlock`](readunlock.md) | 释放读锁 |
-
-### 写锁
-
-| 方法 | 描述 |
-|------|------|
 | [`WriteLock`](writelock.md) | 获取写锁（独占，阻塞所有读者和写者） |
 | [`WriteUnlock`](writeunlock.md) | 释放写锁 |
 
 ## 使用示例
 
 ```cpp
-Threading::ReadWriteLock rwLock;
-Containers::HashMap<String, int> sharedMap;
+#include "XCEngine/Threading/ReadWriteLock.h"
+#include <thread>
+#include <vector>
+#include <iostream>
+#include <map>
+
+XCEngine::Threading::ReadWriteLock rwLock;
+std::map<std::string, int> sharedCache;
 
 // 读操作（多个线程可同时读）
-int* ReadData(const String& key) {
+int ReadData(const std::string& key) {
     rwLock.ReadLock();
-    int* value = sharedMap.Find(key);
+    int value = 0;
+    auto it = sharedCache.find(key);
+    if (it != sharedCache.end()) {
+        value = it->second;
+    }
     rwLock.ReadUnlock();
     return value;
 }
 
 // 写操作（独占）
-void WriteData(const String& key, int value) {
+void WriteData(const std::string& key, int value) {
     rwLock.WriteLock();
-    sharedMap.Insert(key, value);
+    sharedCache[key] = value;
     rwLock.WriteUnlock();
 }
+
+int main() {
+    std::vector<std::thread> threads;
+
+    threads.emplace_back(WriteData, "score", 100);
+    threads.emplace_back(ReadData, "score");
+    threads.emplace_back(WriteData, "health", 200);
+    threads.emplace_back(ReadData, "health");
+
+    for (auto& t : threads) {
+        t.join();
+    }
+
+    return 0;
+}
 ```
 
 ## 相关文档
 
-- [Mutex](../mutex/mutex.md) - 互斥锁
-- [SpinLock](../spinlock/spinlock.md) - 自旋锁
-- [../threading/threading.md](../threading.md) - 模块总览
+- [`ReadLock`](readlock.md) - 获取读锁
+- [`ReadUnlock`](readunlock.md) - 释放读锁
+- [`WriteLock`](writelock.md) - 获取写锁
+- [`WriteUnlock`](writeunlock.md) - 释放写锁

docs/api/threading/readwritelock/writelock.md

@@ -10,6 +10,8 @@ void WriteLock()
 
 **返回：** 无
 
+**线程安全：** ✅
+
 **复杂度：** 平均 O(1)，写者饥饿时可能 O(n)
 
 **注意：**
@@ -20,7 +22,10 @@ void WriteLock()
 **示例：**
 
 ```cpp
-ReadWriteLock rwLock;
+#include "XCEngine/Threading/ReadWriteLock.h"
+#include <vector>
+
+XCEngine::Threading::ReadWriteLock rwLock;
 std::vector<int> buffer;
 
 void Append(int value) {
@@ -32,4 +37,5 @@ void Append(int value) {
 
 ## 相关文档
 
-- [ReadWriteLock 总览](readwritelock.md) - 返回类总览
+- [`ReadWriteLock`](readwritelock.md) - 返回类总览
+- [`WriteUnlock`](writeunlock.md) - 释放写锁

docs/api/threading/readwritelock/writeunlock.md

@@ -10,6 +10,8 @@ void WriteUnlock()
 
 **返回：** 无
 
+**线程安全：** ✅
+
 **复杂度：** O(1)
 
 **注意：** 必须在持有写锁的线程中调用。
@@ -17,10 +19,14 @@ void WriteUnlock()
 **示例：**
 
 ```cpp
-ReadWriteLock rwLock;
-std::unordered_map<String, int> cache;
+#include "XCEngine/Threading/ReadWriteLock.h"
+#include <unordered_map>
+#include <string>
 
-void UpdateCache(const String& key, int value) {
+XCEngine::Threading::ReadWriteLock rwLock;
+std::unordered_map<std::string, int> cache;
+
+void UpdateCache(const std::string& key, int value) {
     rwLock.WriteLock();
     cache[key] = value;
     rwLock.WriteUnlock();
@@ -29,4 +35,5 @@ void UpdateCache(const String& key, int value) {
 
 ## 相关文档
 
-- [ReadWriteLock 总览](readwritelock.md) - 返回类总览
+- [`ReadWriteLock`](readwritelock.md) - 返回类总览
+- [`WriteLock`](writelock.md) - 获取写锁

docs/api/threading/spinlock/lock.md

@@ -15,7 +15,7 @@ void Lock()
 **注意：**
 - 适用于临界区极短（几个 CPU 指令）的场景，避免线程切换开销。
 - 在锁持有时间较长或多核竞争激烈时，会浪费大量 CPU 周期，此时应使用 Mutex。
-- 同一线程不可重复 Lock 同一个 SpinLock。
+- 同一线程对同一个 SpinLock 重复加锁会导致死锁。
 
 **示例：**
 

docs/api/threading/spinlock/lock_1.md

@@ -0,0 +1,31 @@
+# SpinLock::lock
+
+```cpp
+void lock()
+```
+
+STL 兼容的 `lock()` 方法，与 [`Lock`](lock.md) 等效。满足 STL `Lockable` 概念要求。
+
+**参数：** 无
+
+**返回：** 无
+
+**复杂度：** 平均 O(1)，最坏情况取决于竞争程度
+
+**线程安全：** ✅
+
+**示例：**
+
+```cpp
+Threading::SpinLock spinLock;
+
+void STLCompatibleUsage() {
+    spinLock.lock();
+    // 临界区操作
+    spinLock.unlock();
+}
+```
+
+## 相关文档
+
+- [SpinLock 总览](spinlock.md) - 返回类总览

docs/api/threading/spinlock/spinlock.md

@@ -19,6 +19,9 @@
 | [`Lock`](lock.md) | 获取锁（忙等待） |
 | [`Unlock`](unlock.md) | 释放锁 |
 | [`TryLock`](trylock.md) | 尝试获取锁（非阻塞） |
+| [`lock`](lock_1.md) | STL 兼容的 Lock |
+| [`unlock`](unlock_1.md) | STL 兼容的 Unlock |
+| [`try_lock`](try_lock.md) | STL 兼容的 TryLock |
 
 ## STL 兼容方法
 
@@ -50,4 +53,4 @@ void SafeIncrement() {
 
 - [Mutex](../mutex/mutex.md) - 互斥锁
 - [ReadWriteLock](../readwritelock/readwritelock.md) - 读写锁
-- [../threading/threading.md](../threading.md) - 模块总览
+- [../threading.md](../threading.md) - 模块总览

docs/api/threading/spinlock/try_lock.md

@@ -0,0 +1,32 @@
+# SpinLock::try_lock
+
+```cpp
+bool try_lock()
+```
+
+STL 兼容的 `try_lock()` 方法，与 [`TryLock`](trylock.md) 等效。满足 STL `Lockable` 概念要求。
+
+**参数：** 无
+
+**返回：** `bool` - 获取成功返回 true，锁不可用返回 false
+
+**复杂度：** O(1)
+
+**线程安全：** ✅
+
+**示例：**
+
+```cpp
+Threading::SpinLock spinLock;
+
+void STLCompatibleTry() {
+    if (spinLock.try_lock()) {
+        // 临界区操作
+        spinLock.unlock();
+    }
+}
+```
+
+## 相关文档
+
+- [SpinLock 总览](spinlock.md) - 返回类总览

docs/api/threading/spinlock/unlock_1.md

@@ -0,0 +1,31 @@
+# SpinLock::unlock
+
+```cpp
+void unlock()
+```
+
+STL 兼容的 `unlock()` 方法，与 [`Unlock`](unlock.md) 等效。满足 STL `Lockable` 概念要求。
+
+**参数：** 无
+
+**返回：** 无
+
+**复杂度：** O(1)
+
+**线程安全：** ✅
+
+**示例：**
+
+```cpp
+Threading::SpinLock spinLock;
+
+void STLCompatibleUsage() {
+    spinLock.lock();
+    // 临界区操作
+    spinLock.unlock();
+}
+```
+
+## 相关文档
+
+- [SpinLock 总览](spinlock.md) - 返回类总览

docs/api/threading/task-group/add-dependency.md

@@ -0,0 +1,90 @@
+# TaskGroup::AddDependency
+
+```cpp
+void AddDependency(uint64_t taskId, uint64_t dependsOn);
+```
+
+为任务添加依赖关系。指定的任务 `taskId` 将在 `dependsOn` 任务完成后才会开始执行。
+
+**参数：**
+- `taskId` - 从属任务的 ID
+- `dependsOn` - 被依赖任务的 ID，taskId 将在此任务完成后才执行
+
+**返回：** 无
+
+**线程安全：** ✅ 线程安全
+
+**示例：**
+
+```cpp
+#include "XCEngine/Threading/TaskGroup.h"
+#include "XCEngine/Threading/Task.h"
+#include <iostream>
+#include <memory>
+
+using namespace XCEngine::Threading;
+
+int main() {
+    TaskGroup group;
+
+    uint64_t loadData = group.AddTask(
+        []() { std::cout << "Loading data...\n"; },
+        TaskPriority::High
+    );
+
+    uint64_t processData = group.AddTask(
+        []() { std::cout << "Processing data...\n"; },
+        TaskPriority::Normal
+    );
+
+    uint64_t saveData = group.AddTask(
+        []() { std::cout << "Saving data...\n"; },
+        TaskPriority::Low
+    );
+
+    group.AddDependency(processData, loadData);
+    group.AddDependency(saveData, processData);
+
+    std::cout << "Execution order: loadData -> processData -> saveData\n";
+
+    group.Wait();
+    return 0;
+}
+```
+
+## 相关文档
+
+- [TaskGroup 总览](task-group.md) - 返回类总览
+
+## 详细描述
+
+`AddDependency` 方法用于设置任务间的依赖关系。`taskId` 指定的任务将等待 `dependsOn` 指定的任务完成后才能开始执行。
+
+依赖关系必须在任务执行前设置，建议在所有任务添加完成后统一设置依赖。
+
+## 参数
+
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| `taskId` | `uint64_t` | 依赖其他任务的任务ID |
+| `dependsOn` | `uint64_t` | 被依赖的任务ID |
+
+## 返回值
+
+无
+
+## 示例
+
+```cpp
+TaskGroup* group = TaskSystem::Get().CreateTaskGroup();
+
+uint64_t loadData = group->AddTask([]() { /* 加载数据 */ });
+uint64_t processData = group->AddTask([]() { /* 处理数据 */ });
+uint64_t saveData = group->AddTask([]() { /* 保存数据 */ });
+
+// processData必须在loadData完成后才能执行
+group->AddDependency(processData, loadData);
+
+// saveData必须在processData完成后才能执行
+group->AddDependency(saveData, processData);
+```

docs/api/threading/task-group/add-task-callback.md

@@ -0,0 +1,55 @@
+# TaskGroup::AddTask (Callback)
+
+```cpp
+uint64_t AddTask(Callback&& func, TaskPriority priority = TaskPriority::Normal);
+```
+
+将函数回调添加为任务。该方法接受一个可调用对象（lambda、函数指针、std::function 等）作为任务执行体。
+
+**参数：**
+- `func` - 可调用对象，执行任务逻辑
+- `priority` - 任务优先级，默认为 Normal
+
+**返回：** 返回分配给任务的唯一 ID，可用于后续添加依赖关系
+
+**线程安全：** ✅ 线程安全
+
+**示例：**
+
+```cpp
+#include "XCEngine/Threading/TaskGroup.h"
+#include "XCEngine/Threading/Task.h"
+#include <iostream>
+
+using namespace XCEngine::Threading;
+
+int main() {
+    TaskGroup group;
+
+    uint64_t task1 = group.AddTask(
+        []() { std::cout << "Task 1 executing\n"; },
+        TaskPriority::Normal
+    );
+
+    uint64_t task2 = group.AddTask(
+        []() { std::cout << "Task 2 executing (High priority)\n"; },
+        TaskPriority::High
+    );
+
+    uint64_t task3 = group.AddTask(
+        []() { std::cout << "Task 3 executing (Low priority)\n"; },
+        TaskPriority::Low
+    );
+
+    group.AddDependency(task2, task1);
+
+    group.Wait();
+    return 0;
+}
+```
+
+## 相关文档
+
+- [TaskGroup 总览](task-group.md) - 返回类总览
+- [AddTask(ITask)](add-task.md) - 添加 ITask 对象形式的任务
+- [TaskPriority](task-priority.md) - 任务优先级说明

docs/api/threading/task-group/add-task.md

@@ -0,0 +1,62 @@
+# TaskGroup::AddTask
+
+```cpp
+uint64_t AddTask(std::unique_ptr<ITask> task);
+uint64_t AddTask(Callback&& func, TaskPriority priority = TaskPriority::Normal);
+```
+
+将任务添加到任务组。支持两种添加方式：传入 ITask 对象或传入回调函数。
+
+**参数：**
+- `task` - 唯一指针管理的 ITask 对象
+- `func` - 要执行的回调函数
+- `priority` - 任务优先级，默认为 `TaskPriority::Normal`
+
+**返回：** 返回分配的任务 ID，可用于设置依赖关系
+
+**线程安全：** ✅ 线程安全
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include "XCEngine/Threading/TaskGroup.h"
+#include "XCEngine/Threading/Task.h"
+#include <iostream>
+#include <memory>
+
+using namespace XCEngine::Threading;
+
+class MyTask : public ITask {
+public:
+    explicit MyTask(const std::string& name) : m_name(name) {}
+
+    void Execute() override {
+        std::cout << "Executing: " << m_name << "\n";
+    }
+
+private:
+    std::string m_name;
+};
+
+int main() {
+    TaskGroup group;
+
+    auto task = std::make_unique<MyTask>("DataLoading");
+    uint64_t taskId = group.AddTask(std::move(task));
+
+    uint64_t callbackId = group.AddTask([]() {
+        std::cout << "Lambda task executing\n";
+    }, TaskPriority::High);
+
+    group.AddDependency(callbackId, taskId);
+
+    group.Wait();
+    return 0;
+}
+```
+
+## 相关文档
+
+- [TaskGroup 总览](task-group.md) - 返回类总览

docs/api/threading/task-group/adddependency.md

@@ -1,44 +0,0 @@
-# TaskGroup::AddDependency
-
-```cpp
-void AddDependency(uint64_t taskId, uint64_t dependsOn)
-```
-
-为任务添加依赖关系。被依赖的任务必须先完成，当前任务才会开始执行。
-
-**参数：**
-- `taskId` - 任务 ID（需要等待的任务）
-- `dependsOn` - 依赖的父任务 ID
-
-**返回：** 无
-
-**复杂度：** O(1)
-
-**注意：**
-- 如果被依赖的任务不存在或已完成，调用无效果。
-- 支持添加多个依赖，但不支持循环依赖。
-
-**示例：**
-
-```cpp
-TaskGroup* group = TaskSystem::Get().CreateTaskGroup();
-
-uint64_t init = group->AddTask([]() { Initialize(); });
-uint64_t task1 = group->AddTask([]() { Phase1(); });
-uint64_t task2 = group->AddTask([]() { Phase2(); });
-uint64_t cleanup = group->AddTask([]() { Cleanup(); });
-
-// task1 和 task2 依赖 init
-group->AddDependency(task1, init);
-group->AddDependency(task2, init);
-
-// cleanup 依赖 task1 和 task2
-group->AddDependency(cleanup, task1);
-group->AddDependency(cleanup, task2);
-
-group->Wait();
-```
-
-## 相关文档
-
-- [TaskGroup 总览](task-group.md) - 返回类总览

docs/api/threading/task-group/addtask.md

@@ -1,60 +0,0 @@
-# TaskGroup::AddTask
-
-添加任务到任务组。有两个重载版本。
-
-## 重载 1: 添加 ITask 对象
-
-```cpp
-uint64_t AddTask(std::unique_ptr<ITask> task)
-```
-
-将一个已有的 ITask 对象添加到任务组。
-
-**参数：**
-- `task` - 要添加的 unique_ptr 任务对象
-
-**返回：** `uint64_t` - 分配的任务 ID
-
-**复杂度：** O(1)
-
-## 重载 2: 添加 lambda 任务
-
-```cpp
-uint64_t AddTask(Callback&& func, TaskPriority priority = TaskPriority::Normal)
-```
-
-将一个 lambda 函数包装为任务添加到任务组。
-
-**参数：**
-- `func` - 要执行的可调用对象
-- `priority` - 任务优先级，默认 TaskPriority::Normal
-
-**返回：** `uint64_t` - 分配的任务 ID
-
-**复杂度：** O(1)
-
-**示例：**
-
-```cpp
-TaskGroup* group = TaskSystem::Get().CreateTaskGroup();
-
-// 添加 lambda 任务
-uint64_t id1 = group->AddTask([]() {
-    printf("Task A running\n");
-});
-
-uint64_t id2 = group->AddTask([]() {
-    printf("Task B running\n");
-}, TaskPriority::High);
-
-// 添加自定义 ITask
-class MyTask : public ITask {
-public:
-    void Execute() override { printf("Custom task\n"); }
-};
-uint64_t id3 = group->AddTask(std::make_unique<MyTask>());
-```
-
-## 相关文档
-
-- [TaskGroup 总览](task-group.md) - 返回类总览

docs/api/threading/task-group/cancel.md

@@ -1,43 +1,47 @@
 # TaskGroup::Cancel
 
 ```cpp
-void Cancel()
+void Cancel();
 ```
 
-**注意：** 此方法为**部分实现**，存在已知问题。
-
-取消任务组中所有尚未执行的任务。正在执行的任务将不受影响。
+取消任务组中所有尚未开始执行的任务。已经执行完成的任务和正在执行的任务不受影响。
 
 **参数：** 无
 
 **返回：** 无
 
-**复杂度：** O(n)
-
-**当前状态：** 此方法会调用各任务的 `OnCancel()` 回调，但不会减少 `m_pendingCount` 计数器。因此调用 `Wait()` 会导致永久阻塞。建议在 `Cancel()` 后使用 `IsComplete()` 轮询或使用带超时的 `WaitFor()`。
+**线程安全：** ✅ 线程安全
 
 **示例：**
 
 ```cpp
-TaskGroup* group = TaskSystem::Get().CreateTaskGroup();
+#include "XCEngine/Threading/TaskGroup.h"
+#include "XCEngine/Threading/Task.h"
+#include <iostream>
+#include <chrono>
 
-for (int i = 0; i < 100; ++i) {
-    group->AddTask([i]() {
-        if (ShouldCancel()) {
-            return; // 检查取消状态
-        }
-        ProcessLongTask(i);
-    });
+using namespace XCEngine::Threading;
+
+int main() {
+    TaskGroup group;
+
+    for (int i = 0; i < 10; ++i) {
+        group.AddTask([i]() {
+            std::cout << "Task " << i << " executing\n";
+            std::this_thread::sleep_for(std::chrono::milliseconds(100));
+        });
+    }
+
+    std::this_thread::sleep_for(std::chrono::milliseconds(150));
+
+    std::cout << "Cancelling remaining tasks...\n";
+    group.Cancel();
+
+    group.Wait();
+    std::cout << "Tasks cancelled. Final progress: " << (group.GetProgress() * 100) << "%\n";
+
+    return 0;
 }
-
-// 如果用户点击取消按钮
-if (userClickedCancel) {
-    group->Cancel();
-    printf("Tasks canceled. Progress: %.1f%%\n", group->GetProgress() * 100.0f);
-}
-
-// 注意：Cancel() 后 Wait() 会永久阻塞，应使用 WaitFor()
-group->WaitFor(std::chrono::seconds(1));
 ```
 
 ## 相关文档

docs/api/threading/task-group/get-progress.md

@@ -0,0 +1,50 @@
+# TaskGroup::GetProgress
+
+```cpp
+float GetProgress() const;
+```
+
+获取任务组的完成进度。
+
+**参数：** 无
+
+**返回：** 
+- `float` - 0.0 到 1.0 之间的进度值，0.0 表示没有任务或都没有完成，1.0 表示全部完成
+
+**线程安全：** ✅ 线程安全
+
+**示例：**
+
+```cpp
+#include "XCEngine/Threading/TaskGroup.h"
+#include "XCEngine/Threading/Task.h"
+#include <iostream>
+#include <chrono>
+
+using namespace XCEngine::Threading;
+
+int main() {
+    TaskGroup group;
+
+    for (int i = 0; i < 4; ++i) {
+        group.AddTask([i]() {
+            std::this_thread::sleep_for(std::chrono::milliseconds(100));
+        });
+    }
+
+    while (!group.IsComplete()) {
+        float progress = group.GetProgress();
+        std::cout << "Progress: " << (progress * 100) << "%\n";
+        std::this_thread::sleep_for(std::chrono::milliseconds(50));
+    }
+
+    std::cout << "Final Progress: " << (group.GetProgress() * 100) << "%\n";
+
+    return 0;
+}
+```
+
+## 相关文档
+
+- [TaskGroup 总览](task-group.md) - 返回类总览
+- [IsComplete](is-complete.md) - 检查是否完成

docs/api/threading/task-group/getprogress.md

@@ -1,40 +0,0 @@
-# TaskGroup::GetProgress
-
-```cpp
-float GetProgress() const
-```
-
-**注意：** 此方法当前为**空实现/桩代码**。
-
-获取任务组的完成进度。
-
-**参数：** 无
-
-**返回：** `float` - 始终返回 `0.0f`（任务组为空时返回 `1.0f`）
-
-**复杂度：** O(1)
-
-**当前状态：** 此方法为空实现，始终返回 `0.0f`，因为 `m_completedCount` 未被更新。
-
-**示例：**
-
-```cpp
-TaskGroup* group = TaskSystem::Get().CreateTaskGroup();
-
-for (int i = 0; i < 1000; ++i) {
-    group->AddTask([i]() { ProcessItem(i); });
-}
-
-// 显示进度（注意：当前实现始终返回 0.0f）
-while (!group->IsComplete()) {
-    float progress = group->GetProgress();
-    printf("\rProgress: %.1f%%", progress * 100.0f);
-    Thread::Sleep(100);
-}
-printf("\n");
-```
-
-## 相关文档
-
-- [TaskGroup 总览](task-group.md) - 返回类总览
-- [IsComplete](iscomplete.md) - 检查是否完成

docs/api/threading/task-group/is-complete.md

@@ -0,0 +1,50 @@
+# TaskGroup::IsComplete
+
+```cpp
+bool IsComplete() const;
+```
+
+检查任务组中的所有任务是否已完成。
+
+**参数：** 无
+
+**返回：** 
+- `true` - 所有任务已完成（包括被取消的）
+- `false` - 仍有任务在执行或等待执行
+
+**线程安全：** ✅ 线程安全
+
+**示例：**
+
+```cpp
+#include "XCEngine/Threading/TaskGroup.h"
+#include "XCEngine/Threading/Task.h"
+#include <iostream>
+#include <chrono>
+
+using namespace XCEngine::Threading;
+
+int main() {
+    TaskGroup group;
+
+    group.AddTask([]() {
+        std::this_thread::sleep_for(std::chrono::milliseconds(100));
+        std::cout << "Task completed\n";
+    });
+
+    std::cout << "Immediately after AddTask, IsComplete: "
+              << (group.IsComplete() ? "true" : "false") << "\n";
+
+    group.Wait();
+
+    std::cout << "After Wait, IsComplete: "
+              << (group.IsComplete() ? "true" : "false") << "\n";
+
+    return 0;
+}
+```
+
+## 相关文档
+
+- [TaskGroup 总览](task-group.md) - 返回类总览
+- [GetProgress](get-progress.md) - 获取进度百分比

docs/api/threading/task-group/iscomplete.md

@@ -1,38 +0,0 @@
-# TaskGroup::IsComplete
-
-```cpp
-bool IsComplete() const
-```
-
-**注意：** 此方法当前为**空实现/桩代码**。
-
-检查任务组中所有任务是否已完成。
-
-**参数：** 无
-
-**返回：** `bool` - 始终返回 `false`（空实现）
-
-**复杂度：** O(1)（空实现）
-
-**当前状态：** 此方法为空实现，始终返回 `false`，因为 `m_pendingCount` 计数器未正确递减。
-
-**示例：**
-
-```cpp
-TaskGroup* group = TaskSystem::Get().CreateTaskGroup();
-
-for (int i = 0; i < 100; ++i) {
-    group->AddTask([i]() { HeavyCompute(i); });
-}
-
-// 非阻塞轮询
-while (!group->IsComplete()) {
-    printf("Progress: %.1f%%\n", group->GetProgress() * 100.0f);
-    Thread::Sleep(500);
-}
-```
-
-## 相关文档
-
-- [TaskGroup 总览](task-group.md) - 返回类总览
-- [GetProgress](getprogress.md) - 获取完成进度

docs/api/threading/task-group/set-complete-callback.md

@@ -0,0 +1,82 @@
+# TaskGroup::SetCompleteCallback
+
+```cpp
+void SetCompleteCallback(Callback&& callback);
+```
+
+设置任务组完成时的回调函数。当所有任务都执行完成后（包括被取消的任务），该回调将被调用。
+
+**参数：**
+- `callback` - 可调用对象，在所有任务完成后执行
+
+**返回：** 无
+
+**线程安全：** ✅ 线程安全
+
+**示例：**
+
+```cpp
+#include "XCEngine/Threading/TaskGroup.h"
+#include "XCEngine/Threading/Task.h"
+#include <iostream>
+
+using namespace XCEngine::Threading;
+
+int main() {
+    TaskGroup group;
+
+    group.SetCompleteCallback([]() {
+        std::cout << "All tasks have been completed!\n";
+    });
+
+    for (int i = 0; i < 3; ++i) {
+        group.AddTask([i]() {
+            std::cout << "Task " << i << " executing\n";
+        });
+    }
+
+    group.Wait();
+    std::cout << "Back in main after Wait()\n";
+
+    return 0;
+}
+```
+
+## 相关文档
+
+- [TaskGroup 总览](task-group.md) - 返回类总览
+
+## 详细描述
+
+`SetCompleteCallback` 方法用于设置当任务组中所有任务都完成时调用的回调函数。回调在最后一个任务完成时触发。
+
+## 参数
+
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| `callback` | `Callback&&` | 回调函数，类型为 `std::function<void()>` |
+
+## 返回值
+
+无
+
+## 示例
+
+```cpp
+TaskGroup* group = TaskSystem::Get().CreateTaskGroup();
+
+group->SetCompleteCallback([]() {
+    printf("All tasks in group have completed!\n");
+});
+
+for (int i = 0; i < 10; ++i) {
+    group->AddTask([i]() {
+        printf("Task %d completed\n", i);
+    });
+}
+
+// 等待所有任务完成，回调会被触发
+group->Wait();
+
+TaskSystem::Get().DestroyTaskGroup(group);
+```

docs/api/threading/task-group/setcompletecallback.md

@@ -1,36 +0,0 @@
-# TaskGroup::SetCompleteCallback
-
-```cpp
-void SetCompleteCallback(Callback&& callback)
-```
-
-设置任务组完成回调。当所有任务都完成后，回调函数将在某个工作线程中被调用。
-
-**参数：**
-- `callback` - 完成时要调用的回调函数
-
-**返回：** 无
-
-**复杂度：** O(1)
-
-**示例：**
-
-```cpp
-TaskGroup* group = TaskSystem::Get().CreateTaskGroup();
-
-group->AddTask([]() { LoadTextures(); });
-group->AddTask([]() { LoadMeshes(); });
-group->AddTask([]() { LoadAudio(); });
-
-group->SetCompleteCallback([]() {
-    printf("All assets loaded!\n");
-    ResourceManager::InitGPUResources();
-});
-
-group->Wait();
-TaskSystem::Get().DestroyTaskGroup(group);
-```
-
-## 相关文档
-
-- [TaskGroup 总览](task-group.md) - 返回类总览

docs/api/threading/task-group/task-group.md

@@ -6,61 +6,83 @@
 
 **头文件**: `XCEngine/Threading/TaskGroup.h`
 
-**描述**: 任务组管理类，用于组织多个任务并支持批量等待、进度跟踪和依赖管理。
+**描述**: 管理一组相关任务的执行和同步
 
 ## 概述
 
-`TaskGroup` 提供了一种批量管理任务的机制。它允许添加多个任务、设置任务依赖关系、等待所有任务完成，并提供进度回调功能。
+TaskGroup 用于将多个相关任务组织在一起，统一管理它们的执行和同步。任务组内的任务可以声明依赖关系，确保任务按照正确的顺序执行。支持任务优先级设置、完成回调、进度查询和取消操作。
 
-## 公共类型
-
-| 类型 | 描述 |
-|------|------|
-| `Callback = std::function<void()>` | 任务组回调函数类型 |
+主要功能：
+- 添加任务（ITask 对象或函数回调）
+- 声明任务间依赖关系
+- 等待所有任务完成
+- 设置完成回调
+- 查询完成进度
+- 取消未执行的任务
 
 ## 公共方法
 
 | 方法 | 描述 |
 |------|------|
-| `TaskGroup()` | 默认构造函数 |
-| `~TaskGroup()` | 析构函数 |
-| [`AddTask(unique_ptr)`](addtask.md) | 添加任务对象 |
-| [`AddTask(callback)`](addtask.md) | 添加 lambda 任务 |
-| [`AddDependency`](adddependency.md) | 添加任务依赖关系 |
+| [`Task()`](task-group.md) | 默认构造函数 |
+| [`~Task()`](task-group.md) | 析构函数 |
+| [`AddTask`](add-task.md) | 添加任务到组（支持 ITask 或 Callback） |
+| [`AddDependency`](add-dependency.md) | 添加任务依赖关系 |
 | [`Wait`](wait.md) | 阻塞等待所有任务完成 |
-| [`WaitFor`](waitfor.md) | 超时等待 |
-| [`SetCompleteCallback`](setcompletecallback.md) | 设置完成回调 |
-| [`IsComplete`](iscomplete.md) | 检查所有任务是否完成 |
-| [`GetProgress`](getprogress.md) | 获取完成进度（0.0f ~ 1.0f） |
-| [`Cancel`](cancel.md) | 取消所有任务 |
+| [`WaitFor`](wait-for.md) | 等待指定超时时间 |
+| [`SetCompleteCallback`](set-complete-callback.md) | 设置完成回调函数 |
+| [`IsComplete`](is-complete.md) | 检查所有任务是否完成 |
+| [`GetProgress`](get-progress.md) | 获取任务组完成进度 |
+| [`Cancel`](cancel.md) | 取消所有未执行的任务 |
 
 ## 使用示例
 
 ```cpp
-TaskGroup* group = TaskSystem::Get().CreateTaskGroup();
+#include "XCEngine/Threading/TaskGroup.h"
+#include "XCEngine/Threading/Task.h"
+#include <iostream>
 
-// 添加多个任务
-uint64_t task1 = group->AddTask([]() { /* 任务1 */ });
-uint64_t task2 = group->AddTask([]() { /* 任务2 */ });
+using namespace XCEngine::Threading;
 
-// 设置依赖：task3 等待 task1 完成
-uint64_t task3 = group->AddTask([]() { /* 任务3 */ });
-group->AddDependency(task3, task1);
+class MyTask : public ITask {
+public:
+    explicit MyTask(const std::string& name) : m_name(name) {}
 
-// 设置完成回调
-group->SetCompleteCallback([]() {
-    printf("All tasks completed!\n");
-});
+    void Execute() override {
+        std::cout << "Task " << m_name << " executing\n";
+    }
 
-// 等待完成
-group->Wait();
+    void OnComplete() override {
+        std::cout << "Task " << m_name << " completed\n";
+    }
 
-// 销毁
-TaskSystem::Get().DestroyTaskGroup(group);
+private:
+    std::string m_name;
+};
+
+int main() {
+    TaskGroup group;
+
+    uint64_t task1 = group.AddTask(std::make_unique<MyTask>("Task1"));
+    uint64_t task2 = group.AddTask([]() {
+        std::cout << "Lambda task executing\n";
+    }, TaskPriority::High);
+
+    group.AddDependency(task2, task1);
+
+    group.SetCompleteCallback([]() {
+        std::cout << "All tasks completed!\n";
+    });
+
+    group.Wait();
+
+    std::cout << "Progress: " << group.GetProgress() * 100 << "%\n";
+
+    return 0;
+}
 ```
 
 ## 相关文档
 
-- [ITask](../task/task.md) - 任务基类
-- [TaskSystem](../task-system/task-system.md) - 任务系统
-- [../threading/threading.md](../threading.md) - 模块总览
+- [ITask](../task/task.md) - 任务接口基类
+- [TaskSystem](../task-system/task-system.md) - 任务调度系统

docs/api/threading/task-group/task-priority.md

@@ -0,0 +1,59 @@
+# TaskPriority
+
+**命名空间**: `XCEngine::Threading`
+
+**类型**: `enum class`
+
+**头文件**: `XCEngine/Threading/Task.h`
+
+## 概述
+
+`TaskPriority` 定义了任务的优先级，用于控制任务在任务系统中的执行顺序。优先级较高的任务会在优先级较低的任务之前执行。
+
+## 枚举值
+
+| 枚举值 | 数值 | 描述 |
+|--------|------|------|
+| `Critical` | 0 | 最高优先级，关键任务 |
+| `High` | 1 | 高优先级 |
+| `Normal` | 2 | 普通优先级（默认） |
+| `Low` | 3 | 低优先级 |
+| `Idle` | 4 | 最低优先级，仅在无其他任务时执行 |
+
+## 使用示例
+
+```cpp
+#include "XCEngine/Threading/TaskGroup.h"
+#include "XCEngine/Threading/Task.h"
+#include <iostream>
+
+using namespace XCEngine::Threading;
+
+int main() {
+    TaskGroup group;
+
+    group.AddTask([]() {
+        std::cout << "Critical task\n";
+    }, TaskPriority::Critical);
+
+    group.AddTask([]() {
+        std::cout << "High priority task\n";
+    }, TaskPriority::High);
+
+    group.AddTask([]() {
+        std::cout << "Normal task\n";
+    }, TaskPriority::Normal);
+
+    group.AddTask([]() {
+        std::cout << "Low priority task\n";
+    }, TaskPriority::Low);
+
+    group.Wait();
+    return 0;
+}
+```
+
+## 相关文档
+
+- [TaskGroup 总览](task-group.md) - 任务组类总览
+- [ITask](../task/task.md) - 任务接口基类

docs/api/threading/task-group/wait-for.md

@@ -0,0 +1,89 @@
+# TaskGroup::WaitFor
+
+```cpp
+bool WaitFor(std::chrono::milliseconds timeout);
+```
+
+等待任务组中的所有任务完成，最多等待指定的超时时间。
+
+**参数：**
+- `timeout` - 最大等待时间
+
+**返回：** 
+- `true` - 所有任务在超时前已完成
+- `false` - 等待超时，仍有任务未完成
+
+**线程安全：** ✅ 线程安全
+
+**示例：**
+
+```cpp
+#include "XCEngine/Threading/TaskGroup.h"
+#include "XCEngine/Threading/Task.h"
+#include <iostream>
+#include <chrono>
+
+using namespace XCEngine::Threading;
+
+int main() {
+    TaskGroup group;
+
+    group.AddTask([]() {
+        std::this_thread::sleep_for(std::chrono::seconds(5));
+        std::cout << "Long running task completed\n";
+    });
+
+    std::cout << "Waiting with 1 second timeout...\n";
+
+    if (group.WaitFor(std::chrono::milliseconds(1000))) {
+        std::cout << "All tasks completed within timeout\n";
+    } else {
+        std::cout << "Timeout! Some tasks still running.\n";
+    }
+
+    group.Wait();
+    std::cout << "All tasks finally completed after second wait.\n";
+
+    return 0;
+}
+```
+
+## 相关文档
+
+- [TaskGroup 总览](task-group.md) - 返回类总览
+- [Wait](wait.md) - 无限等待
+
+## 详细描述
+
+`WaitFor` 方法会阻塞当前线程，直到所有任务完成或超过指定的超时时间。
+
+## 参数
+
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| `timeout` | `std::chrono::milliseconds` | 超时时间（毫秒） |
+
+## 返回值
+
+返回 `bool` 类型：
+- `true`: 所有任务在超时前完成
+- `false`: 发生超时
+
+## 示例
+
+```cpp
+TaskGroup* group = TaskSystem::Get().CreateTaskGroup();
+
+group->AddTask([]() {
+    std::this_thread::sleep_for(std::chrono::seconds(5));
+});
+
+// 等待3秒超时
+if (group->WaitFor(std::chrono::milliseconds(3000))) {
+    printf("All tasks completed on time\n");
+} else {
+    printf("Wait timed out\n");
+}
+
+TaskSystem::Get().DestroyTaskGroup(group);
+```

docs/api/threading/task-group/wait.md

@@ -1,46 +1,47 @@
 # TaskGroup::Wait
 
 ```cpp
-void Wait()
+void Wait();
 ```
 
-**注意：** 此方法当前为**空实现/桩代码**，不执行任何操作。
-
-阻塞当前线程，等待任务组中所有任务完成。
+阻塞当前线程，直到任务组中的所有任务完成执行。
 
 **参数：** 无
 
 **返回：** 无
 
-**复杂度：** N/A（空实现）
-
-**当前状态：** 此方法为空实现，不执行任何操作。由于 `m_pendingCount` 计数器未正确更新，此方法永远无法正常运作。
-
-**建议：** 使用 `WaitFor()` 代替以避免永久阻塞。
+**线程安全：** ✅ 线程安全
 
 **示例：**
 
 ```cpp
-TaskGroup* group = TaskSystem::Get().CreateTaskGroup();
+#include "XCEngine/Threading/TaskGroup.h"
+#include "XCEngine/Threading/Task.h"
+#include <iostream>
+#include <chrono>
 
-for (int i = 0; i < 10; ++i) {
-    group->AddTask([i]() {
-        printf("Task %d running\n", i);
-    });
+using namespace XCEngine::Threading;
+
+int main() {
+    TaskGroup group;
+
+    for (int i = 0; i < 5; ++i) {
+        group.AddTask([i]() {
+            std::cout << "Task " << i << " started\n";
+            std::this_thread::sleep_for(std::chrono::milliseconds(100));
+            std::cout << "Task " << i << " finished\n";
+        });
+    }
+
+    std::cout << "Waiting for all tasks...\n";
+    group.Wait();
+    std::cout << "All tasks completed!\n";
+
+    return 0;
 }
-
-printf("Waiting for all tasks...\n");
-// 注意：Wait() 为空实现，建议使用 WaitFor()
-if (group->WaitFor(std::chrono::seconds(5))) {
-    printf("All tasks completed within 5 seconds\n");
-} else {
-    printf("Timeout! Tasks may not have completed\n");
-}
-
-TaskSystem::Get().DestroyTaskGroup(group);
 ```
 
 ## 相关文档
 
 - [TaskGroup 总览](task-group.md) - 返回类总览
-- [WaitFor](waitfor.md) - 超时等待
+- [WaitFor](wait-for.md) - 带超时的等待

docs/api/threading/task-group/waitfor.md

@@ -1,39 +0,0 @@
-# TaskGroup::WaitFor
-
-```cpp
-bool WaitFor(std::chrono::milliseconds timeout)
-```
-
-等待任务组中所有任务完成，可在超时后返回。
-
-**参数：**
-- `timeout` - 最大等待时间
-
-**返回：** `bool` - 所有任务在超时前完成返回 true，超时返回 false
-
-**复杂度：** O(n)
-
-**示例：**
-
-```cpp
-TaskGroup* group = TaskSystem::Get().CreateTaskGroup();
-
-for (int i = 0; i < 5; ++i) {
-    group->AddTask([i]() {
-        Thread::Sleep(i * 100);
-        printf("Task %d done\n", i);
-    });
-}
-
-if (group->WaitFor(std::chrono::seconds(1))) {
-    printf("All tasks completed within 1 second\n");
-} else {
-    printf("Timeout! Some tasks still running\n");
-    printf("Progress: %.1f%%\n", group->GetProgress() * 100.0f);
-}
-```
-
-## 相关文档
-
-- [TaskGroup 总览](task-group.md) - 返回类总览
-- [Wait](wait.md) - 无超时等待

docs/api/threading/task-system/createtaskgroup.md

@@ -10,6 +10,8 @@ TaskGroup* CreateTaskGroup()
 
 **返回：** `TaskGroup*` - 新创建的任务组指针
 
+**线程安全：** ✅ (内部使用 SpinLock 保护)
+
 **复杂度：** O(1)
 
 **注意：**

docs/api/threading/task-system/destroytaskgroup.md

@@ -11,6 +11,8 @@ void DestroyTaskGroup(TaskGroup* group)
 
 **返回：** 无
 
+**线程安全：** ✅ (内部使用 SpinLock 保护)
+
 **复杂度：** O(1)
 
 **注意：**

docs/api/threading/task-system/getworkerthreadcount.md

@@ -10,6 +10,8 @@ uint32_t GetWorkerThreadCount() const
 
 **返回：** `uint32_t` - 工作线程数量
 
+**线程安全：** ✅ (只读操作)
+
 **复杂度：** O(1)
 
 **示例：**

docs/api/threading/task-system/initialize.md

@@ -11,6 +11,8 @@ void Initialize(const TaskSystemConfig& config)
 
 **返回：** 无
 
+**线程安全：** ❌ (应在主线程初始化)
+
 **复杂度：** O(n)，n 为 workerThreadCount
 
 **注意：**

docs/api/threading/task-system/parallelfor.md

@@ -17,6 +17,8 @@ void ParallelFor(int32_t start, int32_t end, Func&& func)
 
 **返回：** 无
 
+**线程安全：** ✅ (内部通过 Submit 实现线程安全)
+
 **复杂度：** O(n)
 
 **分区策略：**

docs/api/threading/task-system/runonmainthread.md

@@ -11,6 +11,8 @@ void RunOnMainThread(std::function<void()>&& func)
 
 **返回：** 无
 
+**线程安全：** ✅ (内部使用 mutex 保护主线程队列)
+
 **复杂度：** O(1)
 
 **使用场景：**

docs/api/threading/task-system/shutdown.md

@@ -10,6 +10,8 @@ void Shutdown()
 
 **返回：** 无
 
+**线程安全：** ❌ (非线程安全，调用后应等待所有任务完成)
+
 **复杂度：** O(n)
 
 **注意：**

docs/api/threading/task-system/submit.md

@@ -33,6 +33,8 @@ uint64_t Submit(std::function<void()>&& func, TaskPriority priority = TaskPriori
 
 **复杂度：** O(log n)
 
+**线程安全：** ✅ (内部使用 mutex 保护任务队列)
+
 **示例：**
 
 ```cpp
@@ -52,10 +54,12 @@ uint64_t id3 = TaskSystem::Get().Submit([]() {
     HeavyCompute();
 }, TaskPriority::High);
 
-// 等待任务完成
-TaskSystem::Get().Wait(id1);
-TaskSystem::Get().Wait(id2);
-TaskSystem::Get().Wait(id3);
+// 使用 TaskGroup 等待任务完成
+TaskGroup* group = TaskSystem::Get().CreateTaskGroup();
+group->AddTask([]() { /* task 1 */ });
+group->AddTask([]() { /* task 2 */ });
+group->Wait();
+TaskSystem::Get().DestroyTaskGroup(group);
 ```
 
 ## 相关文档

docs/api/threading/task-system/task-system.md

@@ -12,7 +12,7 @@
 
 `TaskSystem` 是 XCEngine 的核心并行任务调度系统。它创建多个工作线程，使用优先级队列调度任务。它还提供 `ParallelFor` 方法用于数据级并行，以及主线程任务队列。
 
-**注意：** 当前实现的 `stealTasks` 配置项未生效，任务系统使用单一全局任务队列而非工作窃取模式。
+**注意：** 当前实现的 `stealTasks` 配置项未生效，任务系统使用单一全局优先级任务队列。
 
 ## 单例访问
 
@@ -24,7 +24,8 @@
 
 | 方法 | 描述 |
 |------|------|
-| [`Get`](get.md) | 获取单例实例 |
+| [`TaskSystem()`](task-system.md) | 私有构造函数（单例） |
+| [`~TaskSystem()`](task-system.md) | 析构函数 |
 | [`Initialize`](initialize.md) | 初始化任务系统 |
 | [`Shutdown`](shutdown.md) | 关闭任务系统 |
 | [`Submit(unique_ptr)`](submit.md) | 提交任务对象 |

docs/api/threading/task-system/update.md

@@ -10,6 +10,8 @@ void Update()
 
 **返回：** 无
 
+**线程安全：** ❌ (应在主线程调用)
+
 **复杂度：** O(n)，n 为队列中待执行任务数
 
 **使用场景：**

docs/api/threading/task-system/wait.md

@@ -6,17 +6,10 @@ void Wait(uint64_t taskId)
 
 **注意：** 此方法当前为空实现，不执行任何操作。
 
-**参数：**
-- `taskId` - 要等待的任务 ID
-
-**返回：** 无
-
-**复杂度：** N/A（空实现）
-
-**当前状态：** 此方法为空实现，不执行任何操作。任务系统目前不支持按任务 ID 等待。
-
 **建议：** 使用 `TaskGroup::Wait` 代替此方法。
 
+**线程安全：** N/A (空实现)
+
 **示例：**
 
 ```cpp

docs/api/threading/task/task.md

@@ -42,8 +42,6 @@
 | 方法 | 描述 |
 |------|------|
 | `virtual ~ITask()` | 虚析构函数 |
-| `ITask()` | 默认构造函数（受保护） |
-| `ITask(TaskPriority priority)` | 带优先级的构造函数（受保护） |
 | [`Execute`](execute.md) | 任务执行逻辑（纯虚） |
 | [`OnComplete`](oncomplete.md) | 任务完成回调（可重写） |
 | [`OnCancel`](oncancel.md) | 任务取消回调（可重写） |
@@ -56,6 +54,13 @@
 | [`AddRef`](addref.md) | 增加引用计数 |
 | [`Release`](release.md) | 减少引用计数（引用归零时自动 delete） |
 
+## 受保护方法
+
+| 方法 | 描述 |
+|------|------|
+| `ITask()` | 默认构造函数 |
+| `ITask(TaskPriority priority)` | 带优先级的构造函数 |
+
 ## 使用示例
 
 ```cpp

docs/api/threading/thread/detach.md

@@ -1,36 +1,44 @@
 # Thread::Detach
 
 ```cpp
-void Detach()
+void Detach();
 ```
 
-分离线程，使其成为后台线程独立运行。分离后，线程的资源将在其终止时自动释放，调用线程不会被阻塞。
+分离线程，使其在后台独立运行。调用 `Detach()` 后，线程不再受 `Thread` 对象管理，其生命周期由 C++ 运行时库自行管理，直到线程函数执行完毕。
+
+分离后的线程成为"守护线程"，其资源在线程结束时自动由运行时回收。与 `Join()` 不同，`Detach()` 只能调用一次。
+
+**警告：** 分离线程时必须确保其访问的所有数据在线程运行期间保持有效。分离后无法通过 `Thread` 对象同步或等待线程。
 
 **参数：** 无
 
 **返回：** 无
 
-**复杂度：** O(1)
-
-**注意：**
-- 分离后的线程无法再被 Join 或进行任何同步操作。
-- 确保分离线程的所有资源访问都是线程安全的，因为主线程可能在分离线程结束前退出。
-- 如果 Thread 对象在分离线程结束前被销毁，行为取决于具体实现。
+**线程安全：** ❌
 
 **示例：**
 
 ```cpp
-Thread background;
-background.Start([]() {
-    printf("Background task running\n");
-    for (int i = 0; i < 3; ++i) {
-        Thread::Sleep(500);
-        printf("Background: tick %d\n", i);
-    }
-}, "BackgroundThread");
+#include "XCEngine/Threading/Thread.h"
+#include <iostream>
 
-background.Detach();
-printf("Main thread continues immediately\n");
+using namespace XCEngine::Threading;
+
+int main() {
+    Thread t;
+    t.Start([]() {
+        for (int i = 0; i < 3; ++i) {
+            std::cout << "Detached thread running: " << i << std::endl;
+            Thread::Sleep(50);
+        }
+    }, "DetachedThread");
+    
+    std::cout << "Thread detached, main continues..." << std::endl;
+    t.Detach();
+    
+    Thread::Sleep(200);
+    return 0;
+}
 ```
 
 ## 相关文档

docs/api/threading/thread/getcurrentid.md

@@ -1,27 +1,40 @@
 # Thread::GetCurrentId
 
 ```cpp
-static Id GetCurrentId()
+static Id GetCurrentId();
 ```
 
-获取当前执行线程的唯一标识符。这是一个静态方法，可以在任何线程上下文中调用。
+静态方法，返回当前执行线程的唯一标识符。此方法可在任意线程上下文中调用，包括主线程和工作线程。
+
+线程 ID 通过 `std::this_thread::get_id()` 获取，并使用 `std::hash<std::thread::id>` 转换为 `uint64_t` 值。该值与 `Thread::GetId()` 返回的值格式一致，可以直接比较。
 
 **参数：** 无
 
-**返回：** `Thread::Id` - 当前执行线程的唯一标识符
+**返回：** 调用线程的唯一标识符
 
-**复杂度：** O(1)
+**线程安全：** ✅
 
 **示例：**
 
 ```cpp
-Thread worker;
-worker.Start([]() {
-    printf("Worker thread id: %llu\n", (unsigned long long)Thread::GetCurrentId());
-}, "WorkerThread");
+#include "XCEngine/Threading/Thread.h"
+#include <iostream>
 
-printf("Main thread id: %llu\n", (unsigned long long)Thread::GetCurrentId());
-worker.Join();
+using namespace XCEngine::Threading;
+
+int main() {
+    std::cout << "Main thread ID: " << Thread::GetCurrentId() << std::endl;
+    
+    Thread t;
+    t.Start([]() {
+        std::cout << "Worker thread ID: " << Thread::GetCurrentId() << std::endl;
+        std::cout << "Worker ID matches Thread.GetId(): " 
+                  << (Thread::GetCurrentId() == t.GetId() ? "Yes" : "No") << std::endl;
+    }, "CheckIdThread");
+    
+    t.Join();
+    return 0;
+}
 ```
 
 ## 相关文档

docs/api/threading/thread/getid.md

@@ -1,27 +1,41 @@
 # Thread::GetId
 
 ```cpp
-Id GetId() const
+Id GetId() const;
 ```
 
-获取当前线程对象的唯一标识符。该 ID 在线程启动后有效。
+返回当前线程对象的唯一标识符。线程 ID 是 `uint64_t` 类型的值，通过 `std::thread::native_handle()` 获取原生线程句柄并转换为整数。
+
+线程 ID 在线程启动后生效。在调用 `Start()` 之前，`GetId()` 返回 0。
 
 **参数：** 无
 
-**返回：** `Thread::Id` - 线程的唯一标识符（uint64_t 类型）
+**返回：** 线程的唯一标识符，线程未启动时返回 0
 
-**复杂度：** O(1)
-
-**注意：** 在调用 Start 之前返回 0。
+**线程安全：** ✅
 
 **示例：**
 
 ```cpp
-Thread worker;
-printf("Before start: id=%llu\n", (unsigned long long)worker.GetId());
-worker.Start([]() {}, "Test");
-printf("After start: id=%llu\n", (unsigned long long)worker.GetId());
-worker.Join();
+#include "XCEngine/Threading/Thread.h"
+#include <iostream>
+
+using namespace XCEngine::Threading;
+
+int main() {
+    Thread t;
+    
+    std::cout << "Before Start - Thread ID: " << t.GetId() << std::endl;
+    
+    t.Start([]() {
+        std::cout << "Worker ID: " << Thread::GetCurrentId() << std::endl;
+    }, "WorkerThread");
+    
+    std::cout << "After Start - Thread ID: " << t.GetId() << std::endl;
+    
+    t.Join();
+    return 0;
+}
 ```
 
 ## 相关文档

docs/api/threading/thread/getname.md

@@ -1,26 +1,47 @@
 # Thread::GetName
 
 ```cpp
-const Containers::String& GetName() const
+const Containers::String& GetName() const;
 ```
 
-获取线程的名称。该名称在调用 Start 时设置。
+返回线程的名称。线程名称在调用 `Start()` 时通过参数指定，默认为 "Thread"。返回的引用指向内部存储的 `Containers::String` 对象。
+
+线程名称主要用于调试、日志记录和性能分析工具中标识线程。
 
 **参数：** 无
 
-**返回：** `const Containers::String&` - 线程名称的引用
+**返回：** 线程名称的常量引用
 
-**复杂度：** O(1)
-
-**注意：** 在调用 Start 之前返回空字符串。
+**线程安全：** ✅
 
 **示例：**
 
 ```cpp
-Thread worker;
-worker.Start([]() {}, "ComputeThread");
-printf("Thread name: %s\n", worker.GetName().CStr());
-worker.Join();
+#include "XCEngine/Threading/Thread.h"
+#include <iostream>
+
+using namespace XCEngine::Threading;
+
+int main() {
+    Thread t1;
+    t1.Start([]() {}, "RenderingThread");
+    
+    Thread t2;
+    t2.Start([]() {}, "PhysicsThread");
+    
+    Thread t3;
+    t3.Start([]() {});
+    
+    std::cout << "Thread 1 name: " << t1.GetName().CStr() << std::endl;
+    std::cout << "Thread 2 name: " << t2.GetName().CStr() << std::endl;
+    std::cout << "Thread 3 name: " << t3.GetName().CStr() << std::endl;
+    
+    t1.Join();
+    t2.Join();
+    t3.Join();
+    
+    return 0;
+}
 ```
 
 ## 相关文档

docs/api/threading/thread/join.md

@@ -1,35 +1,45 @@
 # Thread::Join
 
 ```cpp
-void Join()
+void Join();
 ```
 
-等待线程结束并回收其资源。调用线程将被阻塞，直到目标线程完成执行。
+等待线程执行完成并回收其资源。调用 `Join()` 会阻塞当前线程，直到目标线程结束运行。如果目标线程已经结束或从未启动，则此调用立即返回。
+
+`Join()` 只能调用一次。在调用 `Join()` 后，`std::thread` 对象不再代表任何线程，不能再次调用 `Join()` 或 `Detach()`。
+
+析构函数会自动调用 `Join()`，确保线程对象销毁前等待线程结束。
+
+**注意：** 如果线程已经被分离（Detach）或已经 Join 过，调用此方法将导致未定义行为。
 
 **参数：** 无
 
 **返回：** 无
 
-**复杂度：** O(n)，n 为目标线程的执行时间
-
-**注意：**
-- 如果线程已经被分离（Detach）或已经 Join 过，调用此方法将导致未定义行为。
-- 建议在使用完 Thread 对象后始终调用 Join 或 Detach。
+**线程安全：** ❌
 
 **示例：**
 
 ```cpp
-Thread worker;
-worker.Start([]() {
-    for (int i = 0; i < 5; ++i) {
-        printf("Working...\n");
-        Thread::Sleep(100);
-    }
-}, "WorkerThread");
+#include "XCEngine/Threading/Thread.h"
+#include <iostream>
 
-printf("Main thread waiting...\n");
-worker.Join();
-printf("Worker thread finished\n");
+using namespace XCEngine::Threading;
+
+int main() {
+    Thread t;
+    t.Start([]() {
+        for (int i = 0; i < 3; ++i) {
+            std::cout << "Working... " << i << std::endl;
+            Thread::Sleep(100);
+        }
+    }, "WorkerThread");
+    
+    std::cout << "Waiting for thread to complete..." << std::endl;
+    t.Join();
+    std::cout << "Thread completed!" << std::endl;
+    return 0;
+}
 ```
 
 ## 相关文档

docs/api/threading/thread/sleep.md

@@ -1,27 +1,34 @@
 # Thread::Sleep
 
 ```cpp
-static void Sleep(uint32_t milliseconds)
+static void Sleep(uint32_t milliseconds);
 ```
 
-使当前线程休眠指定的时间。线程在休眠期间不会消耗 CPU 时间。
+静态方法，使当前线程进入休眠状态指定毫秒数。在休眠期间，线程不会消耗 CPU 时间片，让系统可以将资源分配给其他线程。
+
+实现基于 `std::this_thread::sleep_for`，使用 `std::chrono::milliseconds` 包装休眠时长。休眠精度取决于操作系统调度器的精度。
 
 **参数：**
-- `milliseconds` - 休眠时间，以毫秒为单位
+- `milliseconds` - 休眠时长，以毫秒为单位
 
 **返回：** 无
 
-**复杂度：** 取决于操作系统的调度精度，通常为 O(milliseconds)
+**线程安全：** ✅
 
 **示例：**
 
 ```cpp
-printf("Start\n");
-Thread::Sleep(1000); // 休眠1秒
-printf("After 1 second\n");
+#include "XCEngine/Threading/Thread.h"
+#include <iostream>
 
-Thread::Sleep(500); // 再休眠0.5秒
-printf("After 0.5 more seconds\n");
+using namespace XCEngine::Threading;
+
+int main() {
+    std::cout << "Sleeping for 500ms..." << std::endl;
+    Thread::Sleep(500);
+    std::cout << "Wake up!" << std::endl;
+    return 0;
+}
 ```
 
 ## 相关文档

docs/api/threading/thread/start.md

@@ -2,34 +2,44 @@
 
 ```cpp
 template<typename Func>
-void Start(Func&& func, const Containers::String& name = "Thread")
+void Start(Func&& func, const Containers::String& name = "Thread");
 ```
 
-启动线程，执行传入的可调用对象。该方法创建一个新的执行线程，立即开始运行。
+启动一个新线程并执行传入的可调用对象。该方法是模板方法，可以接受任何可调用对象，包括普通函数、Lambda 表达式、仿函数等。
+
+调用 `Start()` 后，线程立即开始执行。线程 ID 通过 `native_handle()` 获取并转换为 `uint64_t` 类型。
+
+**注意：** `Start()` 不是线程安全的，不应在同一 `Thread` 对象上并发调用。
 
 **参数：**
-- `func` - 要在线程中执行的可调用对象（lambda、函数指针、仿函数等）
-- `name` - 线程名称，用于调试和日志输出，默认值为 "Thread"
+- `func` - 要执行的线程函数，可以是任意可调用对象
+- `name` - 线程名称，默认为 "Thread"，用于调试和日志记录
 
 **返回：** 无
 
-**复杂度：** O(1)
-
-**线程安全：** 该方法不是线程安全的，不应在同一 Thread 对象上并发调用。
+**线程安全：** ❌
 
 **示例：**
 
 ```cpp
-#include "Threading/Thread.h"
+#include "XCEngine/Threading/Thread.h"
+#include <iostream>
 
-Thread worker;
-worker.Start([]() {
-    printf("Worker thread running\n");
-    Thread::Sleep(100);
-    printf("Worker thread done\n");
-}, "WorkerThread");
+using namespace XCEngine::Threading;
 
-worker.Join();
+void FreeFunction(int value) {
+    std::cout << "Free function called with: " << value << std::endl;
+}
+
+int main() {
+    Thread t;
+    t.Start(FreeFunction, "FreeFuncThread");
+    t.Start([]() {
+        std::cout << "Lambda thread executing" << std::endl;
+    }, "LambdaThread");
+    t.Join();
+    return 0;
+}
 ```
 
 ## 相关文档

docs/api/threading/thread/thread.md

@@ -6,24 +6,26 @@
 
 **头文件**: `XCEngine/Threading/Thread.h`
 
-**描述**: 线程封装类，提供跨平台线程创建和管理功能。
+**描述**: 线程类，封装 std::thread 提供命名的线程管理功能。
 
 ## 概述
 
-`Thread` 类封装了 `std::thread`，提供统一的线程管理接口，包括启动、加入、分离等操作。
+`Thread` 类封装了 `std::thread`，提供统一的线程管理接口。设计用于跨平台线程创建和管理，支持为线程指定名称便于调试和日志记录。
 
-## 公共类型
+类提供实例方法用于启动、等待（Join）和分离（Detach）线程，以及静态工具方法用于获取当前线程 ID、线程睡眠和让出 CPU 时间片。
 
-| 类型 | 描述 |
-|------|------|
-| `using Id = uint64_t` | 线程唯一标识符类型 |
+## 类型别名
+
+| 类型 | 定义 | 描述 |
+|------|------|------|
+| `Id` | `uint64_t` | 线程唯一标识符类型 |
 
 ## 公共方法
 
 | 方法 | 描述 |
 |------|------|
-| `Thread()` | 默认构造函数 |
-| `~Thread()` | 析构函数 |
+| [`Thread()`](thread.md) | 默认构造函数 |
+| [`~Thread()`](thread.md) | 析构函数 |
 | [`Start`](start.md) | 启动线程，执行传入的函数 |
 | [`Join`](join.md) | 等待线程结束 |
 | [`Detach`](detach.md) | 分离线程，使其独立运行 |
@@ -36,25 +38,28 @@
 ## 使用示例
 
 ```cpp
-#include "Threading/Thread.h"
+#include "XCEngine/Threading/Thread.h"
 
-// 创建并启动线程
-Thread thread;
-thread.Start([]() {
+using namespace XCEngine::Threading;
+
+void WorkerFunction() {
     printf("Worker thread running\n");
-}, "WorkerThread");
+}
 
-// 等待线程结束
-thread.Join();
+int main() {
+    Thread thread;
+    thread.Start(WorkerFunction, "WorkerThread");
+    thread.Join();
 
-// 使用静态方法
-Thread::Sleep(1000); // 休眠1秒
-Thread::Yield();      // 让出时间片
-auto currentId = Thread::GetCurrentId();
+    Thread::Sleep(1000);
+    Thread::Yield();
+    auto currentId = Thread::GetCurrentId();
+    return 0;
+}
 ```
 
 ## 相关文档
 
 - [Mutex](../mutex/mutex.md) - 互斥锁
 - [TaskSystem](../task-system/task-system.md) - 任务调度系统
-- [../threading/threading.md](../threading.md) - 模块总览
+- [../threading.md](../threading.md) - 模块总览

docs/api/threading/thread/yield.md

@@ -1,37 +1,47 @@
 # Thread::Yield
 
 ```cpp
-static void Yield()
+static void Yield();
 ```
 
-让出当前线程的时间片，允许操作系统调度器将 CPU 时间分配给其他就绪线程。
+静态方法，向调度器提示当前线程愿意让出 CPU 时间片，让其他线程有机会执行。此方法适用于需要 busy-wait 或自旋等待的场景。
+
+实现基于 `std::this_thread::yield()`。调度器行为取决于操作系统。
+
+**警告：** 过度使用 `Yield()` 可能导致性能问题。在多数情况下，使用 `Sleep()` 是更好的选择。
 
 **参数：** 无
 
 **返回：** 无
 
-**复杂度：** O(1)
-
-**使用场景：**
-- 在自旋等待某个条件时调用，避免浪费 CPU 周期。
-- 在长时间循环中定期让出时间片，提高其他线程的响应性。
+**线程安全：** ✅
 
 **示例：**
 
 ```cpp
-volatile bool ready = false;
+#include "XCEngine/Threading/Thread.h"
+#include <atomic>
+#include <iostream>
 
-Thread worker;
-worker.Start([]() {
-    ready = true;
-}, "WorkerThread");
+using namespace XCEngine::Threading;
 
-// 忙等待，但定期让出时间片
-while (!ready) {
-    Thread::Yield();
+int main() {
+    std::atomic<bool> ready{false};
+    
+    Thread t;
+    t.Start([&ready]() {
+        while (!ready.load()) {
+            Thread::Yield();
+        }
+        std::cout << "Worker: ready flag is set!" << std::endl;
+    }, "YieldWorker");
+    
+    Thread::Sleep(100);
+    ready.store(true);
+    
+    t.Join();
+    return 0;
 }
-
-worker.Join();
 ```
 
 ## 相关文档

docs/api/threading/threading.md

@@ -4,6 +4,8 @@
 
 **类型**: `module`
 
+**头文件**: `XCEngine/Threading/Threading.h`
+
 **描述**: XCEngine 的线程和并发模块，提供多线程编程所需的同步原语和任务系统。
 
 ## 概述