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

32
docs/api/XCEngine/Memory/Allocator/Allocate.md
View File

@@ -1,32 +1,30 @@
# IAllocator::Allocate
公开方法，详见头文件声明。
申请一块内存。
```cpp
virtual void* Allocate(size_t size, size_t alignment = 0) = 0;
```
该方法声明于 `XCEngine/Memory/Allocator.h`，当前页面用于固定 `IAllocator` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：**
- `size` - 参数语义详见头文件声明。
- `alignment` - 参数语义详见头文件声明。
这是纯虚接口。不同实现对 `size`、`alignment` 和失败条件的支持程度不同：
**返回：** `void*` - 返回值语义详见头文件声明。
- `LinearAllocator` 支持顺序分配，但对齐语义目前有限。
- `PoolAllocator` 只在 `size <= blockSize` 且还有空闲块时成功。
- `ProxyAllocator` 只是转发到底层分配器。
**示例：**
## 参数
```cpp
#include <XCEngine/Memory/Allocator.h>
- `size` - 请求大小。
- `alignment` - 对齐要求；`0` 表示实现自定默认行为。
void Example() {
XCEngine::Memory::IAllocator object;
// 根据上下文补齐参数后调用 IAllocator::Allocate(...)。
(void)object;
}
```
## 返回值
- `void*` - 成功时返回可用内存；失败时通常返回 `nullptr`。
## 相关文档
- [返回类总览](Allocator.md)
- [返回模块目录](../Memory.md)
- [返回类型总览](Allocator.md)
- [Free](Free.md)
- [Reallocate](Reallocate.md)

62
docs/api/XCEngine/Memory/Allocator/Allocator.md
View File

@@ -1,38 +1,58 @@
# Allocator
# IAllocator
**命名空间**: `XCEngine::Memory`
**类型**: `class (abstract)`
**类型**: `class (abstract interface)`
**头文件**: `XCEngine/Memory/Allocator.h`
**描述**: 定义 `XCEngine/Memory` 子目录中的 `Allocator` public API。
**描述**: 定义统一的分配、释放、重分配和统计查询接口。
## 概述
`Allocator.h` 是 `XCEngine/Memory` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。
`IAllocator` 是当前内存模块的基础抽象。它把“如何申请和回收一块内存”统一成一组稳定接口，让上层代码不必直接依赖具体分配器实现。
## 声明概览
它的职责分成两部分：
| 声明 | 类型 | 说明 |
|------|------|------|
| `IAllocator` | `class` | 头文件中的公开声明。 |
- 内存操作：`Allocate`、`Free`、`Reallocate`
- 统计查询：`GetTotalAllocated`、`GetTotalFreed`、`GetPeakAllocated`、`GetAllocationCount`
## 公共方法
## 设计目的
| 方法 | 描述 |
这类接口在引擎里很有价值，因为：
- 容器、资源系统和工具系统可以接受任意分配器实现。
- 不同策略可以共存，例如线性分配器、对象池、系统分配器代理。
- 调试和统计逻辑可以围绕接口做组合，而不是侵入所有调用点。
## 当前实现约束
- `IAllocator` 只定义形状，不保证线程安全。
- 统计方法的语义由具体实现决定；当前不同分配器的统计精度并不一致。
- 不是每个实现都完整支持 `Free` 和 `Reallocate`。
## 已知实现
- [LinearAllocator](../LinearAllocator/LinearAllocator.md)
- [PoolAllocator](../PoolAllocator/PoolAllocator.md)
- [ProxyAllocator](../ProxyAllocator/ProxyAllocator.md)
- `SystemAllocator`：当前仅存在于 `engine/src/Memory/Memory.cpp` 内部，不是公共类型。
## 公开方法
| 方法 | 说明 |
|------|------|
| [~IAllocator()](Destructor.md) | 销毁对象并释放相关资源。 |
| [Allocate](Allocate.md) | 公开方法，详见头文件声明。 |
| [Free](Free.md) | 公开方法，详见头文件声明。 |
| [Reallocate](Reallocate.md) | 公开方法，详见头文件声明。 |
| [GetTotalAllocated](GetTotalAllocated.md) | 获取相关状态或对象。 |
| [GetTotalFreed](GetTotalFreed.md) | 获取相关状态或对象。 |
| [GetPeakAllocated](GetPeakAllocated.md) | 获取相关状态或对象。 |
| [GetAllocationCount](GetAllocationCount.md) | 获取相关状态或对象。 |
| [GetName](GetName.md) | 获取相关状态或对象。 |
| [Destructor](Destructor.md) | 虚析构函数。 |
| [Allocate](Allocate.md) | 申请内存。 |
| [Free](Free.md) | 释放内存。 |
| [Reallocate](Reallocate.md) | 调整已分配内存大小。 |
| [GetTotalAllocated](GetTotalAllocated.md) | 查询累计已分配量。 |
| [GetTotalFreed](GetTotalFreed.md) | 查询累计已释放量。 |
| [GetPeakAllocated](GetPeakAllocated.md) | 查询峰值分配量。 |
| [GetAllocationCount](GetAllocationCount.md) | 查询当前或累计分配次数。 |
| [GetName](GetName.md) | 查询分配器名称。 |
## 相关文档
- [当前目录](../Memory.md) - 返回 `Memory` 平行目录
- [API 总索引](../../../main.md) - 返回顶层索引
- [当前模块](../Memory.md)
- [Allocator Selection And Current Limits](../../../_guides/Memory/Allocator-Selection-And-Current-Limits.md)

24
docs/api/XCEngine/Memory/Allocator/Destructor.md
View File

@@ -1,29 +1,15 @@
# IAllocator::~IAllocator()
# IAllocator::Destructor
销毁对象并释放相关资源。
通过基类指针安全销毁分配器。
```cpp
virtual ~IAllocator() = default;
```
该方法声明于 `XCEngine/Memory/Allocator.h`，当前页面用于固定 `IAllocator` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：** 无。
**返回：** `void` - 无返回值。
**示例：**
```cpp
#include <XCEngine/Memory/Allocator.h>
void Example() {
XCEngine::Memory::IAllocator object;
// 对象离开作用域时会自动触发析构。
}
```
虚析构函数保证 `std::unique_ptr<IAllocator>` 或基类指针可以正确销毁派生分配器对象。
## 相关文档
- [返回类总览](Allocator.md)
- [返回模块目录](../Memory.md)
- [返回类型总览](Allocator.md)

29
docs/api/XCEngine/Memory/Allocator/Free.md
View File

@@ -1,31 +1,28 @@
# IAllocator::Free
公开方法，详见头文件声明。
释放一块已分配内存。
```cpp
virtual void Free(void* ptr) = 0;
```
该方法声明于 `XCEngine/Memory/Allocator.h`，当前页面用于固定 `IAllocator` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：**
- `ptr` - 参数语义详见头文件声明。
这是纯虚接口，但并不是每个实现都真正支持独立释放：
**返回：** `void` - 无返回值。
- `LinearAllocator` 当前为空实现。
- `PoolAllocator` 支持把 block 放回空闲链表。
- `ProxyAllocator` 会把调用转发到底层分配器。
**示例：**
## 参数
```cpp
#include <XCEngine/Memory/Allocator.h>
- `ptr` - 待释放指针。
void Example() {
XCEngine::Memory::IAllocator object;
// 根据上下文补齐参数后调用 IAllocator::Free(...)。
(void)object;
}
```
## 返回值
- 无。
## 相关文档
- [返回类总览](Allocator.md)
- [返回模块目录](../Memory.md)
- [返回类型总览](Allocator.md)
- [Allocate](Allocate.md)

25
docs/api/XCEngine/Memory/Allocator/GetAllocationCount.md
View File

@@ -1,30 +1,23 @@
# IAllocator::GetAllocationCount
获取相关状态或对象。
查询分配计数。
```cpp
virtual size_t GetAllocationCount() const = 0;
```
该方法声明于 `XCEngine/Memory/Allocator.h`，当前页面用于固定 `IAllocator` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：** 无。
这是纯虚统计接口，但不同实现的口径不同：
**返回：** `size_t` - 返回值语义详见头文件声明。
- `PoolAllocator` 当前返回已分配 block 数。
- `ProxyAllocator` 当前返回内部统计中的 allocationCount。
- `LinearAllocator` 当前始终返回 `0`。
**示例：**
## 返回值
```cpp
#include <XCEngine/Memory/Allocator.h>
void Example() {
XCEngine::Memory::IAllocator object;
// 根据上下文补齐参数后调用 IAllocator::GetAllocationCount(...)。
(void)object;
}
```
- `size_t` - 实现定义的分配计数。
## 相关文档
- [返回类总览](Allocator.md)
- [返回模块目录](../Memory.md)
- [返回类型总览](Allocator.md)

23
docs/api/XCEngine/Memory/Allocator/GetName.md
View File

@@ -1,30 +1,19 @@
# IAllocator::GetName
获取相关状态或对象。
查询分配器名称。
```cpp
virtual const char* GetName() const = 0;
```
该方法声明于 `XCEngine/Memory/Allocator.h`，当前页面用于固定 `IAllocator` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：** 无。
返回一个只读 C 字符串，用于调试、日志或报表标识。不同实现可能返回固定字面量，也可能返回构造时提供的名称。
**返回：** `const char*` - 返回值语义详见头文件声明。
## 返回值
**示例：**
```cpp
#include <XCEngine/Memory/Allocator.h>
void Example() {
XCEngine::Memory::IAllocator object;
// 根据上下文补齐参数后调用 IAllocator::GetName(...)。
(void)object;
}
```
- `const char*` - 分配器名称。
## 相关文档
- [返回类总览](Allocator.md)
- [返回模块目录](../Memory.md)
- [返回类型总览](Allocator.md)

24
docs/api/XCEngine/Memory/Allocator/GetPeakAllocated.md
View File

@@ -1,30 +1,22 @@
# IAllocator::GetPeakAllocated
获取相关状态或对象。
查询峰值分配量。
```cpp
virtual size_t GetPeakAllocated() const = 0;
```
该方法声明于 `XCEngine/Memory/Allocator.h`，当前页面用于固定 `IAllocator` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：** 无。
这是纯虚统计接口，但当前实现并不统一：
**返回：** `size_t` - 返回值语义详见头文件声明。
- `ProxyAllocator` 维护的是净分配峰值。
- `PoolAllocator` 和 `LinearAllocator` 当前返回的是固定容量上界，而不是真实历史峰值。
**示例：**
## 返回值
```cpp
#include <XCEngine/Memory/Allocator.h>
void Example() {
XCEngine::Memory::IAllocator object;
// 根据上下文补齐参数后调用 IAllocator::GetPeakAllocated(...)。
(void)object;
}
```
- `size_t` - 实现定义的峰值分配量。
## 相关文档
- [返回类总览](Allocator.md)
- [返回模块目录](../Memory.md)
- [返回类型总览](Allocator.md)

25
docs/api/XCEngine/Memory/Allocator/GetTotalAllocated.md
View File

