XCEngine/docs/api/XCEngine/Memory/Memory.md

# Memory

**命名空间**: `XCEngine::Memory`

**类型**: `module`

**描述**: 提供分配器抽象、线性分配器、固定块池分配器、统计代理分配器以及全局内存工厂入口。

## 概述

`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`，分配器抽象接口 `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) - 解释各分配器适合什么场景、当前实现做到哪一步，以及与商业引擎常见内存策略的关系。

## 相关文档

- [上级目录](../XCEngine.md)
- [API 总索引](../../main.md)