xuanchi/XCEngine
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update memory and threading API docs

Browse Source
This commit is contained in:
ssdfasd
2026-03-20 02:35:24 +08:00
parent c5b17239ca
commit fd792b7df1
103 changed files with 2485 additions and 673 deletions
Download Patch File Download Diff File Expand all files Collapse all files

19
docs/api/memory/allocator/allocator.md
View File

@@ -4,6 +4,8 @@
**类型**: `class` (abstract interface)
**头文件**: `XCEngine/Memory/Allocator.h`
**描述**: 内存分配器抽象接口，定义标准分配协议。
## 概述
@@ -16,24 +18,24 @@
| 方法 | 描述 |
|------|------|
| `Allocate` | 分配内存 |
| `Free` | 释放内存 |
| `Reallocate` | 重新分配内存 |
| [`Allocate`](allocate.md) | 分配内存 |
| [`Free`](free.md) | 释放内存 |
| [`Reallocate`](reallocate.md) | 重新分配内存 |
### 统计信息
| 方法 | 描述 |
|------|------|
| `GetTotalAllocated` | 获取已分配总字节数 |
| `GetTotalFreed` | 获取已释放总字节数 |
| `GetPeakAllocated` | 获取峰值分配字节数 |
| `GetAllocationCount` | 获取分配次数 |
| [`GetTotalAllocated`](get-total-allocated.md) | 获取已分配总字节数 |
| [`GetTotalFreed`](get-total-freed.md) | 获取已释放总字节数 |
| [`GetPeakAllocated`](get-peak-allocated.md) | 获取峰值分配字节数 |
| [`GetAllocationCount`](get-allocation-count.md) | 获取分配次数 |
### 元信息
| 方法 | 描述 |
|------|------|
| `GetName` | 获取分配器名称 |
| [`GetName`](get-name.md) | 获取分配器名称 |
## 使用示例
@@ -70,3 +72,4 @@ public:
- [MemoryManager](../manager/manager.md) - 内存管理器
- [LinearAllocator](../linear-allocator/linear-allocator.md) - 线性分配器
- [PoolAllocator](../pool-allocator/pool-allocator.md) - 内存池分配器
- [ProxyAllocator](../proxy-allocator/proxy-allocator.md) - 代理分配器

4
docs/api/memory/allocator/get-peak-allocated.md
View File

@@ -30,9 +30,9 @@ public:
void Free(void* ptr) override {
if (ptr) {
size_t size = 256; // 需要外部记录
// size 需要分配器内部记录或通过其他机制获取
::operator delete(ptr);
m_current -= size;
m_current -= 256; // 示例中硬编码
}
}

8
docs/api/memory/allocator/get-total-freed.md
View File