@@ -1,30 +1,23 @@
# IAllocator::GetTotalAllocated
获取相关状态或对象。
查询累计或当前已分配量。
```cpp
virtual size_t GetTotalAllocated() const = 0;
```
该方法声明于 `XCEngine/Memory/Allocator.h`，当前页面用于固定 `IAllocator` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：** 无。
这是纯虚统计接口。当前不同实现的语义不同：
**返回：** `size_t` - 返回值语义详见头文件声明。
- `LinearAllocator` 返回当前已用大小。
- `PoolAllocator` 返回当前已占用 block 总字节数。
- `ProxyAllocator` 返回累计请求分配字节数。
**示例：**
## 返回值
```cpp
#include <XCEngine/Memory/Allocator.h>
void Example() {
XCEngine::Memory::IAllocator object;
// 根据上下文补齐参数后调用 IAllocator::GetTotalAllocated(...)。
(void)object;
}
```
- `size_t` - 实现定义的分配量。
## 相关文档
- [返回类总览](Allocator.md)
- [返回模块目录](../Memory.md)
- [返回类型总览](Allocator.md)

23
docs/api/XCEngine/Memory/Allocator/GetTotalFreed.md
View File

@@ -1,30 +1,19 @@
# IAllocator::GetTotalFreed
获取相关状态或对象。
查询累计或当前已释放量。
```cpp
virtual size_t GetTotalFreed() const = 0;
```
该方法声明于 `XCEngine/Memory/Allocator.h`，当前页面用于固定 `IAllocator` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：** 无。
这是纯虚统计接口。当前各实现语义并不一致，而且 `ProxyAllocator` 的释放统计目前不准确。
**返回：** `size_t` - 返回值语义详见头文件声明。
## 返回值
**示例：**
```cpp
#include <XCEngine/Memory/Allocator.h>
void Example() {
XCEngine::Memory::IAllocator object;
// 根据上下文补齐参数后调用 IAllocator::GetTotalFreed(...)。
(void)object;
}
```
- `size_t` - 实现定义的释放量。
## 相关文档
- [返回类总览](Allocator.md)
- [返回模块目录](../Memory.md)
- [返回类型总览](Allocator.md)

31
docs/api/XCEngine/Memory/Allocator/Reallocate.md
View File

@@ -1,32 +1,29 @@
# IAllocator::Reallocate
公开方法，详见头文件声明。
调整一块已分配内存的大小。
```cpp
virtual void* Reallocate(void* ptr, size_t newSize) = 0;
```
该方法声明于 `XCEngine/Memory/Allocator.h`，当前页面用于固定 `IAllocator` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：**
- `ptr` - 参数语义详见头文件声明。
- `newSize` - 参数语义详见头文件声明。
这是纯虚接口，但当前并不是每个实现都支持：
**返回：** `void*` - 返回值语义详见头文件声明。
- `LinearAllocator` 当前返回 `nullptr`
- `PoolAllocator` 当前返回 `nullptr`
- `ProxyAllocator` 只是转发到底层分配器
**示例：**
## 参数
```cpp
#include <XCEngine/Memory/Allocator.h>
- `ptr` - 原始指针。
- `newSize` - 新大小。
void Example() {
XCEngine::Memory::IAllocator object;
// 根据上下文补齐参数后调用 IAllocator::Reallocate(...)。
(void)object;
}
```
## 返回值
- `void*` - 成功时返回新指针；当前某些实现始终返回 `nullptr`。
## 相关文档
- [返回类总览](Allocator.md)
- [返回模块目录](../Memory.md)
- [返回类型总览](Allocator.md)
- [Allocate](Allocate.md)

39
docs/api/XCEngine/Memory/LinearAllocator/Allocate.md
View File

@@ -1,32 +1,37 @@
# LinearAllocator::Allocate
公开方法，详见头文件声明。
从当前偏移量开始分配一块线性内存。
```cpp
void* Allocate(size_t size, size_t alignment = 8) override;
```
该方法声明于 `XCEngine/Memory/LinearAllocator.h`，当前页面用于固定 `LinearAllocator` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：**
- `size` - 参数语义详见头文件声明。
- `alignment` - 参数语义详见头文件声明。
当前实现流程：
**返回：** `void*` - 返回值语义详见头文件声明。
1. `size == 0` 时直接返回 `nullptr`
2. 以 `m_buffer + m_offset` 作为当前地址
3. 如果 `alignment > 0`，按当前地址计算 misalignment，并把 padding 直接加到消耗的 `size` 上
4. 如果 `m_offset + size > m_capacity`，返回 `nullptr`
5. 返回当前偏移位置指针，并推进 `m_offset`
**示例：**
需要特别注意：
```cpp
#include <XCEngine/Memory/LinearAllocator.h>
- 当前实现增加的是“消耗大小”，不是“返回地址偏移”，因此它不保证返回指针一定满足任意给定对齐要求。
- 分配是单调推进的，不支持单个块释放。
void Example() {
XCEngine::Memory::LinearAllocator object;
// 根据上下文补齐参数后调用 LinearAllocator::Allocate(...)。
(void)object;
}
```
## 参数
- `size` - 请求大小。
- `alignment` - 期望对齐；当前默认值为 `8`。
## 返回值
- `void*` - 成功时返回缓冲区中的一段内存；容量不足时返回 `nullptr`。
## 相关文档
- [返回类总览](LinearAllocator.md)
- [返回模块目录](../Memory.md)
- [返回类型总览](LinearAllocator.md)
- [Clear](Clear.md)
- [GetUsedSize](GetUsedSize.md)

24
docs/api/XCEngine/Memory/LinearAllocator/Clear.md
View File

@@ -1,30 +1,22 @@
# LinearAllocator::Clear
清空内部数据。
一次性回收当前所有线性分配结果。
```cpp
void Clear();
```
该方法声明于 `XCEngine/Memory/LinearAllocator.h`，当前页面用于固定 `LinearAllocator` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：** 无。
**返回：** `void` - 无返回值。
**示例：**
当前实现仅执行：
```cpp
#include <XCEngine/Memory/LinearAllocator.h>
void Example() {
XCEngine::Memory::LinearAllocator object;
// 根据上下文补齐参数后调用 LinearAllocator::Clear(...)。
(void)object;
}
m_offset = 0;
```
它不会逐块调用析构，也不会清零缓冲区内容。旧内存中的字节仍然存在，但逻辑上已经全部视为可重新分配。
## 相关文档
- [返回类总览](LinearAllocator.md)
- [返回模块目录](../Memory.md)
- [返回类型总览](LinearAllocator.md)
- [GetMarker](GetMarker.md)

32
docs/api/XCEngine/Memory/LinearAllocator/Constructor.md
View File

@@ -1,30 +1,30 @@
# LinearAllocator::LinearAllocator()
# LinearAllocator::Constructor
构造对象。
构造一个固定容量的线性分配器。
```cpp
explicit LinearAllocator(size_t size, IAllocator* parent = nullptr);
```
该方法声明于 `XCEngine/Memory/LinearAllocator.h`，当前页面用于固定 `LinearAllocator` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：**
- `size` - 参数语义详见头文件声明。
- `parent` - 参数语义详见头文件声明。
当前实现会保存总容量和父分配器指针，然后申请底层缓冲区：
**返回：** `void` - 无返回值。
- 如果 `parent` 非空，通过父分配器申请 `size` 字节。
- 如果 `parent` 为空，当前实现直接调用 `_aligned_malloc(size, 8)`。
**示例：**
这意味着“无父分配器”路径当前是明显的 Windows 风格实现。
```cpp
#include <XCEngine/Memory/LinearAllocator.h>
## 参数
void Example() {
XCEngine::Memory::LinearAllocator object;
}
```
- `size` - 缓冲区容量。
- `parent` - 可选的父分配器。
## 返回值
- 无。
## 相关文档
- [返回类总览](LinearAllocator.md)
- [返回模块目录](../Memory.md)
- [返回类型总览](LinearAllocator.md)
- [Destructor](Destructor.md)

26
docs/api/XCEngine/Memory/LinearAllocator/Destructor.md
View File

@@ -1,29 +1,19 @@
# LinearAllocator::~LinearAllocator()
# LinearAllocator::Destructor
销毁对象并释放相关资源。
销毁线性分配器并释放底层缓冲区。
```cpp
~LinearAllocator() override;
```
该方法声明于 `XCEngine/Memory/LinearAllocator.h`，当前页面用于固定 `LinearAllocator` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：** 无。
当前实现根据构造来源选择释放方式：
**返回：** `void` - 无返回值。
**示例：**
```cpp
#include <XCEngine/Memory/LinearAllocator.h>
void Example() {
XCEngine::Memory::LinearAllocator object;
// 对象离开作用域时会自动触发析构。
}
```
- 如果有父分配器，则调用 `m_parent->Free(m_buffer)`
- 否则在 Windows 上调用 `_aligned_free(m_buffer)`，非 Windows 路径调用 `std::free(m_buffer)`
## 相关文档
- [返回类总览](LinearAllocator.md)
- [返回模块目录](../Memory.md)
- [返回类型总览](LinearAllocator.md)
- [Constructor](Constructor.md)

25
docs/api/XCEngine/Memory/LinearAllocator/Free.md
View File

@@ -1,31 +1,24 @@
# LinearAllocator::Free
公开方法，详见头文件声明。
释放一块线性分配结果。
```cpp
void Free(void* ptr) override;
```
该方法声明于 `XCEngine/Memory/LinearAllocator.h`，当前页面用于固定 `LinearAllocator` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：**
- `ptr` - 参数语义详见头文件声明。
当前实现为空函数。也就是说，`LinearAllocator` 目前不支持单独释放任何块。
**返回：** `void` - 无返回值。
## 参数
**示例：**
- `ptr` - 当前不会被使用。
```cpp
#include <XCEngine/Memory/LinearAllocator.h>
## 返回值
void Example() {
XCEngine::Memory::LinearAllocator object;
// 根据上下文补齐参数后调用 LinearAllocator::Free(...)。
(void)object;
}
```
- 无。
## 相关文档
- [返回类总览](LinearAllocator.md)
- [返回模块目录](../Memory.md)
- [返回类型总览](LinearAllocator.md)
- [Clear](Clear.md)

23
docs/api/XCEngine/Memory/LinearAllocator/GetAllocationCount.md
View File

@@ -1,30 +1,19 @@
# LinearAllocator::GetAllocationCount
获取相关状态或对象。
查询分配次数。
```cpp
size_t GetAllocationCount() const override;
```
该方法声明于 `XCEngine/Memory/LinearAllocator.h`，当前页面用于固定 `LinearAllocator` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：** 无。
当前头文件内联实现固定返回 `0`。它不是实际分配次数统计。
**返回：** `size_t` - 返回值语义详见头文件声明。
## 返回值
**示例：**
```cpp
#include <XCEngine/Memory/LinearAllocator.h>
void Example() {
XCEngine::Memory::LinearAllocator object;
// 根据上下文补齐参数后调用 LinearAllocator::GetAllocationCount(...)。
(void)object;
}
```
- `size_t` - 当前固定为 `0`。
## 相关文档
- [返回类总览](LinearAllocator.md)
- [返回模块目录](../Memory.md)
- [返回类型总览](LinearAllocator.md)

24
docs/api/XCEngine/Memory/LinearAllocator/GetCapacity.md
View File

@@ -1,30 +1,20 @@
# LinearAllocator::GetCapacity
获取相关状态或对象。
查询线性分配器的总容量。
```cpp
size_t GetCapacity() const;
```
该方法声明于 `XCEngine/Memory/LinearAllocator.h`，当前页面用于固定 `LinearAllocator` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：** 无。
返回构造时保存的 `m_capacity`，不受当前已用偏移量影响。
**返回：** `size_t` - 返回值语义详见头文件声明。
## 返回值
**示例：**
```cpp
#include <XCEngine/Memory/LinearAllocator.h>
void Example() {
XCEngine::Memory::LinearAllocator object;
// 根据上下文补齐参数后调用 LinearAllocator::GetCapacity(...)。
(void)object;
}
```
- `size_t` - 总容量。
## 相关文档
- [返回类总览](LinearAllocator.md)
- [返回模块目录](../Memory.md)
- [返回类型总览](LinearAllocator.md)
- [GetUsedSize](GetUsedSize.md)

