docs: rebuild Memory API content
This commit is contained in:
@@ -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)
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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)
|
||||
|
||||
Reference in New Issue
Block a user