@@ -18,22 +18,20 @@ virtual size_t GetTotalFreed() const = 0;
#include <XCEngine/Memory/Allocator.h>
class MyAllocator : public IAllocator {
size_t m_freed = 0;
public:
void* Allocate(size_t size, size_t alignment = 0) override { return ::operator new(size); }
void Free(void* ptr) override {
if (ptr) {
size_t size = 256; // 需要外部记录
// size 需要分配器内部记录或通过其他机制获取
::operator delete(ptr);
m_freed += size;
}
}
void* Reallocate(void* ptr, size_t newSize) override { /* ... */ }
size_t GetTotalAllocated() const override { return 0; }
size_t GetTotalFreed() const override { return m_freed; }
size_t GetTotalFreed() const override { return 0; } // 示例未实际统计
size_t GetPeakAllocated() const override { return 0; }
size_t GetAllocationCount() const override { return 0; }
const char* GetName() const override { return "MyAllocator"; }
@@ -42,7 +40,7 @@ public:
MyAllocator alloc;
void* ptr = alloc.Allocate(128);
alloc.Free(ptr);
size_t freed = alloc.GetTotalFreed(); // 返回 128
size_t freed = alloc.GetTotalFreed(); // 返回 0（示例未统计）
```
## 相关文档

36
docs/api/memory/linear-allocator/constructor.md Normal file
View File

@@ -0,0 +1,36 @@
# LinearAllocator::LinearAllocator
```cpp
explicit LinearAllocator(size_t size, IAllocator* parent = nullptr);
```
构造一个线性分配器，预分配指定大小的缓冲区。如果提供了 `parent` 分配器，则使用它分配底层缓冲区；否则使用系统默认分配（`_aligned_malloc`，8 字节对齐）。
**参数：**
- `size` - 预分配的缓冲区大小（字节数）
- `parent` - 父分配器，用于分配底层缓冲区，默认为 `nullptr`（使用系统分配）
**返回：** 无
**复杂度：** O(n)，需要分配 `size` 大小的缓冲区
**示例：**
```cpp
#include <XCEngine/Memory/LinearAllocator.h>
// 使用系统分配器创建 1MB 线性分配器
LinearAllocator allocator1(1024 * 1024);
// 使用指定的父分配器
IAllocator* parent = MemoryManager::Get().GetSystemAllocator();
LinearAllocator allocator2(1024 * 1024, parent);
// 默认 8 字节对齐
void* ptr = allocator1.Allocate(256);
```
## 相关文档
- [LinearAllocator 总览](linear-allocator.md) - 返回类总览
- [IAllocator](../allocator/allocator.md) - 分配器接口

31
docs/api/memory/linear-allocator/get-allocation-count.md Normal file
View File

@@ -0,0 +1,31 @@
# LinearAllocator::GetAllocationCount
```cpp
size_t GetAllocationCount() const override;
```
返回自分配器创建以来的累计分配次数。线性分配器不支持单个块释放，始终返回 0。
**参数：** 无
**返回：** 始终返回 `0`
**复杂度：** O(1)
**示例：**
```cpp
#include <XCEngine/Memory/LinearAllocator.h>
LinearAllocator allocator(1024);
allocator.Allocate(256);
allocator.Allocate(128);
allocator.Allocate(64);
size_t count = allocator.GetAllocationCount(); // 0（不支持计数）
```
## 相关文档
- [LinearAllocator 总览](linear-allocator.md) - 返回类总览

6
docs/api/memory/linear-allocator/get-marker.md
View File

@@ -4,13 +4,13 @@
void* GetMarker() const;
```
获取当前分配位置的标记。标记是内部偏移量（`m_offset`）的快照，可用于 `SetMarker` 恢复到该位置。此方法用于实现临时分配的撤销功能。
获取当前分配位置的标记。标记是内部偏移量（`m_offset`）的快照，以 `void*` 类型返回。将此值传给 `SetMarker` 可恢复到该位置。此方法用于实现临时分配的撤销功能。
**参数：** 无
**返回：** 当前位置标记（偏移量值），类型为 `void*`
**返回：** 当前位置标记（偏移量值，类型为 `void*`）
**注意：** 返回值是偏移量数值，不是指针。将其传给 `SetMarker` 可恢复到此分配位置。
**注意：** 返回值是偏移量数值的指针表示，不是真实内存指针。将其传给 `SetMarker` 可恢复到此分配位置。
**复杂度：** O(1)

27
docs/api/memory/linear-allocator/get-name.md Normal file
View File

@@ -0,0 +1,27 @@
# LinearAllocator::GetName
```cpp
const char* GetName() const override;
```
返回分配器的名称字符串，用于调试和日志输出。
**参数：** 无
**返回：** 固定返回 `"LinearAllocator"`
**复杂度：** O(1)
**示例：**
```cpp
#include <XCEngine/Memory/LinearAllocator.h>
LinearAllocator allocator(1024);
const char* name = allocator.GetName(); // "LinearAllocator"
```
## 相关文档
- [LinearAllocator 总览](linear-allocator.md) - 返回类总览

33
docs/api/memory/linear-allocator/get-peak-allocated.md Normal file
View File

@@ -0,0 +1,33 @@
# LinearAllocator::GetPeakAllocated
```cpp
size_t GetPeakAllocated() const override;
```
返回自分配器创建以来的峰值分配字节数。对于线性分配器，这等于总容量（`m_capacity`）。
**参数：** 无
**返回：** 峰值分配字节数（等于容量）
**复杂度：** O(1)
**示例：**
```cpp
#include <XCEngine/Memory/LinearAllocator.h>
LinearAllocator allocator(1024);
size_t peak = allocator.GetPeakAllocated(); // 1024（容量）
allocator.Allocate(512);
size_t used = allocator.GetUsedSize(); // 512
// 即使未达到容量，峰值仍为容量大小
size_t peak_after = allocator.GetPeakAllocated(); // 1024
```
## 相关文档
- [LinearAllocator 总览](linear-allocator.md) - 返回类总览

36
docs/api/memory/linear-allocator/get-total-allocated.md Normal file
View File

@@ -0,0 +1,36 @@
# LinearAllocator::GetTotalAllocated
```cpp
size_t GetTotalAllocated() const override;
```
返回自分配器创建以来的累计分配字节数。对于线性分配器，这等于当前已使用的字节数（`m_offset`）。
**参数：** 无
**返回：** 累计已分配的字节数
**复杂度：** O(1)
**示例：**
```cpp
#include <XCEngine/Memory/LinearAllocator.h>
LinearAllocator allocator(1024);
size_t total1 = allocator.GetTotalAllocated(); // 0
allocator.Allocate(256);
allocator.Allocate(128);
size_t total2 = allocator.GetTotalAllocated(); // 384
allocator.Clear();
size_t total3 = allocator.GetTotalAllocated(); // 0（Clear 后重置）
```
## 相关文档
- [LinearAllocator 总览](linear-allocator.md) - 返回类总览

30
docs/api/memory/linear-allocator/get-total-freed.md Normal file
View File

@@ -0,0 +1,30 @@
# LinearAllocator::GetTotalFreed
```cpp
size_t GetTotalFreed() const override;
```
返回自分配器创建以来的累计释放字节数。线性分配器不支持单个块释放，始终返回 0。
**参数：** 无
**返回：** 始终返回 `0`
**复杂度：** O(1)
**示例：**
```cpp
#include <XCEngine/Memory/LinearAllocator.h>
LinearAllocator allocator(1024);
void* ptr = allocator.Allocate(256);
allocator.Free(ptr); // 无实际效果
size_t freed = allocator.GetTotalFreed(); // 0
```
## 相关文档
- [LinearAllocator 总览](linear-allocator.md) - 返回类总览

62
docs/api/memory/linear-allocator/linear-allocator.md
View File

@@ -4,6 +4,8 @@
**类型**: `class`
**头文件**: `XCEngine/Memory/LinearAllocator.h`
**描述**: 线性分配器，适合帧分配和临时对象。
## 概述
@@ -14,51 +16,21 @@
| 方法 | 描述 |
|------|------|
| `LinearAllocator` | 构造线性分配器 |
| `~LinearAllocator` | 析构函数，释放底层缓冲区 |
| `Allocate` | 顺序分配内存 |
| `Free` | 无效果（不支持） |
| `Reallocate` | 不支持（始终返回 nullptr） |
| `Clear` | 清空所有分配 |
| `GetMarker` | 获取当前位置标记 |
| `SetMarker` | 回滚到指定标记位置 |
| `GetUsedSize` | 获取已使用字节数 |
| `GetCapacity` | 获取总容量 |
## 构造函数
```cpp
explicit LinearAllocator(size_t size, IAllocator* parent = nullptr);
~LinearAllocator() override;
```
构造一个线性分配器，预分配指定大小的缓冲区。如果提供了 `parent` 分配器，则使用它分配底层缓冲区；否则使用系统默认分配（`_aligned_malloc`，8 字节对齐）。
**参数：**
- `size` - 预分配的缓冲区大小（字节数）
- `parent` - 父分配器，用于分配底层缓冲区，默认为 `nullptr`（使用系统分配）
**返回：** 无
**复杂度：** O(n)，需要分配 `size` 大小的缓冲区
**注意：** `Free` 和 `Reallocate` 方法无实际效果。`Free` 是空操作，`Reallocate` 始终返回 `nullptr`。
**示例：**
```cpp
#include <XCEngine/Memory/LinearAllocator.h>
// 使用系统分配器创建 1MB 线性分配器
LinearAllocator allocator1(1024 * 1024);
// 使用指定的父分配器
IAllocator* parent = MemoryManager::Get().GetSystemAllocator();
LinearAllocator allocator2(1024 * 1024, parent);
// 默认 8 字节对齐
void* ptr = allocator1.Allocate(256);
```
| [`LinearAllocator`](constructor.md) | 构造线性分配器 |
| [`~LinearAllocator`](~linear-allocator.md) | 析构函数，释放底层缓冲区 |
| [`Allocate`](allocate.md) | 顺序分配内存 |
| [`Free`](free.md) | 无效果（不支持） |
| [`Reallocate`](reallocate.md) | 不支持（始终返回 nullptr） |
| [`Clear`](clear.md) | 清空所有分配 |
| [`GetMarker`](get-marker.md) | 获取当前位置标记 |
| [`SetMarker`](set-marker.md) | 回滚到指定标记位置 |
| [`GetUsedSize`](get-used-size.md) | 获取已使用字节数 |
| [`GetCapacity`](get-capacity.md) | 获取总容量 |
| [`GetName`](get-name.md) | 获取分配器名称 |
| [`GetTotalAllocated`](get-total-allocated.md) | 获取累计分配字节数 |
| [`GetTotalFreed`](get-total-freed.md) | 获取累计释放字节数 |
| [`GetPeakAllocated`](get-peak-allocated.md) | 获取峰值分配字节数 |
| [`GetAllocationCount`](get-allocation-count.md) | 获取分配次数 |
## 相关文档

2
docs/api/memory/linear-allocator/~linear-allocator.md
View File

@@ -4,7 +4,7 @@
~LinearAllocator() override;
```
销毁线性分配器，释放预分配的缓冲区。如果提供了 `parent` 分配器，则使用它释放缓冲区；否则使用系统默认释放（`::operator delete`）。
销毁线性分配器，释放预分配的缓冲区。如果提供了 `parent` 分配器，则使用它释放缓冲区；否则使用系统默认释放（`_aligned_free`）。
**参数：** 无

22
docs/api/memory/manager/manager.md
View File

@@ -4,6 +4,8 @@
**类型**: `class` (singleton)
**头文件**: `XCEngine/Memory/MemoryManager.h`
**描述**: 全局内存管理器单例，提供系统分配器和各种专用分配器的创建。
## 概述
@@ -14,21 +16,21 @@
| 方法 | 描述 |
|------|------|
| `Get` | 获取单例实例 |
| [`Get`](get.md) | 获取单例实例 |
## 公共方法
| 方法 | 描述 |
|------|------|
| `Initialize` | 初始化内存管理器 |
| `Shutdown` | 关闭内存管理器 |
| `GetSystemAllocator` | 获取系统默认分配器 |
| `CreateLinearAllocator` | 创建线性分配器 |
| `CreatePoolAllocator` | 创建内存池分配器 |
| `CreateProxyAllocator` | 创建代理分配器 |
| `SetTrackAllocations` | 设置是否跟踪分配 |
| `DumpMemoryLeaks` | 输出内存泄漏报告 |
| `GenerateMemoryReport` | 生成内存使用报告 |
| [`Initialize`](initialize.md) | 初始化内存管理器 |
| [`Shutdown`](shutdown.md) | 关闭内存管理器 |
| [`GetSystemAllocator`](get-system-allocator.md) | 获取系统默认分配器 |
| [`CreateLinearAllocator`](create-linear-allocator.md) | 创建线性分配器 |
| [`CreatePoolAllocator`](create-pool-allocator.md) | 创建内存池分配器 |
| [`CreateProxyAllocator`](create-proxy-allocator.md) | 创建代理分配器 |
| [`SetTrackAllocations`](set-track-allocations.md) | 设置是否跟踪分配 |
| [`DumpMemoryLeaks`](dump-memory-leaks.md) | 输出内存泄漏报告 |
| [`GenerateMemoryReport`](generate-memory-report.md) | 生成内存使用报告 |
## 宏定义

2
docs/api/memory/memory.md
View File

@@ -4,6 +4,8 @@
**类型**: `module`
**头文件**: `XCEngine/Memory/Memory.h`
**描述**: XCEngine 的内存管理模块，提供多种内存分配器实现。
## 概述

32
docs/api/memory/memorymanager/createlinearallocator.md Normal file
View File

@@ -0,0 +1,32 @@
# MemoryManager::CreateLinearAllocator
```cpp
std::unique_ptr<LinearAllocator> CreateLinearAllocator(size_t size);
```
创建并返回一个新的 LinearAllocator 实例，使用系统分配器作为底层。返回的 `unique_ptr` 管理分配器生命周期。
**参数：**
- `size` - 分配器缓冲区大小（字节）
**返回：** LinearAllocator 的 unique_ptr
**复杂度：** O(1)
**示例：**
```cpp
#include <XCEngine/Memory/MemoryManager.h>
auto linear = MemoryManager::Get().CreateLinearAllocator(1024 * 1024);
void* ptr = linear->Allocate(256);
void* marker = linear->GetMarker();
linear->Allocate(128);
linear->SetMarker(marker);
linear->Clear();
```
## 相关文档
- [MemoryManager 总览](memorymanager.md) - 返回类总览
- [LinearAllocator](../linear-allocator/linear-allocator.md) - 线性分配器

37
docs/api/memory/memorymanager/createpoolallocator.md Normal file
View File

@@ -0,0 +1,37 @@
# MemoryManager::CreatePoolAllocator
```cpp
std::unique_ptr<PoolAllocator> CreatePoolAllocator(size_t blockSize, size_t count);
```
创建并返回一个新的 PoolAllocator 实例，使用系统分配器作为底层。返回的 `unique_ptr` 管理分配器生命周期。
**参数：**
- `blockSize` - 每个内存块的大小（字节）
- `count` - 内存池中块的数量
**返回：** PoolAllocator 的 unique_ptr
**复杂度：** O(blockSize * count)（需要预分配所有块）
**示例：**
```cpp
#include <XCEngine/Memory/MemoryManager.h>
struct Particle {
float x, y, z;
float life;
};
auto pool = MemoryManager::Get().CreatePoolAllocator(sizeof(Particle), 1000);
void* block = pool->Allocate();
auto* p = new (block) Particle{1.0f, 2.0f, 3.0f, 5.0f};
p->~Particle();
pool->Free(block);
```
## 相关文档
- [MemoryManager 总览](memorymanager.md) - 返回类总览
- [PoolAllocator](../pool-allocator/pool-allocator.md) - 内存池分配器

36
docs/api/memory/memorymanager/createproxyallocator.md Normal file
View File

@@ -0,0 +1,36 @@
# MemoryManager::CreateProxyAllocator
```cpp
std::unique_ptr<ProxyAllocator> CreateProxyAllocator(const char* name);
```
创建并返回一个新的 ProxyAllocator 实例，包装系统分配器并使用指定名称。返回的 `unique_ptr` 管理分配器生命周期。
**参数：**
- `name` - 代理分配器的名称
**返回：** ProxyAllocator 的 unique_ptr
**复杂度：** O(1)
**示例：**
```cpp
#include <XCEngine/Memory/MemoryManager.h>
auto proxy = MemoryManager::Get().CreateProxyAllocator("FrameData");
void* ptr = proxy->Allocate(1024);
void* ptr2 = proxy->Allocate(512);
const auto& stats = proxy->GetStats();
printf("Peak: %zu bytes, Count: %zu\n",
stats.peakAllocated, stats.allocationCount);
proxy->Free(ptr);
proxy->Free(ptr2);
```
## 相关文档
- [MemoryManager 总览](memorymanager.md) - 返回类总览
- [ProxyAllocator](../proxy-allocator/proxy-allocator.md) - 代理分配器

31
docs/api/memory/memorymanager/dumpmemoryleaks.md Normal file
View File

@@ -0,0 +1,31 @@
# MemoryManager::DumpMemoryLeaks
```cpp
void DumpMemoryLeaks();
```
输出当前未释放的内存分配信息。如果启用了内存跟踪，此方法会遍历所有记录并报告疑似泄漏的分配。应在程序退出前调用，以便发现资源泄漏。
**参数：** 无
**返回：** 无
**复杂度：** O(n)
**示例：**
```cpp
#include <XCEngine/Memory/MemoryManager.h>
MemoryManager::Get().Initialize();
// ... 程序运行 ...
// 程序退出前检查泄漏
MemoryManager::Get().DumpMemoryLeaks();
MemoryManager::Get().Shutdown();
```
## 相关文档
- [MemoryManager 总览](memorymanager.md) - 返回类总览

37
docs/api/memory/memorymanager/generatememoryreport.md Normal file
View File

@@ -0,0 +1,37 @@
# MemoryManager::GenerateMemoryReport
```cpp
void GenerateMemoryReport();
```
生成并输出当前内存使用情况的详细报告。报告内容包括各分配器的统计信息、峰值使用量、分配次数等。应在启用内存跟踪后调用。
**参数：** 无
**返回：** 无
**复杂度：** O(n)
**示例：**
```cpp
#include <XCEngine/Memory/MemoryManager.h>
MemoryManager::Get().Initialize();
auto proxy = MemoryManager::Get().CreateProxyAllocator("GameFrame");
proxy->Allocate(1024 * 1024);
proxy->Allocate(512 * 1024);
// 生成内存报告
MemoryManager::Get().GenerateMemoryReport();
proxy->Free(proxy->Allocate(256 * 1024));
MemoryManager::Get().GenerateMemoryReport();
MemoryManager::Get().Shutdown();
```
## 相关文档
- [MemoryManager 总览](memorymanager.md) - 返回类总览

39
docs/api/memory/memorymanager/get.md Normal file
View File

@@ -0,0 +1,39 @@
# MemoryManager::Get
```cpp
static MemoryManager& Get();
```
获取 MemoryManager 单例实例。如果尚未创建则内部构造。此方法是获取内存管理器实例的唯一途径。
**参数：** 无
**返回：** MemoryManager 单例引用
**复杂度：** O(1)
**示例：**
```cpp
#include <XCEngine/Memory/MemoryManager.h>
// 获取单例
MemoryManager& manager = MemoryManager::Get();
// 初始化
manager.Initialize();
// 访问系统分配器
IAllocator* sysAlloc = manager.GetSystemAllocator();
// 关闭
manager.Shutdown();
// 多次调用返回同一实例
MemoryManager& manager2 = MemoryManager::Get();
// manager == manager2 为 true
```
## 相关文档
- [MemoryManager 总览](memorymanager.md) - 返回类总览

27
docs/api/memory/memorymanager/getsystemallocator.md Normal file
View File

@@ -0,0 +1,27 @@
# MemoryManager::GetSystemAllocator
```cpp
IAllocator* GetSystemAllocator();
```
获取系统默认分配器。该分配器使用标准 C 库的 `std::malloc` 和平台特定的对齐分配函数（如 Windows 的 `_aligned_malloc`）作为后端，适用于通用内存分配场景。
**参数：** 无
**返回：** 系统分配器指针
**复杂度：** O(1)
**示例：**
```cpp
#include <XCEngine/Memory/MemoryManager.h>
IAllocator* sysAlloc = MemoryManager::Get().GetSystemAllocator();
void* ptr = sysAlloc->Allocate(1024);
sysAlloc->Free(ptr);
```
## 相关文档
- [MemoryManager 总览](memorymanager.md) - 返回类总览

33
docs/api/memory/memorymanager/initialize.md Normal file
View File

@@ -0,0 +1,33 @@
# MemoryManager::Initialize
```cpp
void Initialize();
```
初始化内存管理器。创建系统默认分配器，设置内存跟踪标志。应在程序启动早期调用，且仅可调用一次。
**参数：** 无
**返回：** 无
**复杂度：** O(n)
**示例：**
```cpp
#include <XCEngine/Memory/MemoryManager.h>
int main() {
// 程序启动时初始化
MemoryManager::Get().Initialize();
// 使用内存系统...
MemoryManager::Get().Shutdown();
return 0;
}
```
## 相关文档
- [MemoryManager 总览](memorymanager.md) - 返回类总览

85
docs/api/memory/memorymanager/memorymanager.md Normal file
View File

@@ -0,0 +1,85 @@
# MemoryManager
**命名空间**: `XCEngine::Memory`
**类型**: `class` (singleton)
**描述**: 全局内存管理器单例，提供系统分配器和各种专用分配器的创建与管理。
## 概述
`MemoryManager` 是 XCEngine 内存管理系统的核心单例。它负责维护系统分配器，提供分配器工厂方法，并支持内存泄漏检测和报告。
## 单例访问
| 方法 | 描述 |
|------|------|
| [`Get`](get.md) | 获取单例实例 |
## 公共方法
| 方法 | 描述 |
|------|------|
| [`Initialize`](initialize.md) | 初始化内存管理器 |
| [`Shutdown`](shutdown.md) | 关闭内存管理器 |
| [`GetSystemAllocator`](getsystemallocator.md) | 获取系统默认分配器 |
| [`CreateLinearAllocator`](createlinearallocator.md) | 创建线性分配器 |
| [`CreatePoolAllocator`](createpoolallocator.md) | 创建内存池分配器 |
| [`CreateProxyAllocator`](createproxyallocator.md) | 创建代理分配器 |
| [`SetTrackAllocations`](settrackallocations.md) | 设置是否跟踪分配 |
| [`DumpMemoryLeaks`](dumpmemoryleaks.md) | 输出内存泄漏报告 |
| [`GenerateMemoryReport`](generatememoryreport.md) | 生成内存使用报告 |
## 宏定义
### XE_ALLOC
```cpp
#define XE_ALLOC(allocator, size, ...) allocator->Allocate(size, ##__VA_ARGS__)
```
内存分配宏。
### XE_FREE
```cpp
#define XE_FREE(allocator, ptr) allocator->Free(ptr)
```
内存释放宏。
## 使用示例
```cpp
#include <XCEngine/Memory/MemoryManager.h>
// 初始化
MemoryManager::Get().Initialize();
// 获取系统分配器
IAllocator* sysAlloc = MemoryManager::Get().GetSystemAllocator();
// 创建专用分配器
auto linearAlloc = MemoryManager::Get().CreateLinearAllocator(1024 * 1024);
auto poolAlloc = MemoryManager::Get().CreatePoolAllocator(sizeof(MyObject), 1000);
auto proxyAlloc = MemoryManager::Get().CreateProxyAllocator("GameFrame");
// 使用宏分配
void* ptr = XE_ALLOC(proxyAlloc, 256);
XE_FREE(proxyAlloc, ptr);
// 跟踪内存
MemoryManager::Get().SetTrackAllocations(true);
MemoryManager::Get().GenerateMemoryReport();
// 关闭
MemoryManager::Get().Shutdown();
```
## 相关文档
- [Memory 模块总览](../memory.md) - 返回模块总览
- [IAllocator](../allocator/allocator.md) - 分配器接口
- [LinearAllocator](../linear-allocator/linear-allocator.md) - 线性分配器
- [PoolAllocator](../pool-allocator/pool-allocator.md) - 内存池分配器
- [ProxyAllocator](../proxy-allocator/proxy-allocator.md) - 代理分配器

35
docs/api/memory/memorymanager/settrackallocations.md Normal file
View File

@@ -0,0 +1,35 @@
# MemoryManager::SetTrackAllocations
```cpp
void SetTrackAllocations(bool track);
```
设置是否启用内存分配跟踪。启用后系统会记录所有分配操作，用于生成内存报告和泄漏检测。
**参数：**
- `track` - true 启用跟踪，false 禁用跟踪
**返回：** 无
**复杂度：** O(1)
**示例：**
```cpp
#include <XCEngine/Memory/MemoryManager.h>
MemoryManager::Get().Initialize();
// 禁用跟踪（提升性能）
MemoryManager::Get().SetTrackAllocations(false);
// ... 大量内存操作 ...
// 重新启用跟踪进行分析
MemoryManager::Get().SetTrackAllocations(true);
MemoryManager::Get().GenerateMemoryReport();
```
## 相关文档
- [MemoryManager 总览](memorymanager.md) - 返回类总览

35
docs/api/memory/memorymanager/shutdown.md Normal file
View File

@@ -0,0 +1,35 @@
# MemoryManager::Shutdown
```cpp
void Shutdown();
```
关闭内存管理器。执行内存泄漏检测报告，释放系统分配器。应在程序退出前调用。
**参数：** 无
**返回：** 无
**复杂度：** O(n)
**示例：**
```cpp
#include <XCEngine/Memory/MemoryManager.h>
int main() {
MemoryManager::Get().Initialize();
// ... 游戏主循环 ...
// 程序退出前关闭
MemoryManager::Get().DumpMemoryLeaks();
MemoryManager::Get().Shutdown();
return 0;
}
```
## 相关文档
- [MemoryManager 总览](memorymanager.md) - 返回类总览

40
docs/api/memory/pool-allocator/constructor.md Normal file
View File

@@ -0,0 +1,40 @@
# PoolAllocator::PoolAllocator
```cpp
PoolAllocator(size_t blockSize, size_t poolSize, size_t alignment = 8);
```
构造内存池分配器，预分配 `poolSize` 个大小为 `blockSize` 字节的内存块。内存块按 `alignment` 对齐（默认 8 字节）。内部维护一个空闲链表来管理分配。
**参数：**
- `blockSize` - 每个内存块的大小（字节）
- `poolSize` - 内存池中总块数
- `alignment` - 对齐要求，默认为 8 字节
**返回：** 无
**复杂度：** O(n)，需要预分配所有块
**示例：**
```cpp
#include <XCEngine/Memory/PoolAllocator.h>
struct Particle {
float x, y, z;
float vx, vy, vz;
float life;
};
// 创建一个能容纳 1000 个 Particle 的内存池，16 字节对齐
PoolAllocator pool(sizeof(Particle), 1000, alignof(Particle));
size_t blockSize = pool.GetBlockSize(); // sizeof(Particle)
size_t total = pool.GetTotalBlockCount(); // 1000
size_t free = pool.GetFreeBlockCount(); // 1000
```
## 相关文档
- [PoolAllocator 总览](pool-allocator.md) - 返回类总览
- [`~PoolAllocator`](~pool-allocator.md) - 析构函数

40
docs/api/memory/pool-allocator/get-allocation-count.md Normal file
View File

@@ -0,0 +1,40 @@
# PoolAllocator::GetAllocationCount
```cpp
size_t GetAllocationCount() const override;
```
返回当前已分配块的数量。计算公式：`m_totalBlocks - m_freeBlocks`。
**参数：** 无
**返回：** 当前已分配块的数量
**复杂度：** O(1)
**示例：**
```cpp
#include <XCEngine/Memory/PoolAllocator.h>
PoolAllocator pool(sizeof(int), 100);
size_t count = pool.GetAllocationCount(); // 0
void* blocks[10];
for (int i = 0; i < 10; ++i) {
blocks[i] = pool.Allocate();
}
count = pool.GetAllocationCount(); // 10
for (int i = 0; i < 5; ++i) {
pool.Free(blocks[i]);
}
count = pool.GetAllocationCount(); // 5
```
## 相关文档
- [PoolAllocator 总览](pool-allocator.md) - 返回类总览

2
docs/api/memory/pool-allocator/get-block-size.md
View File

@@ -4,7 +4,7 @@
size_t GetBlockSize() const;
```
返回内存池中每个内存块的大小。此值在构造时确定，之后保持不变。
返回内存池中每个内存块的大小。此值在构造时确定，之后保持不变。实际分配的内存可能按对齐要求调整，但块大小返回原始请求值。
**参数：** 无

29
docs/api/memory/pool-allocator/get-name.md Normal file
View File

@@ -0,0 +1,29 @@
# PoolAllocator::GetName
```cpp
const char* GetName() const override;
```
返回分配器的名称字符串 "PoolAllocator"。用于调试和日志记录。
**参数：** 无
**返回：** 固定返回 `"PoolAllocator"` 字符串
**复杂度：** O(1)
**示例：**
```cpp
#include <XCEngine/Memory/PoolAllocator.h>
#include <iostream>
PoolAllocator pool(sizeof(int), 100);
const char* name = pool.GetName(); // "PoolAllocator"
std::cout << "Allocator: " << name << std::endl;
```
## 相关文档
- [PoolAllocator 总览](pool-allocator.md) - 返回类总览

33
docs/api/memory/pool-allocator/get-peak-allocated.md Normal file
View File

@@ -0,0 +1,33 @@
# PoolAllocator::GetPeakAllocated
```cpp
size_t GetPeakAllocated() const override;
```
返回峰值分配的内存总量（字节）。由于池在构造时预分配所有块，峰值即为 `m_totalBlocks * m_blockSize`。
**参数：** 无
**返回：** 内存池总容量（字节）
**复杂度：** O(1)
**示例：**
```cpp
#include <XCEngine/Memory/PoolAllocator.h>
PoolAllocator pool(sizeof(int), 100);
size_t peak = pool.GetPeakAllocated(); // 100 * sizeof(int)
// 即使分配了部分块，峰值仍然是总容量
void* block1 = pool.Allocate();
void* block2 = pool.Allocate();
size_t current = pool.GetTotalAllocated(); // 2 * sizeof(int)
peak = pool.GetPeakAllocated(); // 100 * sizeof(int)
```
## 相关文档
- [PoolAllocator 总览](pool-allocator.md) - 返回类总览

33
docs/api/memory/pool-allocator/get-total-allocated.md Normal file
View File

@@ -0,0 +1,33 @@
# PoolAllocator::GetTotalAllocated
```cpp
size_t GetTotalAllocated() const override;
```
返回当前已分配的内存总量（字节）。计算公式：`(m_totalBlocks - m_freeBlocks) * m_blockSize`。
**参数：** 无
**返回：** 当前已分配块的字节数
**复杂度：** O(1)
**示例：**
```cpp
#include <XCEngine/Memory/PoolAllocator.h>
PoolAllocator pool(sizeof(int), 100);
size_t allocated = pool.GetTotalAllocated(); // 0
void* block = pool.Allocate();
allocated = pool.GetTotalAllocated(); // sizeof(int)
pool.Free(block);
allocated = pool.GetTotalAllocated(); // 0
```
## 相关文档
- [PoolAllocator 总览](pool-allocator.md) - 返回类总览

33
docs/api/memory/pool-allocator/get-total-freed.md Normal file
View File

@@ -0,0 +1,33 @@
# PoolAllocator::GetTotalFreed
```cpp
size_t GetTotalFreed() const override;
```
返回当前空闲的内存总量（字节）。计算公式：`m_freeBlocks * m_blockSize`。
**参数：** 无
**返回：** 当前空闲块的字节数
**复杂度：** O(1)
**示例：**
```cpp
#include <XCEngine/Memory/PoolAllocator.h>
PoolAllocator pool(sizeof(int), 100);
size_t freed = pool.GetTotalFreed(); // 100 * sizeof(int)
void* block = pool.Allocate();
freed = pool.GetTotalFreed(); // 99 * sizeof(int)
pool.Free(block);
freed = pool.GetTotalFreed(); // 100 * sizeof(int)
```
## 相关文档
- [PoolAllocator 总览](pool-allocator.md) - 返回类总览

25
docs/api/memory/pool-allocator/pool-allocator.md
View File

@@ -4,6 +4,8 @@
**类型**: `class`
**头文件**: `XCEngine/Memory/PoolAllocator.h`
**描述**: 内存池分配器，预分配固定大小的内存块池。
## 概述
@@ -14,15 +16,20 @@
| 方法 | 描述 |
|------|------|
| `PoolAllocator` | 构造内存池分配器 |
| `~PoolAllocator` | 析构函数，释放整个内存池 |
| `Allocate` | 分配一个内存块 |
| `Free` | 释放内存块回空闲链表 |
| `Reallocate` | 不支持（始终返回 nullptr） |
| `Contains` | 检查指针是否属于此池 |
| `GetBlockSize` | 获取块大小 |
| `GetFreeBlockCount` | 获取空闲块数量 |
| `GetTotalBlockCount` | 获取总块数 |
| [`PoolAllocator`](constructor.md) | 构造内存池分配器 |
| [`~PoolAllocator`](~pool-allocator.md) | 析构函数，释放整个内存池 |
| [`Allocate`](allocate.md) | 分配一个内存块 |
| [`Free`](free.md) | 释放内存块回空闲链表 |
| [`Reallocate`](reallocate.md) | 不支持（始终返回 nullptr） |
| [`Contains`](contains.md) | 检查指针是否属于此池 |
| [`GetBlockSize`](get-block-size.md) | 获取块大小 |
| [`GetFreeBlockCount`](get-free-block-count.md) | 获取空闲块数量 |
| [`GetTotalBlockCount`](get-total-block-count.md) | 获取总块数 |
| [`GetName`](get-name.md) | 获取分配器名称 |
| [`GetTotalAllocated`](get-total-allocated.md) | 获取当前已分配内存 |
| [`GetTotalFreed`](get-total-freed.md) | 获取当前空闲内存 |
| [`GetPeakAllocated`](get-peak-allocated.md) | 获取峰值分配内存 |
| [`GetAllocationCount`](get-allocation-count.md) | 获取当前分配块数量 |
## 构造函数

8
docs/api/memory/proxy-allocator/free.md
View File

@@ -4,9 +4,7 @@
void Free(void* ptr) override;
```
释放内存并记录统计。调用转发到底层分配器，同时更新统计信息：递增 `totalFreed`（累加当前 `allocationCount`），并递减 `allocationCount`。
**注意：** `totalFreed` 累加的是每次释放时的 `allocationCount`（分配计数）而非实际字节大小。这是一个简化的实现，用于追踪释放操作次数。
释放内存并记录统计。调用转发到底层分配器，同时更新统计信息：递增 `totalFreed`（累加释放字节数），并递减 `allocationCount`。
**参数：**
- `ptr` - 指向要释放的内存块
@@ -31,9 +29,9 @@ proxy.Free(p1);
proxy.Free(p2);
const auto& stats = proxy.GetStats();
// totalFreed 累加了每次释放时的 allocationCount（次数，非字节）
// totalFreed 累加了释放的字节数
// allocationCount 最终为 0
printf("Total allocated: %zu bytes, Freed count: %zu, Current count: %zu\n",
printf("Total allocated: %zu bytes, Freed: %zu bytes, Current count: %zu\n",
stats.totalAllocated, stats.totalFreed, stats.allocationCount);
```

37
docs/api/memory/proxy-allocator/get-allocation-count.md Normal file
View File

@@ -0,0 +1,37 @@
# ProxyAllocator::GetAllocationCount
```cpp
size_t GetAllocationCount() const override;
```
获取当前未释放的分配次数。
**参数：** 无
**返回：** 当前未释放的分配次数
**线程安全：** ✅
**复杂度：** O(1)
**示例：**
```cpp
#include <XCEngine/Memory/MemoryManager.h>
#include <XCEngine/Memory/ProxyAllocator.h>
IAllocator* sysAlloc = MemoryManager::Get().GetSystemAllocator();
ProxyAllocator proxy(sysAlloc, "TrackedAlloc");
proxy.Allocate(100);
proxy.Allocate(200);
void* p = proxy.Allocate(300);
proxy.Free(p);
size_t count = proxy.GetAllocationCount();
printf("Current allocation count: %zu\n", count);
```
## 相关文档
- [ProxyAllocator 总览](proxy-allocator.md) - 返回类总览

32
docs/api/memory/proxy-allocator/get-name.md Normal file
View File

@@ -0,0 +1,32 @@
# ProxyAllocator::GetName
```cpp
const char* GetName() const override;
```
获取分配器的名称字符串。
**参数：** 无
**返回：** 分配器名称字符串
**线程安全：** ✅
**复杂度：** O(1)
**示例：**
```cpp
#include <XCEngine/Memory/MemoryManager.h>
#include <XCEngine/Memory/ProxyAllocator.h>
IAllocator* sysAlloc = MemoryManager::Get().GetSystemAllocator();
ProxyAllocator proxy(sysAlloc, "TrackedAlloc");
const char* name = proxy.GetName();
printf("Allocator name: %s\n", name);
```
## 相关文档
- [ProxyAllocator 总览](proxy-allocator.md) - 返回类总览

37
docs/api/memory/proxy-allocator/get-peak-allocated.md Normal file
View File

@@ -0,0 +1,37 @@
# ProxyAllocator::GetPeakAllocated
```cpp
size_t GetPeakAllocated() const override;
```
获取峰值分配的字节数。
**参数：** 无
**返回：** 峰值分配的字节数
**线程安全：** ✅
**复杂度：** O(1)
**示例：**
```cpp
#include <XCEngine/Memory/MemoryManager.h>
#include <XCEngine/Memory/ProxyAllocator.h>
IAllocator* sysAlloc = MemoryManager::Get().GetSystemAllocator();
ProxyAllocator proxy(sysAlloc, "TrackedAlloc");
proxy.Allocate(100);
proxy.Allocate(200);
proxy.Free(proxy.Allocate(50));
proxy.Free(proxy.Allocate(100));
size_t peakAllocated = proxy.GetPeakAllocated();
printf("Peak allocated: %zu bytes\n", peakAllocated);
```
## 相关文档
- [ProxyAllocator 总览](proxy-allocator.md) - 返回类总览

35
docs/api/memory/proxy-allocator/get-total-allocated.md Normal file
View File

@@ -0,0 +1,35 @@
# ProxyAllocator::GetTotalAllocated
```cpp
size_t GetTotalAllocated() const override;
```
获取累计分配的字节数。
**参数：** 无
**返回：** 累计分配的字节数
**线程安全：** ✅
**复杂度：** O(1)
**示例：**
```cpp
#include <XCEngine/Memory/MemoryManager.h>
#include <XCEngine/Memory/ProxyAllocator.h>
IAllocator* sysAlloc = MemoryManager::Get().GetSystemAllocator();
ProxyAllocator proxy(sysAlloc, "TrackedAlloc");
proxy.Allocate(100);
proxy.Allocate(200);
size_t totalAllocated = proxy.GetTotalAllocated();
printf("Total allocated: %zu bytes\n", totalAllocated);
```
## 相关文档
- [ProxyAllocator 总览](proxy-allocator.md) - 返回类总览

35
docs/api/memory/proxy-allocator/get-total-freed.md Normal file
View File

@@ -0,0 +1,35 @@
# ProxyAllocator::GetTotalFreed
```cpp
size_t GetTotalFreed() const override;
```
获取累计释放的字节数。
**参数：** 无
**返回：** 累计释放的字节数
**线程安全：** ✅
**复杂度：** O(1)
**示例：**
```cpp
#include <XCEngine/Memory/MemoryManager.h>
#include <XCEngine/Memory/ProxyAllocator.h>
IAllocator* sysAlloc = MemoryManager::Get().GetSystemAllocator();
ProxyAllocator proxy(sysAlloc, "TrackedAlloc");
void* p1 = proxy.Allocate(100);
proxy.Free(p1);
size_t totalFreed = proxy.GetTotalFreed();
printf("Total freed: %zu bytes\n", totalFreed);
```
## 相关文档
- [ProxyAllocator 总览](proxy-allocator.md) - 返回类总览

17
docs/api/memory/proxy-allocator/proxy-allocator.md
View File

@@ -4,6 +4,8 @@
**类型**: `class`
**头文件**: `XCEngine/Memory/ProxyAllocator.h`
**描述**: 代理分配器，用于统计和跟踪底层分配器的分配情况。
## 概述
@@ -14,12 +16,15 @@
| 方法 | 描述 |
|------|------|
| `ProxyAllocator` | 构造代理分配器 |
| `~ProxyAllocator` | 析构函数 |
| `Allocate` | 分配内存并记录统计 |
| `Free` | 释放内存并记录统计 |
| `Reallocate` | 转发到底层分配器 |
| `GetStats` | 获取详细统计信息 |
| [`Allocate`](allocate.md) | 分配内存并记录统计 |
| [`Free`](free.md) | 释放内存并记录统计 |
| [`Reallocate`](reallocate.md) | 转发到底层分配器 |
| [`GetStats`](get-stats.md) | 获取详细统计信息 |
| [`GetTotalAllocated`](get-total-allocated.md) | 获取累计分配字节数 |
| [`GetTotalFreed`](get-total-freed.md) | 获取累计释放字节数 |
| [`GetPeakAllocated`](get-peak-allocated.md) | 获取峰值分配字节数 |
| [`GetAllocationCount`](get-allocation-count.md) | 获取分配次数 |
| [`GetName`](get-name.md) | 获取分配器名称 |
## 构造函数

2
docs/api/memory/proxy-allocator/reallocate.md
View File

@@ -4,7 +4,7 @@
void* Reallocate(void* ptr, size_t newSize) override;
```
重新分配内存。调用转发到底层分配器，不记录额外统计信息（底层分配器的返回值直接返回）。此方法线程安全，内部使用互斥锁保护。
重新分配内存。调用转发到底层分配器，同时更新统计信息（峰值分配和当前分配量）。此方法线程安全，内部使用互斥锁保护。
**参数：**
- `ptr` - 现有内存块指针

37
docs/api/memory/proxy-allocator/~proxy-allocator.md
View File

@@ -1,37 +0,0 @@
# ProxyAllocator::~ProxyAllocator
```cpp
~ProxyAllocator() override;
```
销毁代理分配器。此析构函数不释放底层分配器，只清理代理分配器自身的统计信息（互斥锁等）。底层分配器由创建者负责管理。
**参数：** 无
**返回：** 无
**注意：** 析构函数不释放底层分配器。如果需要释放底层分配器，应先调用 `Shutdown` 或显式销毁底层分配器。
**示例：**
```cpp
#include <XCEngine/Memory/MemoryManager.h>
#include <XCEngine/Memory/ProxyAllocator.h>
{
MemoryManager::Get().Initialize();
IAllocator* sysAlloc = MemoryManager::Get().GetSystemAllocator();
auto proxy = MemoryManager::Get().CreateProxyAllocator("TrackedAlloc");
proxy->Allocate(1024);
// proxy 超出作用域时自动销毁
// 底层 sysAlloc 仍有效
MemoryManager::Get().Shutdown();
}
```
## 相关文档
- [ProxyAllocator 总览](proxy-allocator.md) - 返回类总览

40
docs/api/threading/lambdatask/execute.md Normal file
View File

@@ -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) - 基类方法文档

2
docs/api/threading/lambdatask/lambdatask.md
View File

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

2
docs/api/threading/mutex/lock.md
View File

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

43
docs/api/threading/mutex/lock_const.md Normal file
View File

@@ -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) - 返回类总览

49
docs/api/threading/mutex/mutex.md
View File

@@ -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;
}
```

36
docs/api/threading/mutex/try_lock.md Normal file
View File

@@ -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) - 返回类总览