28
docs/api/XCEngine/Memory/LinearAllocator/GetMarker.md
View File

@@ -1,30 +1,26 @@
# LinearAllocator::GetMarker
获取相关状态或对象。
获取当前偏移标记。
```cpp
void* GetMarker() const;
```
该方法声明于 `XCEngine/Memory/LinearAllocator.h`，当前页面用于固定 `LinearAllocator` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：** 无。
**返回：** `void*` - 返回值语义详见头文件声明。
**示例：**
当前实现返回的是：
```cpp
#include <XCEngine/Memory/LinearAllocator.h>
void Example() {
XCEngine::Memory::LinearAllocator object;
// 根据上下文补齐参数后调用 LinearAllocator::GetMarker(...)。
(void)object;
}
reinterpret_cast<void*>(m_offset)
```
也就是说，这不是缓冲区中的真实内存指针，而是把“当前 offset 值”包装成一个 `void*` 令牌，供 [SetMarker](SetMarker.md) 之后恢复使用。
## 返回值
- `void*` - 偏移量令牌。
## 相关文档
- [返回类总览](LinearAllocator.md)
- [返回模块目录](../Memory.md)
- [返回类型总览](LinearAllocator.md)
- [SetMarker](SetMarker.md)

23
docs/api/XCEngine/Memory/LinearAllocator/GetName.md
View File

@@ -1,30 +1,19 @@
# LinearAllocator::GetName
获取相关状态或对象。
查询分配器名称。
```cpp
const char* GetName() const override;
```
该方法声明于 `XCEngine/Memory/LinearAllocator.h`，当前页面用于固定 `LinearAllocator` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：** 无。
当前头文件内联实现固定返回 `"LinearAllocator"`。
**返回：** `const char*` - 返回值语义详见头文件声明。
## 返回值
**示例：**
```cpp
#include <XCEngine/Memory/LinearAllocator.h>
void Example() {
XCEngine::Memory::LinearAllocator object;
// 根据上下文补齐参数后调用 LinearAllocator::GetName(...)。
(void)object;
}
```
- `const char*` - 固定名称字符串。
## 相关文档
- [返回类总览](LinearAllocator.md)
- [返回模块目录](../Memory.md)
- [返回类型总览](LinearAllocator.md)

24
docs/api/XCEngine/Memory/LinearAllocator/GetPeakAllocated.md
View File

@@ -1,30 +1,20 @@
# LinearAllocator::GetPeakAllocated
获取相关状态或对象。
查询峰值分配量。
```cpp
size_t GetPeakAllocated() const override;
```
该方法声明于 `XCEngine/Memory/LinearAllocator.h`，当前页面用于固定 `LinearAllocator` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：** 无。
当前头文件内联实现直接返回 `m_capacity`。这表示“理论最大可用容量”，而不是历史峰值使用量。
**返回：** `size_t` - 返回值语义详见头文件声明。
## 返回值
**示例：**
```cpp
#include <XCEngine/Memory/LinearAllocator.h>
void Example() {
XCEngine::Memory::LinearAllocator object;
// 根据上下文补齐参数后调用 LinearAllocator::GetPeakAllocated(...)。
(void)object;
}
```
- `size_t` - 当前固定等于容量。
## 相关文档
- [返回类总览](LinearAllocator.md)
- [返回模块目录](../Memory.md)
- [返回类型总览](LinearAllocator.md)
- [GetCapacity](GetCapacity.md)

24
docs/api/XCEngine/Memory/LinearAllocator/GetTotalAllocated.md
View File

@@ -1,30 +1,20 @@
# LinearAllocator::GetTotalAllocated
获取相关状态或对象。
查询当前已用字节数。
```cpp
size_t GetTotalAllocated() const override;
```
该方法声明于 `XCEngine/Memory/LinearAllocator.h`，当前页面用于固定 `LinearAllocator` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：** 无。
当前头文件内联实现直接返回 `m_offset`。因此它表示的是“当前已消耗的线性缓冲大小”，不是历史累计分配量。
**返回：** `size_t` - 返回值语义详见头文件声明。
## 返回值
**示例：**
```cpp
#include <XCEngine/Memory/LinearAllocator.h>
void Example() {
XCEngine::Memory::LinearAllocator object;
// 根据上下文补齐参数后调用 LinearAllocator::GetTotalAllocated(...)。
(void)object;
}
```
- `size_t` - 当前已用字节数。
## 相关文档
- [返回类总览](LinearAllocator.md)
- [返回模块目录](../Memory.md)
- [返回类型总览](LinearAllocator.md)
- [GetUsedSize](GetUsedSize.md)

23
docs/api/XCEngine/Memory/LinearAllocator/GetTotalFreed.md
View File

@@ -1,30 +1,19 @@
# LinearAllocator::GetTotalFreed
获取相关状态或对象。
查询累计释放量。
```cpp
size_t GetTotalFreed() const override;
```
该方法声明于 `XCEngine/Memory/LinearAllocator.h`，当前页面用于固定 `LinearAllocator` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：** 无。
当前头文件内联实现固定返回 `0`，因为 `LinearAllocator` 目前不做单块释放统计。
**返回：** `size_t` - 返回值语义详见头文件声明。
## 返回值
**示例：**
```cpp
#include <XCEngine/Memory/LinearAllocator.h>
void Example() {
XCEngine::Memory::LinearAllocator object;
// 根据上下文补齐参数后调用 LinearAllocator::GetTotalFreed(...)。
(void)object;
}
```
- `size_t` - 当前固定为 `0`。
## 相关文档
- [返回类总览](LinearAllocator.md)
- [返回模块目录](../Memory.md)
- [返回类型总览](LinearAllocator.md)

24
docs/api/XCEngine/Memory/LinearAllocator/GetUsedSize.md
View File

@@ -1,30 +1,20 @@
# LinearAllocator::GetUsedSize
获取相关状态或对象。
查询当前已用大小。
```cpp
size_t GetUsedSize() const;
```
该方法声明于 `XCEngine/Memory/LinearAllocator.h`，当前页面用于固定 `LinearAllocator` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：** 无。
当前头文件内联实现返回 `m_offset`。语义与 [GetTotalAllocated](GetTotalAllocated.md) 相同。
**返回：** `size_t` - 返回值语义详见头文件声明。
## 返回值
**示例：**
```cpp
#include <XCEngine/Memory/LinearAllocator.h>
void Example() {
XCEngine::Memory::LinearAllocator object;
// 根据上下文补齐参数后调用 LinearAllocator::GetUsedSize(...)。
(void)object;
}
```
- `size_t` - 当前已用大小。
## 相关文档
- [返回类总览](LinearAllocator.md)
- [返回模块目录](../Memory.md)
- [返回类型总览](LinearAllocator.md)
- [GetTotalAllocated](GetTotalAllocated.md)

69
docs/api/XCEngine/Memory/LinearAllocator/LinearAllocator.md
View File

@@ -6,39 +6,58 @@
**头文件**: `XCEngine/Memory/LinearAllocator.h`
**描述**: 定义 `XCEngine/Memory` 子目录中的 `LinearAllocator` public API。
**描述**: 以单调递增偏移量分配内存的线性分配器，适合临时或批量释放场景。
## 概述
`LinearAllocator.h` 是 `XCEngine/Memory` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。
`LinearAllocator` 是典型的 bump / arena allocator：每次分配只推进一个偏移量，不跟踪单个块，也不支持逐块释放。它适合：
## 声明概览
- 帧级临时内存
- 批量构建后整体清空的中间数据
- 需要极低分配开销、但不要求单个对象回收的场景
| 声明 | 类型 | 说明 |
|------|------|------|
| `LinearAllocator` | `class` | 继承自 `IAllocator` 的公开声明。 |
## 生命周期与所有权
## 公共方法
- [Constructor](Constructor.md) 创建一块固定容量缓冲区。
- 如果传入父分配器，底层缓冲由父分配器提供并在析构时归还给父分配器。
- 如果没有父分配器，当前实现会直接在构造函数中申请原生内存。
- [Clear](Clear.md) 会把偏移量重置为零，相当于一次性回收所有线性分配结果。
| 方法 | 描述 |
## 当前实现限制
- [Free](Free.md) 目前是空实现，不会释放单个块。
- [Reallocate](Reallocate.md) 目前始终返回 `nullptr`。
- `GetMarker` / `SetMarker` 使用的是“偏移量令牌”，不是缓冲区中的真实指针。
- `GetPeakAllocated` 当前直接返回总容量，而不是历史峰值使用量。
- `GetAllocationCount` 当前始终返回 `0`。
- `Allocate` 会尝试处理对齐，但当前实现通过“增加消耗大小”而不是“返回对齐后的指针”来处理 padding，因此不要过度依赖高阶自定义对齐保证。
## 线程语义
- 当前没有锁；应由调用方在单线程或外部同步前提下使用。
## 公开方法
| 方法 | 说明 |
|------|------|
| [LinearAllocator()](Constructor.md) | 构造对象。 |
| [~LinearAllocator()](Destructor.md) | 销毁对象并释放相关资源。 |
| [Allocate](Allocate.md) | 公开方法，详见头文件声明。 |
| [Free](Free.md) | 公开方法，详见头文件声明。 |
| [Reallocate](Reallocate.md) | 公开方法，详见头文件声明。 |
| [Clear](Clear.md) | 清空内部数据。 |
| [GetMarker](GetMarker.md) | 获取相关状态或对象。 |
| [SetMarker](SetMarker.md) | 设置相关状态或配置。 |
| [GetUsedSize](GetUsedSize.md) | 获取相关状态或对象。 |
| [GetCapacity](GetCapacity.md) | 获取相关状态或对象。 |
| [GetName](GetName.md) | 获取相关状态或对象。 |
| [GetTotalAllocated](GetTotalAllocated.md) | 获取相关状态或对象。 |
| [GetTotalFreed](GetTotalFreed.md) | 获取相关状态或对象。 |
| [GetPeakAllocated](GetPeakAllocated.md) | 获取相关状态或对象。 |
| [GetAllocationCount](GetAllocationCount.md) | 获取相关状态或对象。 |
| [Constructor](Constructor.md) | 构造线性分配器。 |
| [Destructor](Destructor.md) | 销毁分配器并释放底层缓冲。 |
| [Allocate](Allocate.md) | 从当前偏移量分配一块内存。 |
| [Free](Free.md) | 释放单个块；当前为空实现。 |
| [Reallocate](Reallocate.md) | 重分配块；当前返回 `nullptr`。 |
| [Clear](Clear.md) | 清空所有线性分配结果。 |
| [GetMarker](GetMarker.md) | 获取当前偏移标记。 |
| [SetMarker](SetMarker.md) | 回退或推进到指定偏移标记。 |
| [GetUsedSize](GetUsedSize.md) | 查询当前已用大小。 |
| [GetCapacity](GetCapacity.md) | 查询总容量。 |
| [GetName](GetName.md) | 查询分配器名称。 |
| [GetTotalAllocated](GetTotalAllocated.md) | 查询当前已用字节数。 |
| [GetTotalFreed](GetTotalFreed.md) | 查询累计释放量；当前固定为 `0`。 |
| [GetPeakAllocated](GetPeakAllocated.md) | 查询峰值分配量；当前返回容量。 |
| [GetAllocationCount](GetAllocationCount.md) | 查询分配次数；当前固定为 `0`。 |
## 相关文档
- [当前目录](../Memory.md) - 返回 `Memory` 平行目录
- [API 总索引](../../../main.md) - 返回顶层索引
- [当前模块](../Memory.md)
- [IAllocator](../Allocator/Allocator.md)
- [Allocator Selection And Current Limits](../../../_guides/Memory/Allocator-Selection-And-Current-Limits.md)

