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

docs: rebuild Memory API content

Browse Source
This commit is contained in:
ssdfasd
2026-03-26 18:02:29 +08:00
parent ce2eee32e3
commit dc252502ac
66 changed files with 1182 additions and 1066 deletions
Download Patch File Download Diff File Expand all files Collapse all files

42
docs/api/XCEngine/Memory/MemoryManager/CreateLinearAllocator.md
View File

@@ -1,31 +1,39 @@
# MemoryManager::CreateLinearAllocator
创建新对象或资源。
创建一个线性分配器。
```cpp
std::unique_ptr<LinearAllocator> CreateLinearAllocator(size_t size);
```
该方法声明于 `XCEngine/Memory/MemoryManager.h`，当前页面用于固定 `MemoryManager` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：**
- `size` - 参数语义详见头文件声明。
**返回：** `std::unique_ptr<LinearAllocator>` - 返回值语义详见头文件声明。
**示例：**
当前实现等价于：
```cpp
#include <XCEngine/Memory/MemoryManager.h>
void Example() {
XCEngine::Memory::MemoryManager object;
// 根据上下文补齐参数后调用 MemoryManager::CreateLinearAllocator(...)。
(void)object;
}
return std::make_unique<LinearAllocator>(size, m_systemAllocator);
```
这意味着：
- 如果已经调用过 [Initialize](Initialize.md)，新建的 `LinearAllocator` 会把系统分配器作为父分配器。
- 如果还没初始化，`m_systemAllocator == nullptr`，`LinearAllocator` 会走自己的直接分配路径。
## 参数
- `size` - 线性缓冲区容量。
## 返回值
- `std::unique_ptr<LinearAllocator>` - 由调用方拥有的线性分配器。
## 生命周期注意事项
- 这个工厂不会把返回对象注册到 `MemoryManager` 内部，调用方仍然负责销毁它。
- 如果它绑定了系统分配器作为父分配器，应在 [Shutdown](Shutdown.md) 之前销毁；否则析构时可能访问悬空的 `m_systemAllocator`。
## 相关文档
- [返回类总览](MemoryManager.md)
- [返回模块目录](../Memory.md)
- [返回类型总览](MemoryManager.md)
- [Initialize](Initialize.md)
- [Shutdown](Shutdown.md)

40
docs/api/XCEngine/Memory/MemoryManager/CreatePoolAllocator.md
View File

@@ -1,32 +1,36 @@
# MemoryManager::CreatePoolAllocator
创建新对象或资源。
创建一个池分配器。
```cpp
std::unique_ptr<PoolAllocator> CreatePoolAllocator(size_t blockSize, size_t count);
```
该方法声明于 `XCEngine/Memory/MemoryManager.h`，当前页面用于固定 `MemoryManager` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：**
- `blockSize` - 参数语义详见头文件声明。
- `count` - 参数语义详见头文件声明。
**返回：** `std::unique_ptr<PoolAllocator>` - 返回值语义详见头文件声明。
**示例：**
当前实现等价于：
```cpp
#include <XCEngine/Memory/MemoryManager.h>
void Example() {
XCEngine::Memory::MemoryManager object;
// 根据上下文补齐参数后调用 MemoryManager::CreatePoolAllocator(...)。
(void)object;
}
return std::make_unique<PoolAllocator>(blockSize, count);
```
它不会使用 `m_systemAllocator`，因此即使没有调用 [Initialize](Initialize.md) 也可以工作。
## 参数
- `blockSize` - 单个逻辑 block 大小。
- `count` - block 数量。
## 返回值
- `std::unique_ptr<PoolAllocator>` - 由调用方拥有的池分配器。
## 注意事项
- 这个工厂同样只是创建对象，不会集中托管其生命周期。
- 参数不会在 `MemoryManager` 层做额外校验，`PoolAllocator` 自身当前也缺少防御式检查。
## 相关文档
- [返回类总览](MemoryManager.md)
- [返回模块目录](../Memory.md)
- [返回类型总览](MemoryManager.md)
- [Initialize](Initialize.md)

39
docs/api/XCEngine/Memory/MemoryManager/CreateProxyAllocator.md
View File