41
docs/api/threading/mutex/try_lock_const.md Normal file
View File

@@ -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) - 返回类总览

2
docs/api/threading/mutex/trylock.md
View File

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

2
docs/api/threading/mutex/unlock.md
View File

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

34
docs/api/threading/mutex/unlock_const.md Normal file
View File

@@ -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) - 返回类总览

35
docs/api/threading/readwritelock/constructor.md Normal file
View File

@@ -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) - 释放写锁

40
docs/api/threading/readwritelock/destructor.md Normal file
View File

@@ -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) - 释放写锁

11
docs/api/threading/readwritelock/readlock.md
View File

@@ -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) - 释放读锁

9
docs/api/threading/readwritelock/readunlock.md
View File

@@ -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) - 获取读锁

70
docs/api/threading/readwritelock/readwritelock.md
View File

@@ -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) - 释放写锁

10
docs/api/threading/readwritelock/writelock.md
View File

@@ -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) - 释放写锁

15
docs/api/threading/readwritelock/writeunlock.md
View File

@@ -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) - 获取写锁

2
docs/api/threading/spinlock/lock.md
View File

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

31
docs/api/threading/spinlock/lock_1.md Normal file
View File

@@ -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) - 返回类总览

5
docs/api/threading/spinlock/spinlock.md
View File