27
docs/api/XCEngine/Memory/LinearAllocator/Reallocate.md
View File

@@ -1,32 +1,25 @@
# LinearAllocator::Reallocate
公开方法，详见头文件声明。
调整一块线性分配结果的大小。
```cpp
void* Reallocate(void* ptr, size_t newSize) override;
```
该方法声明于 `XCEngine/Memory/LinearAllocator.h`，当前页面用于固定 `LinearAllocator` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：**
- `ptr` - 参数语义详见头文件声明。
- `newSize` - 参数语义详见头文件声明。
当前实现直接返回 `nullptr`，没有任何重分配逻辑。
**返回：** `void*` - 返回值语义详见头文件声明。
## 参数
**示例：**
- `ptr` - 当前不会被使用。
- `newSize` - 当前不会被使用。
```cpp
#include <XCEngine/Memory/LinearAllocator.h>
## 返回值
void Example() {
XCEngine::Memory::LinearAllocator object;
// 根据上下文补齐参数后调用 LinearAllocator::Reallocate(...)。
(void)object;
}
```
- `void*` - 当前固定返回 `nullptr`。
## 相关文档
- [返回类总览](LinearAllocator.md)
- [返回模块目录](../Memory.md)
- [返回类型总览](LinearAllocator.md)
- [Allocate](Allocate.md)

33
docs/api/XCEngine/Memory/LinearAllocator/SetMarker.md
View File

@@ -1,31 +1,30 @@
# LinearAllocator::SetMarker
设置相关状态或配置。
把偏移量恢复到指定标记。
```cpp
void SetMarker(void* marker);
```
该方法声明于 `XCEngine/Memory/LinearAllocator.h`，当前页面用于固定 `LinearAllocator` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：**
- `marker` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。
**示例：**
当前实现会执行：
```cpp
#include <XCEngine/Memory/LinearAllocator.h>
void Example() {
XCEngine::Memory::LinearAllocator object;
// 根据上下文补齐参数后调用 LinearAllocator::SetMarker(...)。
(void)object;
}
m_offset = reinterpret_cast<size_t>(marker);
```
也就是说，`marker` 不是缓冲区中的真实指针，而应当来自 [GetMarker](GetMarker.md) 返回的偏移量令牌。
## 参数
- `marker` - 偏移量令牌。
## 返回值
- 无。
## 相关文档
- [返回类总览](LinearAllocator.md)
- [返回模块目录](../Memory.md)
- [返回类型总览](LinearAllocator.md)
- [GetMarker](GetMarker.md)

48
docs/api/XCEngine/Memory/Memory.md
View File

@@ -4,19 +4,51 @@
**类型**: `module`
**描述**: 分配器与内存管理。
**描述**: 提供分配器抽象、线性分配器、固定块池分配器、统计代理分配器以及全局内存工厂入口。
## 概览
## 概述
该目录与 `XCEngine/Memory` 对应的 public headers 保持平行，用于承载唯一的 canonical API 文档入口。
`XCEngine::Memory` 试图把“如何分配内存”从具体容器和系统模块中抽离出来。当前模块的公共 API 分成两层：
- `IAllocator` 定义统一分配器接口。
- `LinearAllocator`、`PoolAllocator` 和 `ProxyAllocator` 提供不同策略的具体实现。
- `MemoryManager` 负责初始化内部系统分配器并创建若干常用分配器对象。
这类设计在商业级引擎里很常见，因为不同场景对内存的需求完全不同：
- 帧级临时数据更适合 arena / linear allocator。
- 大量固定尺寸对象更适合 pool allocator。
- 调试和统计更适合在已有分配器外面套一层 proxy / tracking allocator。
## 当前实现成熟度
当前公开接口比实现完整度更大，需要把这点写清楚：
- `LinearAllocator` 的 `Free` 和 `Reallocate` 目前都是空实现或占位返回。
- `PoolAllocator` 的 `Reallocate` 目前返回 `nullptr`。
- `ProxyAllocator` 能转发分配，但其释放统计和重分配统计并不完整。
- `MemoryManager::DumpMemoryLeaks` 和 `GenerateMemoryReport` 目前只输出标题文本。
- `MemoryManager::SetTrackAllocations` 当前只修改标志位，没有驱动其它行为。
- 通过 `MemoryManager` 创建且依赖系统分配器的对象，当前仍需要调用方自己保证在 `Shutdown()` 前完成销毁。
## 设计要点
- 引擎级分配器 API 的价值，不在于替代系统 `malloc`，而在于为不同生命周期和数据形态提供更明确的分配策略。
- `IAllocator` 让容器和上层系统可以依赖抽象，而不是依赖某个具体分配器实现。
- `ProxyAllocator` 反映了“组合优于继承”的思路：统计逻辑可以叠加在任意底层分配器上。
- `MemoryManager` 当前更像工厂与引导入口，而不是完整的全局内存分析系统。
## 头文件
- [Allocator](Allocator/Allocator.md) - `Allocator.h`
- [LinearAllocator](LinearAllocator/LinearAllocator.md) - `LinearAllocator.h`
- [MemoryManager](MemoryManager/MemoryManager.md) - `MemoryManager.h`
- [PoolAllocator](PoolAllocator/PoolAllocator.md) - `PoolAllocator.h`
- [ProxyAllocator](ProxyAllocator/ProxyAllocator.md) - `ProxyAllocator.h`
- [Allocator](Allocator/Allocator.md) - `Allocator.h`，分配器抽象接口 `IAllocator`。
- [LinearAllocator](LinearAllocator/LinearAllocator.md) - `LinearAllocator.h`，线性/arena 风格分配器。
- [MemoryManager](MemoryManager/MemoryManager.md) - `MemoryManager.h`，系统分配器与工厂入口。
- [PoolAllocator](PoolAllocator/PoolAllocator.md) - `PoolAllocator.h`，固定块池分配器。
- [ProxyAllocator](ProxyAllocator/ProxyAllocator.md) - `ProxyAllocator.h`，统计代理分配器。
## 相关指南
- [Allocator Selection And Current Limits](../../_guides/Memory/Allocator-Selection-And-Current-Limits.md) - 解释各分配器适合什么场景、当前实现做到哪一步，以及与商业引擎常见内存策略的关系。
## 相关文档

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)

45
docs/api/XCEngine/Memory/PoolAllocator/Allocate.md
View File

@@ -1,32 +1,43 @@
# PoolAllocator::Allocate
公开方法，详见头文件声明。
从空闲链表中取出一个固定块。
```cpp
void* Allocate(size_t size, size_t alignment = 0) override;
```
该方法声明于 `XCEngine/Memory/PoolAllocator.h`，当前页面用于固定 `PoolAllocator` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：**
- `size` - 参数语义详见头文件声明。
- `alignment` - 参数语义详见头文件声明。
当前实现按以下顺序执行：
**返回：** `void*` - 返回值语义详见头文件声明。
1. 如果空闲链表为空，返回 `nullptr`。
2. 如果 `size > m_blockSize`，返回 `nullptr`。
3. 取出链表头节点，把 `m_freeBlocks` 减一。
4. 直接返回该节点地址。
**示例：**
需要特别注意：
```cpp
#include <XCEngine/Memory/PoolAllocator.h>
- `alignment` 参数在当前实现中被完全忽略。
- 只要 `size <= m_blockSize`，调用就会占用整个 block；不会按请求大小切分。
- `size == 0` 也会消耗一个 block。
- 返回地址来自构造阶段预先切好的池，不会在调用时再次向系统堆申请内存。
void Example() {
XCEngine::Memory::PoolAllocator object;
// 根据上下文补齐参数后调用 PoolAllocator::Allocate(...)。
(void)object;
}
```
## 参数
- `size` - 请求大小；必须不大于构造时的 `blockSize`。
- `alignment` - 调用期对齐要求；当前实现不使用它。
## 返回值
- `void*` - 成功时返回一个 block 的起始地址；池已耗尽或请求过大时返回 `nullptr`。
## 使用建议
- 把 `size` 理解为“上界检查”而不是“真实占用字节数”。
- 如果调用方依赖逐次调用时的不同对齐要求，当前实现并不满足这种需求。
## 相关文档
- [返回类总览](PoolAllocator.md)
- [返回模块目录](../Memory.md)
- [返回类型总览](PoolAllocator.md)
- [Free](Free.md)
- [Contains](Contains.md)

46
docs/api/XCEngine/Memory/PoolAllocator/Constructor.md
View File

@@ -1,31 +1,45 @@
# PoolAllocator::PoolAllocator()
# PoolAllocator::Constructor
构造对象。
构造一个固定块池分配器。
```cpp
PoolAllocator(size_t blockSize, size_t poolSize, size_t alignment = 8);
```
该方法声明于 `XCEngine/Memory/PoolAllocator.h`，当前页面用于固定 `PoolAllocator` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：**
- `blockSize` - 参数语义详见头文件声明。
- `poolSize` - 参数语义详见头文件声明。
- `alignment` - 参数语义详见头文件声明。
构造函数会一次性完成两件事：
**返回：** `void` - 无返回值。
1. 计算每个 block 的实际步长 `actualBlockSize`。
2. 申请一整块池内存，并把它串成单向空闲链表。
**示例：**
当 `alignment > 0` 时，当前实现使用下面的位运算向上取整：
```cpp
#include <XCEngine/Memory/PoolAllocator.h>
void Example() {
XCEngine::Memory::PoolAllocator object;
}
(blockSize + alignment - 1) & ~(alignment - 1)
```
随后它会调用 `std::malloc(actualBlockSize * poolSize)`，并在这块连续内存上建立空闲链表。
## 参数
- `blockSize` - 逻辑 block 大小，也是 [Allocate](Allocate.md) 允许的最大请求大小。
- `poolSize` - block 数量。
- `alignment` - block 步长对齐粒度；默认值为 `8`。
## 返回值
- 无。
## 当前实现限制
- 当前没有验证 `alignment` 是否是 2 的幂。
- 当前没有防御 `blockSize == 0`、`poolSize == 0` 或底层分配失败。
- 在 `poolSize == 0` 或 `malloc` 失败时，后续空闲链表初始化可能进入未定义行为，因此调用方应保证参数有效。
- 对齐只影响 block 步长，不保证 `malloc` 返回的池起始地址本身满足同样的高阶对齐要求。
## 相关文档
- [返回类总览](PoolAllocator.md)
- [返回模块目录](../Memory.md)
- [返回类型总览](PoolAllocator.md)
- [Destructor](Destructor.md)
- [GetBlockSize](GetBlockSize.md)

37
docs/api/XCEngine/Memory/PoolAllocator/Contains.md
View File

