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