@@ -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) - 模块总览

32
docs/api/threading/spinlock/try_lock.md Normal file
View File

@@ -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) - 返回类总览

31
docs/api/threading/spinlock/unlock_1.md Normal file
View File

@@ -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) - 返回类总览

90
docs/api/threading/task-group/add-dependency.md Normal file
View File

@@ -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);
```

55
docs/api/threading/task-group/add-task-callback.md Normal file
View File

@@ -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) - 任务优先级说明

62
docs/api/threading/task-group/add-task.md Normal file
View File

@@ -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) - 返回类总览

44
docs/api/threading/task-group/adddependency.md
View File

@@ -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) - 返回类总览

60
docs/api/threading/task-group/addtask.md
View File

@@ -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) - 返回类总览

52
docs/api/threading/task-group/cancel.md
View File

@@ -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));
```
## 相关文档

50
docs/api/threading/task-group/get-progress.md Normal file
View File

@@ -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) - 检查是否完成

40
docs/api/threading/task-group/getprogress.md
View File

@@ -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) - 检查是否完成

50
docs/api/threading/task-group/is-complete.md Normal file
View File

@@ -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) - 获取进度百分比

38
docs/api/threading/task-group/iscomplete.md
View File

@@ -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) - 获取完成进度

82
docs/api/threading/task-group/set-complete-callback.md Normal file
View File