@@ -1,31 +1,36 @@
# MemoryManager::CreateProxyAllocator
创建新对象或资源。
创建一个代理分配器。
```cpp
std::unique_ptr<ProxyAllocator> CreateProxyAllocator(const char* name);
```
该方法声明于 `XCEngine/Memory/MemoryManager.h`，当前页面用于固定 `MemoryManager` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：**
- `name` - 参数语义详见头文件声明。
**返回：** `std::unique_ptr<ProxyAllocator>` - 返回值语义详见头文件声明。
**示例：**
当前实现等价于：
```cpp
#include <XCEngine/Memory/MemoryManager.h>
void Example() {
XCEngine::Memory::MemoryManager object;
// 根据上下文补齐参数后调用 MemoryManager::CreateProxyAllocator(...)。
(void)object;
}
return std::make_unique<ProxyAllocator>(m_systemAllocator, name);
```
也就是说，这个工厂当前总是把“系统分配器”作为底层分配器传给 `ProxyAllocator`。
## 参数
- `name` - 代理名称；当前只会把指针原样保存，不会复制内容。
## 返回值
- `std::unique_ptr<ProxyAllocator>` - 由调用方拥有的代理分配器。
## 生命周期注意事项
- 应在 [Initialize](Initialize.md) 之后调用；否则底层分配器为空，后续任何分配操作都可能触发未定义行为。
- 应在 [Shutdown](Shutdown.md) 之前销毁；否则底层系统分配器被删除后，代理内部会留下悬空指针。
## 相关文档
- [返回类总览](MemoryManager.md)
- [返回模块目录](../Memory.md)
- [返回类型总览](MemoryManager.md)
- [Initialize](Initialize.md)
- [Shutdown](Shutdown.md)

28
docs/api/XCEngine/Memory/MemoryManager/DumpMemoryLeaks.md
View File

@@ -1,30 +1,26 @@
# MemoryManager::DumpMemoryLeaks
公开方法，详见头文件声明。
输出内存泄漏报告。
```cpp
void DumpMemoryLeaks();
```
该方法声明于 `XCEngine/Memory/MemoryManager.h`，当前页面用于固定 `MemoryManager` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：** 无。
**返回：** `void` - 无返回值。
**示例：**
当前实现还只是占位接口，实际只向标准输出打印一行标题：
```cpp
#include <XCEngine/Memory/MemoryManager.h>
void Example() {
XCEngine::Memory::MemoryManager object;
// 根据上下文补齐参数后调用 MemoryManager::DumpMemoryLeaks(...)。
(void)object;
}
Memory Leak Report:
```
它不会遍历任何分配记录，也不会列出真实泄漏条目。
## 返回值
- 无。
## 相关文档
- [返回类总览](MemoryManager.md)
- [返回模块目录](../Memory.md)
- [返回类型总览](MemoryManager.md)
- [GenerateMemoryReport](GenerateMemoryReport.md)

28
docs/api/XCEngine/Memory/MemoryManager/GenerateMemoryReport.md
View File

@@ -1,30 +1,26 @@
# MemoryManager::GenerateMemoryReport
公开方法，详见头文件声明。
输出内存报告。
```cpp
void GenerateMemoryReport();
```
该方法声明于 `XCEngine/Memory/MemoryManager.h`，当前页面用于固定 `MemoryManager` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：** 无。
**返回：** `void` - 无返回值。
**示例：**
当前实现同样只是占位接口，实际只向标准输出打印：
```cpp
#include <XCEngine/Memory/MemoryManager.h>
void Example() {
XCEngine::Memory::MemoryManager object;
// 根据上下文补齐参数后调用 MemoryManager::GenerateMemoryReport(...)。
(void)object;
}
Memory Report:
```
它不会汇总各分配器状态，也不会生成结构化报表文件。
## 返回值
- 无。
## 相关文档
- [返回类总览](MemoryManager.md)
- [返回模块目录](../Memory.md)
- [返回类型总览](MemoryManager.md)
- [DumpMemoryLeaks](DumpMemoryLeaks.md)

30
docs/api/XCEngine/Memory/MemoryManager/Get.md
View File

@@ -1,29 +1,29 @@
# MemoryManager::Get
获取相关状态或对象。
获取全局 `MemoryManager` 单例。
```cpp
static MemoryManager& Get();
```
该方法声明于 `XCEngine/Memory/MemoryManager.h`，当前页面用于固定 `MemoryManager` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：** 无。
**返回：** `MemoryManager&` - 返回值语义详见头文件声明。
**示例：**
当前实现通过函数内静态对象返回进程级唯一实例：
```cpp
#include <XCEngine/Memory/MemoryManager.h>
void Example() {
auto& instance = XCEngine::Memory::MemoryManager::Get();
(void)instance;
}
static MemoryManager instance;
```
## 返回值
- `MemoryManager&` - 全局 `MemoryManager` 实例引用。
## 设计说明
- 这提供了一个集中入口，但不意味着所有分配器对象都被统一托管。
- 通过工厂方法创建出来的分配器，生命周期仍由调用方负责。
## 相关文档
- [返回类总览](MemoryManager.md)
- [返回模块目录](../Memory.md)
- [返回类型总览](MemoryManager.md)
- [Initialize](Initialize.md)