@@ -1,31 +1,36 @@
# PoolAllocator::Contains
公开方法，详见头文件声明。
判断指针是否落在当前池的地址范围内。
```cpp
bool Contains(void* ptr) const;
```
该方法声明于 `XCEngine/Memory/PoolAllocator.h`，当前页面用于固定 `PoolAllocator` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：**
- `ptr` - 参数语义详见头文件声明。
当前实现只做范围判断：
**返回：** `bool` - 返回值语义详见头文件声明。
1. 如果 `ptr == nullptr` 或 `m_memory == nullptr`，返回 `false`。
2. 计算 `ptr` 相对池起始地址的偏移。
3. 用构造阶段的实际 block 步长乘以 `m_totalBlocks`，得到整个池的地址范围。
4. 只要偏移仍在这个范围内，就返回 `true`。
**示例：**
这意味着：
```cpp
#include <XCEngine/Memory/PoolAllocator.h>
- 它是范围检查，不是“当前已分配块”的检查。
- 指向某个 block 中间位置的指针也可能返回 `true`。
- 已经释放回池的指针仍可能返回 `true`。
- 它不验证指针是否落在 block 边界上。
void Example() {
XCEngine::Memory::PoolAllocator object;
// 根据上下文补齐参数后调用 PoolAllocator::Contains(...)。
(void)object;
}
```
## 参数
- `ptr` - 待检测指针。
## 返回值
- `bool` - 指针位于池地址范围内时返回 `true`；否则返回 `false`。
## 相关文档
- [返回类总览](PoolAllocator.md)
- [返回模块目录](../Memory.md)
- [返回类型总览](PoolAllocator.md)
- [Free](Free.md)

34
docs/api/XCEngine/Memory/PoolAllocator/Destructor.md
View File

@@ -1,29 +1,31 @@
# PoolAllocator::~PoolAllocator()
# PoolAllocator::Destructor
销毁对象并释放相关资源。
销毁整个池并释放底层大块内存。
```cpp
~PoolAllocator() override;
```
该方法声明于 `XCEngine/Memory/PoolAllocator.h`，当前页面用于固定 `PoolAllocator` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：** 无。
**返回：** `void` - 无返回值。
**示例：**
当前实现只做一件事：
```cpp
#include <XCEngine/Memory/PoolAllocator.h>
void Example() {
XCEngine::Memory::PoolAllocator object;
// 对象离开作用域时会自动触发析构。
}
std::free(m_memory);
```
它不会遍历池中的对象，也不会为池中存放的 C++ 对象调用析构函数。换句话说，`PoolAllocator` 只负责原始内存块，不负责对象生命周期管理。
## 返回值
- 无。
## 使用建议
- 如果 block 中放的是需要析构的对象，应由调用方先显式析构对象，再销毁分配器。
- 分配器销毁后，之前返回的所有 block 指针都会变成悬空指针。
## 相关文档
- [返回类总览](PoolAllocator.md)
- [返回模块目录](../Memory.md)
- [返回类型总览](PoolAllocator.md)
- [Free](Free.md)

39
docs/api/XCEngine/Memory/PoolAllocator/Free.md
View File

@@ -1,31 +1,38 @@
# PoolAllocator::Free
公开方法，详见头文件声明。
把一个 block 放回空闲链表。
```cpp
void Free(void* ptr) override;
```
该方法声明于 `XCEngine/Memory/PoolAllocator.h`，当前页面用于固定 `PoolAllocator` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：**
- `ptr` - 参数语义详见头文件声明。
当前实现非常直接：
**返回：** `void` - 无返回值。
1. 如果 `ptr == nullptr`，直接返回。
2. 把 `ptr` 视为 `FreeNode*`。
3. 把该节点插回空闲链表头部。
4. 把 `m_freeBlocks` 加一。
**示例：**
## 参数
```cpp
#include <XCEngine/Memory/PoolAllocator.h>
- `ptr` - 要归还的 block 指针。
void Example() {
XCEngine::Memory::PoolAllocator object;
// 根据上下文补齐参数后调用 PoolAllocator::Free(...)。
(void)object;
}
```
## 返回值
- 无。
## 当前实现限制
- 不验证 `ptr` 是否真的来自当前池。
- 不验证 `ptr` 是否位于 block 边界。
- 不防止重复释放。
- 如果把不属于当前池的地址传进来，可能破坏空闲链表甚至直接写坏任意内存。
- 如果重复释放同一块，`m_freeBlocks` 可能大于 `m_totalBlocks`，随后统计接口会失真甚至发生无符号下溢。
## 相关文档
- [返回类总览](PoolAllocator.md)
- [返回模块目录](../Memory.md)
- [返回类型总览](PoolAllocator.md)
- [Allocate](Allocate.md)
- [Contains](Contains.md)

33
docs/api/XCEngine/Memory/PoolAllocator/GetAllocationCount.md
View File

@@ -1,30 +1,31 @@
# PoolAllocator::GetAllocationCount
获取相关状态或对象。
查询当前已分配 block 数量。
```cpp
size_t GetAllocationCount() const override;
```
该方法声明于 `XCEngine/Memory/PoolAllocator.h`，当前页面用于固定 `PoolAllocator` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：** 无。
**返回：** `size_t` - 返回值语义详见头文件声明。
**示例：**
当前头文件内联实现返回：
```cpp
#include <XCEngine/Memory/PoolAllocator.h>
void Example() {
XCEngine::Memory::PoolAllocator object;
// 根据上下文补齐参数后调用 PoolAllocator::GetAllocationCount(...)。
(void)object;
}
m_totalBlocks - m_freeBlocks
```
这反映的是“当前在用 block 数”，不是累计分配次数。
## 返回值
- `size_t` - 当前在用 block 数。
## 注意事项
- 这个值依赖 [Free](Free.md) 正确维护 `m_freeBlocks`。
- 如果发生重复释放或错误释放，`m_freeBlocks` 可能超过 `m_totalBlocks`，此处会出现无符号下溢并返回失真的大数值。
## 相关文档
- [返回类总览](PoolAllocator.md)
- [返回模块目录](../Memory.md)
- [返回类型总览](PoolAllocator.md)
- [GetFreeBlockCount](GetFreeBlockCount.md)

27
docs/api/XCEngine/Memory/PoolAllocator/GetBlockSize.md
View File

@@ -1,30 +1,27 @@
# PoolAllocator::GetBlockSize
获取相关状态或对象。
查询逻辑 block 大小。
```cpp
size_t GetBlockSize() const;
```
该方法声明于 `XCEngine/Memory/PoolAllocator.h`，当前页面用于固定 `PoolAllocator` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：** 无。
当前头文件内联实现直接返回 `m_blockSize`。
**返回：** `size_t` - 返回值语义详见头文件声明。
这表示的是 API 视角下的单块容量上限，也就是 [Allocate](Allocate.md) 允许的最大请求大小；它不一定等于构造时实际使用的 block 步长。
**示例：**
## 返回值
```cpp
#include <XCEngine/Memory/PoolAllocator.h>
- `size_t` - 逻辑 block 大小。
void Example() {
XCEngine::Memory::PoolAllocator object;
// 根据上下文补齐参数后调用 PoolAllocator::GetBlockSize(...)。
(void)object;
}
```
## 注意事项
- 如果构造时传入了较大的 `alignment`，实际池内存的 block 间距可能大于这里返回的值。
- [GetTotalAllocated](GetTotalAllocated.md)、[GetTotalFreed](GetTotalFreed.md) 和 [GetPeakAllocated](GetPeakAllocated.md) 也都是基于这个逻辑大小计算，而不是基于实际 stride。
## 相关文档
- [返回类总览](PoolAllocator.md)
- [返回模块目录](../Memory.md)
- [返回类型总览](PoolAllocator.md)
- [Constructor](Constructor.md)

25
docs/api/XCEngine/Memory/PoolAllocator/GetFreeBlockCount.md
View File

@@ -1,30 +1,25 @@
# PoolAllocator::GetFreeBlockCount
获取相关状态或对象。
查询当前空闲 block 数。
```cpp
size_t GetFreeBlockCount() const;
```
该方法声明于 `XCEngine/Memory/PoolAllocator.h`，当前页面用于固定 `PoolAllocator` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：** 无。
当前实现直接返回 `m_freeBlocks`。
**返回：** `size_t` - 返回值语义详见头文件声明。
## 返回值
**示例：**
- `size_t` - 当前空闲 block 数。
```cpp
#include <XCEngine/Memory/PoolAllocator.h>
## 注意事项
void Example() {
XCEngine::Memory::PoolAllocator object;
// 根据上下文补齐参数后调用 PoolAllocator::GetFreeBlockCount(...)。
(void)object;
}
```
- 这是一个“当前快照值”，不是历史统计。
- 如果调用方错误地传入无效指针或重复释放，`m_freeBlocks` 会被破坏，这里的结果也会随之失真。
## 相关文档
- [返回类总览](PoolAllocator.md)
- [返回模块目录](../Memory.md)
- [返回类型总览](PoolAllocator.md)
- [GetAllocationCount](GetAllocationCount.md)

25
docs/api/XCEngine/Memory/PoolAllocator/GetName.md
View File

@@ -1,30 +1,23 @@
# PoolAllocator::GetName
获取相关状态或对象。
查询分配器名称。
```cpp
const char* GetName() const override;
```
该方法声明于 `XCEngine/Memory/PoolAllocator.h`，当前页面用于固定 `PoolAllocator` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：** 无。
**返回：** `const char*` - 返回值语义详见头文件声明。
**示例：**
当前头文件内联实现固定返回字符串字面量：
```cpp
#include <XCEngine/Memory/PoolAllocator.h>
void Example() {
XCEngine::Memory::PoolAllocator object;
// 根据上下文补齐参数后调用 PoolAllocator::GetName(...)。
(void)object;
}
"PoolAllocator"
```
## 返回值
- `const char*` - 当前固定为 `"PoolAllocator"`。
## 相关文档
- [返回类总览](PoolAllocator.md)
- [返回模块目录](../Memory.md)
- [返回类型总览](PoolAllocator.md)

33
docs/api/XCEngine/Memory/PoolAllocator/GetPeakAllocated.md
View File

@@ -1,30 +1,31 @@
# PoolAllocator::GetPeakAllocated
获取相关状态或对象。
查询峰值分配量。
```cpp
size_t GetPeakAllocated() const override;
```
该方法声明于 `XCEngine/Memory/PoolAllocator.h`，当前页面用于固定 `PoolAllocator` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：** 无。
**返回：** `size_t` - 返回值语义详见头文件声明。
**示例：**
当前头文件内联实现返回：
```cpp
#include <XCEngine/Memory/PoolAllocator.h>
void Example() {
XCEngine::Memory::PoolAllocator object;
// 根据上下文补齐参数后调用 PoolAllocator::GetPeakAllocated(...)。
(void)object;
}
m_totalBlocks * m_blockSize
```
这并不是“历史上曾经达到过的最大已用字节数”，而是整个池按逻辑 block 大小计算的总容量上界。
## 返回值
- `size_t` - 当前实现下等于总池容量上界。
## 注意事项
- 如果你把它当作调试统计里的“历史峰值”，会得到过于乐观的结果。
- 这里同样不考虑对齐放大后的真实 stride。
## 相关文档
- [返回类总览](PoolAllocator.md)
- [返回模块目录](../Memory.md)
- [返回类型总览](PoolAllocator.md)
- [GetTotalAllocated](GetTotalAllocated.md)

33
docs/api/XCEngine/Memory/PoolAllocator/GetTotalAllocated.md
View File