@@ -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);
```

36
docs/api/threading/task-group/setcompletecallback.md
View File

@@ -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) - 返回类总览

92
docs/api/threading/task-group/task-group.md
View File

@@ -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) - 任务调度系统

59
docs/api/threading/task-group/task-priority.md Normal file
View File

@@ -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) - 任务接口基类

89
docs/api/threading/task-group/wait-for.md Normal file
View File

@@ -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);
```

51
docs/api/threading/task-group/wait.md
View File

@@ -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) - 带超时的等待

39
docs/api/threading/task-group/waitfor.md
View File

@@ -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) - 无超时等待

2
docs/api/threading/task-system/createtaskgroup.md
View File

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

2
docs/api/threading/task-system/destroytaskgroup.md
View File

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

2
docs/api/threading/task-system/getworkerthreadcount.md
View File

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

2
docs/api/threading/task-system/initialize.md
View File

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

2
docs/api/threading/task-system/parallelfor.md
View File

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

2
docs/api/threading/task-system/runonmainthread.md
View File

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

2
docs/api/threading/task-system/shutdown.md
View File

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

12
docs/api/threading/task-system/submit.md
View File

@@ -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);
```
## 相关文档

5
docs/api/threading/task-system/task-system.md
View File

@@ -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) | 提交任务对象 |

2
docs/api/threading/task-system/update.md
View File

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

11
docs/api/threading/task-system/wait.md
View File

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

9
docs/api/threading/task/task.md
View File

@@ -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

44
docs/api/threading/thread/detach.md
View File

@@ -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;
}
```
## 相关文档

33
docs/api/threading/thread/getcurrentid.md
View File

@@ -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;
}
```
## 相关文档

36
docs/api/threading/thread/getid.md
View File

@@ -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;
}
```
## 相关文档

41
docs/api/threading/thread/getname.md
View File

@@ -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;
}
```
## 相关文档

44
docs/api/threading/thread/join.md
View File

@@ -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;
}
```
## 相关文档

25
docs/api/threading/thread/sleep.md
View File

@@ -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;
}
```
## 相关文档

40
docs/api/threading/thread/start.md
View File

@@ -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;
}
```
## 相关文档

Some files were not shown because too many files have changed in this diff Show More