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

# ProxyAllocator

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

**类型**: `class`

**头文件**: `XCEngine/Memory/ProxyAllocator.h`

**描述**: 在已有分配器外面包一层统计逻辑的代理分配器。

## 概述

`ProxyAllocator` 不直接拥有原始堆，而是把所有内存操作转发给底层分配器，并在外层记录统计信息。这种设计适合：

- 调试某个子系统的内存使用
- 给同一个底层分配器增加具名统计视图
- 在不改底层分配器实现的前提下，追加追踪逻辑

## 所有权

- [Constructor](Constructor.md) 接收一个底层 `IAllocator*` 和一个名称。
- 当前 `ProxyAllocator` 不拥有底层分配器，不会在销毁时释放它。
- 当前实现既不校验底层分配器是否为空，也不复制名称字符串。
- `MemoryManager::CreateProxyAllocator` 当前总是包装系统分配器，而不是任意自定义底层分配器。

## 当前实现限制

- [Free](Free.md) 会把 `totalFreed` 增加为“当前 allocation count”，而不是被释放块的真实大小，因此释放字节统计当前并不准确。
- [Reallocate](Reallocate.md) 只转发调用，不更新统计信息。
- 如果底层分配器失效或被提前销毁，后续所有代理操作都可能触发未定义行为。
- `GetStats()` 返回内部结构体引用，当前没有为只读访问额外加锁。
- `memoryOverhead` 字段存在，但当前没有被维护。

## 线程语义

- `Allocate`、`Free` 和 `Reallocate` 当前在内部使用 `Threading::Mutex` 保护统计更新。
- `GetStats()` 是无锁只读返回；更适合在无并发修改或调试快照场景下读取。

## 公开方法

| 方法 | 说明 |
|------|------|
| [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)
- [IAllocator](../Allocator/Allocator.md)
- [MemoryManager](../MemoryManager/MemoryManager.md)
- [Allocator Selection And Current Limits](../../../_guides/Memory/Allocator-Selection-And-Current-Limits.md)