@@ -1,30 +1,31 @@
# PoolAllocator::GetTotalAllocated
获取相关状态或对象。
查询当前已用字节数。
```cpp
size_t GetTotalAllocated() const override;
```
该方法声明于 `XCEngine/Memory/PoolAllocator.h`，当前页面用于固定 `PoolAllocator` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：** 无。
**返回：** `size_t` - 返回值语义详见头文件声明。
**示例：**
当前头文件内联实现返回：
```cpp
#include <XCEngine/Memory/PoolAllocator.h>
void Example() {
XCEngine::Memory::PoolAllocator object;
// 根据上下文补齐参数后调用 PoolAllocator::GetTotalAllocated(...)。
(void)object;
}
(m_totalBlocks - m_freeBlocks) * m_blockSize
```
因此它表示的是“当前正在使用的逻辑字节数”，而不是累计分配过多少字节。
## 返回值
- `size_t` - 当前已用逻辑字节数。
## 注意事项
- 这里按 `m_blockSize` 计费，不按对齐后的实际 stride 计费。
- 如果 `m_freeBlocks` 因错误释放被破坏，这个值也会失真。
## 相关文档
- [返回类总览](PoolAllocator.md)
- [返回模块目录](../Memory.md)
- [返回类型总览](PoolAllocator.md)
- [GetTotalFreed](GetTotalFreed.md)

24
docs/api/XCEngine/Memory/PoolAllocator/GetTotalBlockCount.md
View File

@@ -1,30 +1,20 @@
# PoolAllocator::GetTotalBlockCount
获取相关状态或对象。
查询池中的总 block 数。
```cpp
size_t GetTotalBlockCount() const;
```
该方法声明于 `XCEngine/Memory/PoolAllocator.h`，当前页面用于固定 `PoolAllocator` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：** 无。
当前头文件内联实现直接返回 `m_totalBlocks`，也就是构造时指定的 block 数量。
**返回：** `size_t` - 返回值语义详见头文件声明。
## 返回值
**示例：**
```cpp
#include <XCEngine/Memory/PoolAllocator.h>
void Example() {
XCEngine::Memory::PoolAllocator object;
// 根据上下文补齐参数后调用 PoolAllocator::GetTotalBlockCount(...)。
(void)object;
}
```
- `size_t` - 池的总 block 数。
## 相关文档
- [返回类总览](PoolAllocator.md)
- [返回模块目录](../Memory.md)
- [返回类型总览](PoolAllocator.md)
- [GetFreeBlockCount](GetFreeBlockCount.md)

33
docs/api/XCEngine/Memory/PoolAllocator/GetTotalFreed.md
View File

@@ -1,30 +1,31 @@
# PoolAllocator::GetTotalFreed
获取相关状态或对象。
查询当前空闲字节数。
```cpp
size_t GetTotalFreed() const override;
```
该方法声明于 `XCEngine/Memory/PoolAllocator.h`，当前页面用于固定 `PoolAllocator` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：** 无。
**返回：** `size_t` - 返回值语义详见头文件声明。
**示例：**
当前头文件内联实现返回：
```cpp
#include <XCEngine/Memory/PoolAllocator.h>
void Example() {
XCEngine::Memory::PoolAllocator object;
// 根据上下文补齐参数后调用 PoolAllocator::GetTotalFreed(...)。
(void)object;
}
m_freeBlocks * m_blockSize
```
因此这个接口在 `PoolAllocator` 中表示的是“当前还空着多少逻辑字节”，不是“累计向系统释放了多少字节”。整个池在分配器存活期间始终保留在进程内存中，直到析构时才统一释放。
## 返回值
- `size_t` - 当前空闲逻辑字节数。
## 注意事项
- 这里同样不考虑对齐放大的真实 stride。
- 如果发生错误释放，`m_freeBlocks` 失真，这里的统计也会随之失真。
## 相关文档
- [返回类总览](PoolAllocator.md)
- [返回模块目录](../Memory.md)
- [返回类型总览](PoolAllocator.md)
- [GetTotalAllocated](GetTotalAllocated.md)

67
docs/api/XCEngine/Memory/PoolAllocator/PoolAllocator.md
View File

@@ -6,38 +6,57 @@
**头文件**: `XCEngine/Memory/PoolAllocator.h`
**描述**: 定义 `XCEngine/Memory` 子目录中的 `PoolAllocator` public API。
**描述**: 为固定尺寸对象提供 O(1) 弹出/归还的池分配器。
## 概述
`PoolAllocator.h` 是 `XCEngine/Memory` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。
`PoolAllocator` 预先申请一整块内存，然后把它切成固定尺寸的 block，通过空闲链表管理这些 block。它适合：
## 声明概览
- 大量尺寸相同或尺寸上界稳定的小对象
- 频繁分配和释放、但不想承担通用堆分配碎片与额外元数据开销的场景
| 声明 | 类型 | 说明 |
|------|------|------|
| `PoolAllocator` | `class` | 继承自 `IAllocator` 的公开声明。 |
## 生命周期与所有权
## 公共方法
- [Constructor](Constructor.md) 一次性申请整个池。
- [Allocate](Allocate.md) 从空闲链表弹出一个 block。
- [Free](Free.md) 把 block 放回空闲链表头部。
- [Destructor](Destructor.md) 在整个池销毁时一次性释放底层内存。
| 方法 | 描述 |
## 当前实现限制
- [Reallocate](Reallocate.md) 当前返回 `nullptr`。
- `Allocate` 忽略调用时传入的 `alignment` 参数，真正使用的是构造阶段保存的对齐设置。
- 对齐逻辑当前只影响 block stride 计算，不保证底层池起始地址本身按该对齐值申请。
- 构造函数当前不校验 `blockSize > 0`、`poolSize > 0`，也不处理底层内存申请失败后的初始化路径。
- [Free](Free.md) 不检查指针是否真的来自当前池，也不防止重复释放。
- [Contains](Contains.md) 当前只检查“是否落在池的地址范围内”，不检查是否对齐到 block 边界，也不检查块是否仍在分配状态。
- `GetPeakAllocated` 当前返回整个池的总容量，而不是历史峰值使用量。
## 线程语义
- 当前没有锁；需要外部同步。
## 公开方法
| 方法 | 说明 |
|------|------|
| [PoolAllocator()](Constructor.md) | 构造对象。 |
| [~PoolAllocator()](Destructor.md) | 销毁对象并释放相关资源。 |
| [Allocate](Allocate.md) | 公开方法，详见头文件声明。 |
| [Free](Free.md) | 公开方法，详见头文件声明。 |
| [Reallocate](Reallocate.md) | 公开方法，详见头文件声明。 |
| [Contains](Contains.md) | 公开方法，详见头文件声明。 |
| [GetBlockSize](GetBlockSize.md) | 获取相关状态或对象。 |
| [GetFreeBlockCount](GetFreeBlockCount.md) | 获取相关状态或对象。 |
| [GetTotalBlockCount](GetTotalBlockCount.md) | 获取相关状态或对象。 |
| [GetName](GetName.md) | 获取相关状态或对象。 |
| [GetTotalAllocated](GetTotalAllocated.md) | 获取相关状态或对象。 |
| [GetTotalFreed](GetTotalFreed.md) | 获取相关状态或对象。 |
| [GetPeakAllocated](GetPeakAllocated.md) | 获取相关状态或对象。 |
| [GetAllocationCount](GetAllocationCount.md) | 获取相关状态或对象。 |
| [Constructor](Constructor.md) | 构造固定块池分配器。 |
| [Destructor](Destructor.md) | 销毁整个池。 |
| [Allocate](Allocate.md) | 分配一个 block。 |
| [Free](Free.md) | 归还一个 block。 |
| [Reallocate](Reallocate.md) | 重分配 block；当前返回 `nullptr`。 |
| [Contains](Contains.md) | 判断指针是否位于池地址范围内。 |
| [GetBlockSize](GetBlockSize.md) | 查询逻辑 block 大小。 |
| [GetFreeBlockCount](GetFreeBlockCount.md) | 查询空闲 block 数。 |
| [GetTotalBlockCount](GetTotalBlockCount.md) | 查询总 block 数。 |
| [GetName](GetName.md) | 查询分配器名称。 |
| [GetTotalAllocated](GetTotalAllocated.md) | 查询当前已用字节数。 |
| [GetTotalFreed](GetTotalFreed.md) | 查询当前空闲字节数。 |
| [GetPeakAllocated](GetPeakAllocated.md) | 查询峰值分配量；当前返回总池容量。 |
| [GetAllocationCount](GetAllocationCount.md) | 查询当前已分配 block 数。 |
## 相关文档
- [当前目录](../Memory.md) - 返回 `Memory` 平行目录
- [API 总索引](../../../main.md) - 返回顶层索引
- [当前模块](../Memory.md)
- [IAllocator](../Allocator/Allocator.md)
- [Allocator Selection And Current Limits](../../../_guides/Memory/Allocator-Selection-And-Current-Limits.md)

31
docs/api/XCEngine/Memory/PoolAllocator/Reallocate.md
View File

@@ -1,32 +1,29 @@
# PoolAllocator::Reallocate
公开方法，详见头文件声明。
重分配一个 block。
```cpp
void* Reallocate(void* ptr, size_t newSize) override;
```
该方法声明于 `XCEngine/Memory/PoolAllocator.h`，当前页面用于固定 `PoolAllocator` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：**
- `ptr` - 参数语义详见头文件声明。
- `newSize` - 参数语义详见头文件声明。
当前实现没有真正支持可变尺寸重分配，函数体固定返回 `nullptr`，也不会读取 `ptr` 或 `newSize`。
**返回：** `void*` - 返回值语义详见头文件声明。
## 参数
**示例：**
- `ptr` - 原 block 指针；当前实现忽略。
- `newSize` - 新大小；当前实现忽略。
```cpp
#include <XCEngine/Memory/PoolAllocator.h>
## 返回值
void Example() {
XCEngine::Memory::PoolAllocator object;
// 根据上下文补齐参数后调用 PoolAllocator::Reallocate(...)。
(void)object;
}
```
- `void*` - 当前固定返回 `nullptr`。
## 设计说明
这与池分配器的典型定位一致：它更适合固定尺寸对象，而不是 `realloc` 风格的可变尺寸缓冲。
## 相关文档
- [返回类总览](PoolAllocator.md)
- [返回模块目录](../Memory.md)
- [返回类型总览](PoolAllocator.md)
- [Allocate](Allocate.md)

41
docs/api/XCEngine/Memory/ProxyAllocator/Allocate.md
View File

@@ -1,32 +1,39 @@
# ProxyAllocator::Allocate
公开方法，详见头文件声明。
通过底层分配器申请内存，并更新代理统计。
```cpp
void* Allocate(size_t size, size_t alignment = 0) override;
```
该方法声明于 `XCEngine/Memory/ProxyAllocator.h`，当前页面用于固定 `ProxyAllocator` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：**
- `size` - 参数语义详见头文件声明。
- `alignment` - 参数语义详见头文件声明。
当前实现会先加锁，然后执行以下逻辑：
**返回：** `void*` - 返回值语义详见头文件声明。
1. 调用 `m_underlying->Allocate(size, alignment)`。
2. 如果返回非空：
- `m_stats.totalAllocated += size`
- `m_stats.allocationCount++`
- 用 `m_stats.totalAllocated - m_stats.totalFreed` 更新 `m_stats.peakAllocated`
3. 返回底层分配器给出的指针。
**示例：**
## 参数
```cpp
#include <XCEngine/Memory/ProxyAllocator.h>
- `size` - 请求大小；成功时会按这个值计入 `totalAllocated`。
- `alignment` - 对齐要求；当前只是原样转发到底层分配器。
void Example() {
XCEngine::Memory::ProxyAllocator object;
// 根据上下文补齐参数后调用 ProxyAllocator::Allocate(...)。
(void)object;
}
```
## 返回值
- `void*` - 底层分配器返回的指针；失败时通常为 `nullptr`。
## 注意事项
- 统计记录的是“请求大小”，不是底层分配器真实消耗的字节数。
- 如果 `m_underlying == nullptr`，当前实现会直接解引用空指针。
- 由于 [Free](Free.md) 的释放统计存在缺陷，这里的峰值更新也可能被连带污染。
## 相关文档
- [返回类总览](ProxyAllocator.md)
- [返回模块目录](../Memory.md)
- [返回类型总览](ProxyAllocator.md)
- [Free](Free.md)
- [GetStats](GetStats.md)