26
docs/api/XCEngine/Memory/MemoryManager/GetSystemAllocator.md
View File

@@ -1,30 +1,26 @@
# MemoryManager::GetSystemAllocator
获取相关状态或对象。
获取内部系统分配器。
```cpp
IAllocator* GetSystemAllocator();
```
该方法声明于 `XCEngine/Memory/MemoryManager.h`，当前页面用于固定 `MemoryManager` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：** 无。
当前实现直接返回成员指针 `m_systemAllocator`，不会增加引用计数，也不会转移所有权。
**返回：** `IAllocator*` - 返回值语义详见头文件声明。
## 返回值
**示例：**
- `IAllocator*` - 系统分配器指针；未初始化或已关闭时为 `nullptr`。
```cpp
#include <XCEngine/Memory/MemoryManager.h>
## 生命周期注意事项
void Example() {
XCEngine::Memory::MemoryManager object;
// 根据上下文补齐参数后调用 MemoryManager::GetSystemAllocator(...)。
(void)object;
}
```
- 这是一个非拥有指针。
- 只有在 [Initialize](Initialize.md) 之后、[Shutdown](Shutdown.md) 之前使用才安全。
## 相关文档
- [返回类总览](MemoryManager.md)
- [返回模块目录](../Memory.md)
- [返回类型总览](MemoryManager.md)
- [Initialize](Initialize.md)
- [Shutdown](Shutdown.md)

31
docs/api/XCEngine/Memory/MemoryManager/Initialize.md
View File

@@ -1,30 +1,31 @@
# MemoryManager::Initialize
初始化内部状态。
初始化内部系统分配器。
```cpp
void Initialize();
```
该方法声明于 `XCEngine/Memory/MemoryManager.h`，当前页面用于固定 `MemoryManager` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：** 无。
当前实现是幂等的：
**返回：** `void` - 无返回值。
1. 如果 `m_initialized` 已经是 `true`，直接返回。
2. 否则执行 `m_systemAllocator = new SystemAllocator();`
3. 把 `m_initialized` 设为 `true`。
**示例：**
## 返回值
```cpp
#include <XCEngine/Memory/MemoryManager.h>
- 无。
void Example() {
XCEngine::Memory::MemoryManager object;
// 根据上下文补齐参数后调用 MemoryManager::Initialize(...)。
(void)object;
}
```
## 当前实现限制
- 不加锁，不适合并发初始化。
- 不处理 `new SystemAllocator()` 失败后的恢复逻辑。
- 不会因为 `m_trackAllocations` 的值不同而启用额外跟踪流程。
## 相关文档
- [返回类总览](MemoryManager.md)
- [返回模块目录](../Memory.md)
- [返回类型总览](MemoryManager.md)
- [GetSystemAllocator](GetSystemAllocator.md)
- [Shutdown](Shutdown.md)

63
docs/api/XCEngine/Memory/MemoryManager/MemoryManager.md
View File