38
docs/api/XCEngine/Memory/ProxyAllocator/Constructor.md
View File

@@ -1,30 +1,36 @@
# ProxyAllocator::ProxyAllocator()
# ProxyAllocator::Constructor
构造对象。
构造一个代理分配器。
```cpp
ProxyAllocator(IAllocator* underlying, const char* name);
```
该方法声明于 `XCEngine/Memory/ProxyAllocator.h`，当前页面用于固定 `ProxyAllocator` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：**
- `underlying` - 参数语义详见头文件声明。
- `name` - 参数语义详见头文件声明。
当前构造函数只做成员保存：
**返回：** `void` - 无返回值。
- `m_underlying = underlying`
- `m_name = name`
**示例：**
它不会复制名称字符串，也不会接管底层分配器所有权。
```cpp
#include <XCEngine/Memory/ProxyAllocator.h>
## 参数
void Example() {
XCEngine::Memory::ProxyAllocator object;
}
```
- `underlying` - 被代理的底层分配器。
- `name` - 代理名称。
## 返回值
- 无。
## 当前实现限制
- 不校验 `underlying` 是否为空。
- 不复制 `name` 内容，只保存原始指针。
- 调用方必须保证底层分配器和名称字符串在 `ProxyAllocator` 生命周期内保持有效。
## 相关文档
- [返回类总览](ProxyAllocator.md)
- [返回模块目录](../Memory.md)
- [返回类型总览](ProxyAllocator.md)
- [GetName](GetName.md)

37
docs/api/XCEngine/Memory/ProxyAllocator/Free.md
View File

@@ -1,31 +1,36 @@
# ProxyAllocator::Free
公开方法，详见头文件声明。
通过底层分配器释放内存，并更新代理统计。
```cpp
void Free(void* ptr) override;
```
该方法声明于 `XCEngine/Memory/ProxyAllocator.h`，当前页面用于固定 `ProxyAllocator` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：**
- `ptr` - 参数语义详见头文件声明。
当前实现会先加锁，然后执行：
**返回：** `void` - 无返回值。
1. 调用 `m_underlying->Free(ptr)`。
2. 执行 `m_stats.totalFreed += m_stats.allocationCount`。
3. 执行 `m_stats.allocationCount--`。
**示例：**
## 参数
```cpp
#include <XCEngine/Memory/ProxyAllocator.h>
- `ptr` - 要释放的指针。
void Example() {
XCEngine::Memory::ProxyAllocator object;
// 根据上下文补齐参数后调用 ProxyAllocator::Free(...)。
(void)object;
}
```
## 返回值
- 无。
## 当前实现限制
- `totalFreed` 增加的是“当前 allocation count”，不是被释放块的真实字节数。
- 如果 `allocationCount` 当前为 `0`，执行 `m_stats.allocationCount--` 会发生无符号下溢。
- `ptr` 是否允许为 `nullptr`，取决于底层分配器；代理层没有额外保护。
- 如果 `m_underlying == nullptr`，当前实现会直接解引用空指针。
## 相关文档
- [返回类总览](ProxyAllocator.md)
- [返回模块目录](../Memory.md)
- [返回类型总览](ProxyAllocator.md)
- [Allocate](Allocate.md)
- [GetTotalFreed](GetTotalFreed.md)

25
docs/api/XCEngine/Memory/ProxyAllocator/GetAllocationCount.md
View File

@@ -1,30 +1,25 @@
# ProxyAllocator::GetAllocationCount
获取相关状态或对象。
查询当前统计中的分配计数。
```cpp
size_t GetAllocationCount() const override;
```
该方法声明于 `XCEngine/Memory/ProxyAllocator.h`，当前页面用于固定 `ProxyAllocator` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：** 无。
当前头文件内联实现直接返回 `m_stats.allocationCount`。
**返回：** `size_t` - 返回值语义详见头文件声明。
## 返回值
**示例：**
- `size_t` - 代理内部记录的分配计数。
```cpp
#include <XCEngine/Memory/ProxyAllocator.h>
## 注意事项
void Example() {
XCEngine::Memory::ProxyAllocator object;
// 根据上下文补齐参数后调用 ProxyAllocator::GetAllocationCount(...)。
(void)object;
}
```
- 这不是底层分配器的权威状态，而是代理层自己的统计字段。
- 由于 [Free](Free.md) 可能发生下溢、[Reallocate](Reallocate.md) 又不调整统计，这个值不应被当作严格可信的实时分配数。
## 相关文档
- [返回类总览](ProxyAllocator.md)
- [返回模块目录](../Memory.md)
- [返回类型总览](ProxyAllocator.md)
- [GetStats](GetStats.md)

24
docs/api/XCEngine/Memory/ProxyAllocator/GetName.md
View File

@@ -1,30 +1,24 @@
# ProxyAllocator::GetName
获取相关状态或对象。
查询代理名称。
```cpp
const char* GetName() const override;
```
该方法声明于 `XCEngine/Memory/ProxyAllocator.h`，当前页面用于固定 `ProxyAllocator` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：** 无。
当前头文件内联实现直接返回 `m_name`。
**返回：** `const char*` - 返回值语义详见头文件声明。
## 返回值
**示例：**
- `const char*` - 构造时传入的名称指针。
```cpp
#include <XCEngine/Memory/ProxyAllocator.h>
## 注意事项
void Example() {
XCEngine::Memory::ProxyAllocator object;
// 根据上下文补齐参数后调用 ProxyAllocator::GetName(...)。
(void)object;
}
```
- 名称字符串不会被复制；如果原始字符串失效，这里返回的就是悬空指针。
## 相关文档
- [返回类总览](ProxyAllocator.md)
- [返回模块目录](../Memory.md)
- [返回类型总览](ProxyAllocator.md)
- [Constructor](Constructor.md)

31
docs/api/XCEngine/Memory/ProxyAllocator/GetPeakAllocated.md
View File

@@ -1,30 +1,31 @@
# ProxyAllocator::GetPeakAllocated
获取相关状态或对象。
查询峰值净分配量。
```cpp
size_t GetPeakAllocated() const override;
```
该方法声明于 `XCEngine/Memory/ProxyAllocator.h`，当前页面用于固定 `ProxyAllocator` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：** 无。
当前头文件内联实现直接返回 `m_stats.peakAllocated`。
**返回：** `size_t` - 返回值语义详见头文件声明。
**示例：**
这个字段只会在 [Allocate](Allocate.md) 成功时更新，更新依据是：
```cpp
#include <XCEngine/Memory/ProxyAllocator.h>
void Example() {
XCEngine::Memory::ProxyAllocator object;
// 根据上下文补齐参数后调用 ProxyAllocator::GetPeakAllocated(...)。
(void)object;
}
m_stats.totalAllocated - m_stats.totalFreed
```
## 返回值
- `size_t` - 代理层记录的峰值净分配量。
## 注意事项
- 由于 `totalFreed` 的统计当前有缺陷，这里的峰值也可能失真。
- [Reallocate](Reallocate.md) 不更新统计，因此大缓冲重分配不会反映到峰值里。
## 相关文档
- [返回类总览](ProxyAllocator.md)
- [返回模块目录](../Memory.md)
- [返回类型总览](ProxyAllocator.md)
- [GetTotalAllocated](GetTotalAllocated.md)

34
docs/api/XCEngine/Memory/ProxyAllocator/GetStats.md
View File

@@ -1,30 +1,34 @@
# ProxyAllocator::GetStats
获取相关状态或对象。
读取完整统计结构。
```cpp
const Stats& GetStats() const;
```
该方法声明于 `XCEngine/Memory/ProxyAllocator.h`，当前页面用于固定 `ProxyAllocator` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：** 无。
当前实现直接返回内部成员 `m_stats` 的常量引用，不会复制数据，也不会在读取时加锁。
**返回：** `const Stats&` - 返回值语义详见头文件声明。
`Stats` 结构当前包含这些字段：
**示例：**
- `totalAllocated`
- `totalFreed`
- `peakAllocated`
- `allocationCount`
- `memoryOverhead`
```cpp
#include <XCEngine/Memory/ProxyAllocator.h>
## 返回值
void Example() {
XCEngine::Memory::ProxyAllocator object;
// 根据上下文补齐参数后调用 ProxyAllocator::GetStats(...)。
(void)object;
}
```
- `const Stats&` - 指向内部统计结构的只读引用。
## 注意事项
- 这是对内部状态的直接暴露，不适合在并发写入期间无保护读取。
- `memoryOverhead` 字段当前始终保持默认值 `0`。
- `totalFreed` 和由它推导出的字段目前不完全准确。
## 相关文档
- [返回类总览](ProxyAllocator.md)
- [返回模块目录](../Memory.md)
- [返回类型总览](ProxyAllocator.md)
- [GetAllocationCount](GetAllocationCount.md)

27
docs/api/XCEngine/Memory/ProxyAllocator/GetTotalAllocated.md
View File

@@ -1,30 +1,27 @@
# ProxyAllocator::GetTotalAllocated
获取相关状态或对象。
查询累计分配字节数。
```cpp
size_t GetTotalAllocated() const override;
```
该方法声明于 `XCEngine/Memory/ProxyAllocator.h`，当前页面用于固定 `ProxyAllocator` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：** 无。
当前头文件内联实现直接返回 `m_stats.totalAllocated`。
**返回：** `size_t` - 返回值语义详见头文件声明。
这个字段在 [Allocate](Allocate.md) 成功时按“请求大小”累加，不会向底层分配器反查真实消耗。
**示例：**
## 返回值
```cpp
#include <XCEngine/Memory/ProxyAllocator.h>
- `size_t` - 代理层记录的累计请求字节数。
void Example() {
XCEngine::Memory::ProxyAllocator object;
// 根据上下文补齐参数后调用 ProxyAllocator::GetTotalAllocated(...)。
(void)object;
}
```
## 注意事项
- 这不是底层分配器的精确字节记账。
- 当前读取路径没有加锁，更适合在受控快照点使用。
## 相关文档
- [返回类总览](ProxyAllocator.md)
- [返回模块目录](../Memory.md)
- [返回类型总览](ProxyAllocator.md)
- [GetTotalFreed](GetTotalFreed.md)

27
docs/api/XCEngine/Memory/ProxyAllocator/GetTotalFreed.md
View File

@@ -1,30 +1,27 @@
# ProxyAllocator::GetTotalFreed
获取相关状态或对象。
查询累计释放字节数。
```cpp
size_t GetTotalFreed() const override;
```
该方法声明于 `XCEngine/Memory/ProxyAllocator.h`，当前页面用于固定 `ProxyAllocator` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：** 无。
当前头文件内联实现直接返回 `m_stats.totalFreed`。
**返回：** `size_t` - 返回值语义详见头文件声明。
但这个字段的写入逻辑有明显缺陷：[Free](Free.md) 并不是按被释放块大小累加，而是把“调用当时的 allocation count”加进来。
**示例：**
## 返回值
```cpp
#include <XCEngine/Memory/ProxyAllocator.h>
- `size_t` - 代理层当前记录的释放统计值。
void Example() {
XCEngine::Memory::ProxyAllocator object;
// 根据上下文补齐参数后调用 ProxyAllocator::GetTotalFreed(...)。
(void)object;
}
```
## 注意事项
- 这个值当前不代表真实释放字节数。
- 基于它计算的净分配量和峰值也会受影响。
## 相关文档
- [返回类总览](ProxyAllocator.md)
- [返回模块目录](../Memory.md)
- [返回类型总览](ProxyAllocator.md)
- [Free](Free.md)

60
docs/api/XCEngine/Memory/ProxyAllocator/ProxyAllocator.md
View File

@@ -6,34 +6,54 @@
**头文件**: `XCEngine/Memory/ProxyAllocator.h`
**描述**: 定义 `XCEngine/Memory` 子目录中的 `ProxyAllocator` public API。
**描述**: 在已有分配器外面包一层统计逻辑的代理分配器。
## 概述
`ProxyAllocator.h` 是 `XCEngine/Memory` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。
`ProxyAllocator` 不直接拥有原始堆，而是把所有内存操作转发给底层分配器，并在外层记录统计信息。这种设计适合：
## 声明概览
- 调试某个子系统的内存使用
- 给同一个底层分配器增加具名统计视图
- 在不改底层分配器实现的前提下，追加追踪逻辑
| 声明 | 类型 | 说明 |
|------|------|------|
| `ProxyAllocator` | `class` | 继承自 `IAllocator` 的公开声明。 |
## 所有权
## 公共方法
- [Constructor](Constructor.md) 接收一个底层 `IAllocator*` 和一个名称。
- 当前 `ProxyAllocator` 不拥有底层分配器，不会在销毁时释放它。
- 当前实现既不校验底层分配器是否为空，也不复制名称字符串。
- `MemoryManager::CreateProxyAllocator` 当前总是包装系统分配器，而不是任意自定义底层分配器。
| 方法 | 描述 |
## 当前实现限制
- [Free](Free.md) 会把 `totalFreed` 增加为“当前 allocation count”，而不是被释放块的真实大小，因此释放字节统计当前并不准确。
- [Reallocate](Reallocate.md) 只转发调用，不更新统计信息。
- 如果底层分配器失效或被提前销毁，后续所有代理操作都可能触发未定义行为。
- `GetStats()` 返回内部结构体引用，当前没有为只读访问额外加锁。
- `memoryOverhead` 字段存在，但当前没有被维护。
## 线程语义
- `Allocate`、`Free` 和 `Reallocate` 当前在内部使用 `Threading::Mutex` 保护统计更新。
- `GetStats()` 是无锁只读返回；更适合在无并发修改或调试快照场景下读取。
## 公开方法
| 方法 | 说明 |
|------|------|
| [ProxyAllocator()](Constructor.md) | 构造对象。 |
| [Allocate](Allocate.md) | 公开方法，详见头文件声明。 |
| [Free](Free.md) | 公开方法，详见头文件声明。 |
| [Reallocate](Reallocate.md) | 公开方法，详见头文件声明。 |
| [GetTotalAllocated](GetTotalAllocated.md) | 获取相关状态或对象。 |
| [GetTotalFreed](GetTotalFreed.md) | 获取相关状态或对象。 |
| [GetPeakAllocated](GetPeakAllocated.md) | 获取相关状态或对象。 |
| [GetAllocationCount](GetAllocationCount.md) | 获取相关状态或对象。 |
| [GetStats](GetStats.md) | 获取相关状态或对象。 |
| [GetName](GetName.md) | 获取相关状态或对象。 |
| [Constructor](Constructor.md) | 构造代理分配器。 |
| [Allocate](Allocate.md) | 通过底层分配器分配，并更新统计。 |
| [Free](Free.md) | 通过底层分配器释放，并更新统计。 |
| [Reallocate](Reallocate.md) | 转发重分配。 |
| [GetTotalAllocated](GetTotalAllocated.md) | 查询累计分配字节。 |
| [GetTotalFreed](GetTotalFreed.md) | 查询累计释放字节。 |
| [GetPeakAllocated](GetPeakAllocated.md) | 查询峰值净分配量。 |
| [GetAllocationCount](GetAllocationCount.md) | 查询当前统计中的分配计数。 |
| [GetStats](GetStats.md) | 读取完整统计结构。 |
| [GetName](GetName.md) | 查询代理名称。 |
## 相关文档
- [当前目录](../Memory.md) - 返回 `Memory` 平行目录
- [API 总索引](../../../main.md) - 返回顶层索引
- [当前模块](../Memory.md)
- [IAllocator](../Allocator/Allocator.md)
- [MemoryManager](../MemoryManager/MemoryManager.md)
- [Allocator Selection And Current Limits](../../../_guides/Memory/Allocator-Selection-And-Current-Limits.md)

39
docs/api/XCEngine/Memory/ProxyAllocator/Reallocate.md
View File

@@ -1,32 +1,35 @@
# ProxyAllocator::Reallocate
公开方法，详见头文件声明。
通过底层分配器重分配内存。
```cpp
void* Reallocate(void* ptr, size_t newSize) override;
```
该方法声明于 `XCEngine/Memory/ProxyAllocator.h`，当前页面用于固定 `ProxyAllocator` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：**
- `ptr` - 参数语义详见头文件声明。
- `newSize` - 参数语义详见头文件声明。
**返回：** `void*` - 返回值语义详见头文件声明。
**示例：**
当前实现会先加锁，然后仅做一件事：
```cpp
#include <XCEngine/Memory/ProxyAllocator.h>
void Example() {
XCEngine::Memory::ProxyAllocator object;
// 根据上下文补齐参数后调用 ProxyAllocator::Reallocate(...)。
(void)object;
}
return m_underlying->Reallocate(ptr, newSize);
```
## 参数
- `ptr` - 原指针。
- `newSize` - 新大小。
## 返回值
- `void*` - 底层分配器返回的新指针。
## 当前实现限制
- 不更新 `totalAllocated`、`totalFreed`、`peakAllocated` 或 `allocationCount`。
- 如果底层分配器会移动内存，这里的返回值可能与 `ptr` 不同。
- 如果 `m_underlying == nullptr`，当前实现会直接解引用空指针。
## 相关文档
- [返回类总览](ProxyAllocator.md)
- [返回模块目录](../Memory.md)
- [返回类型总览](ProxyAllocator.md)
- [Allocate](Allocate.md)

124
docs/api/_guides/Memory/Allocator-Selection-And-Current-Limits.md Normal file
View File

@@ -0,0 +1,124 @@
# Allocator Selection And Current Limits
## 为什么引擎要有多种分配器
商业级引擎不会把所有内存都交给一套通用堆分配器。原因很现实：
- 帧级临时数据的生命周期极短，逐块释放反而是额外成本。
- 大量固定尺寸对象如果走通用堆，碎片和元数据开销通常不划算。
- 调试阶段又往往需要单独统计某个系统到底分了多少内存。
这就是 `XCEngine::Memory` 当前这组 API 的设计出发点。
## 现在这几个分配器分别适合什么
### `LinearAllocator`
适合：
- 一整批数据统一释放
- 帧级或阶段级临时内存
- 极低开销的顺序分配
不适合：
- 需要单个对象独立释放
- 需要通用 `realloc`
如果你熟悉 Unity 或其它引擎，可以把它理解为更接近 arena / frame allocator 这一类思路，而不是常驻对象堆。
### `PoolAllocator`
适合：
- 固定尺寸或尺寸上界稳定的对象
- 高频分配 / 释放
- 想避免通用堆碎片
不适合：
- 大小变化大的对象
- 需要可变尺寸重分配
### `ProxyAllocator`
适合：
- 给现有分配器加统计视图
- 调试某个系统的内存用量
- 不想修改底层分配器实现，但想额外记录指标
不适合：
- 被当作完整可信的内存分析器
## 当前版本最需要诚实面对的事
这套模块已经有了不错的 API 形状，但实现还没有完全跟上。
最重要的限制有这些：
- `LinearAllocator::Free` 和 `Reallocate` 还没有完成。
- `PoolAllocator::Reallocate` 还没有完成。
- `ProxyAllocator` 的释放统计当前不准确。
- `MemoryManager` 的泄漏和报表接口现在只是占位输出。
- 部分统计方法名字很强，但当前返回值更接近“固定上界”而不是真实历史峰值。
- 通过 `MemoryManager` 创建且依赖系统分配器的对象，目前仍要求调用方在 `Shutdown()` 之前主动销毁。
这意味着当前更合理的使用方式是：
- 把这些分配器当作明确生命周期的工具型组件；
- 不要把它们当成已经完备的内存诊断平台。
## 如何选择
如果你只是要一块批量临时内存：
```cpp
auto allocator = XCEngine::Memory::MemoryManager::Get().CreateLinearAllocator(1024 * 1024);
```
如果你要大量固定尺寸对象：
```cpp
auto allocator = XCEngine::Memory::MemoryManager::Get().CreatePoolAllocator(sizeof(MyNode), 1024);
```
如果你要统计某个系统的分配情况：
```cpp
auto allocator = XCEngine::Memory::MemoryManager::Get().CreateProxyAllocator("RenderGraph");
```
这里还要额外记住一点：
- `CreateProxyAllocator()` 应在 `Initialize()` 之后调用。
- `CreateLinearAllocator()` 如果绑定了系统分配器作为父分配器，也应在 `Shutdown()` 前完成销毁。
## 为什么要保留 `IAllocator`
`IAllocator` 的价值不在“虚函数本身”，而在于它允许上层容器和子系统表达“我需要一个分配策略”，而不是“我必须依赖某个具体实现”。
这和很多商业引擎里的思路一致：
- 容器依赖 allocator 接口
- 上层根据数据生命周期决定用哪种分配器
- 调试阶段可以额外套 tracking / proxy 层
## 当前阶段最值得补的方向
如果继续把这个模块做实，最值得优先补的通常是：
1. 给 `LinearAllocator` 和 `PoolAllocator` 明确补完 `Reallocate` / 回收语义，或者在 API 层彻底禁掉不支持的操作。
2. 修正 `ProxyAllocator` 的统计口径。
3. 让 `MemoryManager` 的泄漏与报表接口真正产出结构化结果。
4. 为不同分配器补充更严格的越界、重复释放和对齐校验。
## 相关 API
- [Memory](../../XCEngine/Memory/Memory.md)
- [IAllocator](../../XCEngine/Memory/Allocator/Allocator.md)
- [LinearAllocator](../../XCEngine/Memory/LinearAllocator/LinearAllocator.md)
- [PoolAllocator](../../XCEngine/Memory/PoolAllocator/PoolAllocator.md)
- [ProxyAllocator](../../XCEngine/Memory/ProxyAllocator/ProxyAllocator.md)
- [MemoryManager](../../XCEngine/Memory/MemoryManager/MemoryManager.md)

4
docs/api/_meta/rebuild-status.md
View File

@@ -1,12 +1,12 @@
# API 文档重构状态
**生成时间**: `2026-03-26 17:39:11`
**生成时间**: `2026-03-26 18:01:19`
**来源**: `docs/api/_tools/audit_api_docs.py`
## 摘要
- Markdown 页面数（全部）: `2443`
- Markdown 页面数（全部）: `2444`
- Markdown 页面数（canonical）: `2436`
- Public headers 数: `185`
- 有效头文件引用数（全部）: `185`