@@ -6,34 +6,57 @@
**头文件**: `XCEngine/Memory/MemoryManager.h`
**描述**: 定义 `XCEngine/Memory` 子目录中的 `MemoryManager` public API。
**描述**: 初始化内部系统分配器，并提供常用分配器的工厂接口。
## 概述
`MemoryManager.h` 是 `XCEngine/Memory` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。
`MemoryManager` 当前是内存模块的全局入口，但它的职责比名字听起来更窄。它主要做三件事：
## 声明概览
- 创建和保存一个内部 `SystemAllocator`
- 提供若干分配器工厂方法
- 预留追踪、泄漏报告和报表接口
| 声明 | 类型 | 说明 |
|------|------|------|
| `MemoryManager` | `class` | 头文件中的公开声明。 |
它还定义了两个便利宏：
## 公共方法
- `XE_ALLOC(allocator, size, ...)`
- `XE_FREE(allocator, ptr)`
| 方法 | 描述 |
## 当前实现边界
- 只有在 [Initialize](Initialize.md) 之后，`GetSystemAllocator()` 才会返回有效系统分配器。
- `CreateLinearAllocator()` 即使在未初始化时也能工作，因为 `LinearAllocator` 在父分配器为空时会走自身的直接分配路径。
- `CreateProxyAllocator()` 在未初始化时会创建一个底层分配器为空的对象，后续实际分配将产生未定义行为，因此应在初始化后使用。
- 使用系统分配器作为底层或父分配器创建出来的对象，应在 [Shutdown](Shutdown.md) 之前销毁，否则会留下悬空指针。
- `SetTrackAllocations()` 当前只修改标志位，不驱动统计逻辑。
- `DumpMemoryLeaks()` 和 `GenerateMemoryReport()` 当前只向 `stdout` 输出标题。
## 生命周期
- [Get](Get.md) 返回进程级单例。
- [Initialize](Initialize.md) 创建内部系统分配器。
- [Shutdown](Shutdown.md) 销毁内部系统分配器。
## 线程语义
- 当前管理器自身没有锁。
- 建议在启动和受控退出阶段使用，不要在多个线程中并发初始化或关闭。
## 公开方法
| 方法 | 说明 |
|------|------|
| [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) | 公开方法，详见头文件声明。 |
| [Get](Get.md) | 获取全局 `MemoryManager` 实例。 |
| [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) | 输出内存报告标题。 |
## 相关文档
- [当前目录](../Memory.md) - 返回 `Memory` 平行目录
- [API 总索引](../../../main.md) - 返回顶层索引
- [当前模块](../Memory.md)
- [Allocator Selection And Current Limits](../../../_guides/Memory/Allocator-Selection-And-Current-Limits.md)

33
docs/api/XCEngine/Memory/MemoryManager/SetTrackAllocations.md
View File

@@ -1,31 +1,30 @@
# MemoryManager::SetTrackAllocations
设置相关状态或配置。
设置是否跟踪分配。
```cpp
void SetTrackAllocations(bool track);
```
该方法声明于 `XCEngine/Memory/MemoryManager.h`，当前页面用于固定 `MemoryManager` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：**
- `track` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。
**示例：**
当前实现只做一件事：
```cpp
#include <XCEngine/Memory/MemoryManager.h>
void Example() {
XCEngine::Memory::MemoryManager object;
// 根据上下文补齐参数后调用 MemoryManager::SetTrackAllocations(...)。
(void)object;
}
m_trackAllocations = track;
```
它不会创建追踪器、不会改变 `ProxyAllocator` 行为，也不会影响 `DumpMemoryLeaks()` 或 `GenerateMemoryReport()` 的输出内容。
## 参数
- `track` - 要保存的跟踪开关值。
## 返回值
- 无。
## 相关文档
- [返回类总览](MemoryManager.md)
- [返回模块目录](../Memory.md)
- [返回类型总览](MemoryManager.md)
- [DumpMemoryLeaks](DumpMemoryLeaks.md)

31
docs/api/XCEngine/Memory/MemoryManager/Shutdown.md
View File

@@ -1,30 +1,31 @@
# MemoryManager::Shutdown
关闭并清理内部状态。
关闭内存管理器并销毁内部系统分配器。
```cpp
void Shutdown();
```
该方法声明于 `XCEngine/Memory/MemoryManager.h`，当前页面用于固定 `MemoryManager` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：** 无。
当前实现也是幂等的：
**返回：** `void` - 无返回值。
1. 如果 `m_initialized` 为 `false`，直接返回。
2. 否则执行 `delete static_cast<SystemAllocator*>(m_systemAllocator);`
3. 把 `m_systemAllocator` 置空，并把 `m_initialized` 设为 `false`。
**示例：**
## 返回值
```cpp
#include <XCEngine/Memory/MemoryManager.h>
- 无。
void Example() {
XCEngine::Memory::MemoryManager object;
// 根据上下文补齐参数后调用 MemoryManager::Shutdown(...)。
(void)object;
}
```
## 当前实现限制
- 不会自动销毁通过工厂方法创建的其它分配器对象。
- 不会检查是否还有未释放对象或未完成的泄漏跟踪。
- 如果仍有依赖系统分配器的 `LinearAllocator` 或 `ProxyAllocator` 存活，后续使用或析构都可能访问悬空指针。
## 相关文档
- [返回类总览](MemoryManager.md)
- [返回模块目录](../Memory.md)
- [返回类型总览](MemoryManager.md)
- [Initialize](Initialize.md)
- [GetSystemAllocator](GetSystemAllocator.md)