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

# PoolAllocator

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

**类型**: `class`

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

**描述**: 为固定尺寸对象提供 O(1) 弹出/归还的池分配器。

## 概述

`PoolAllocator` 预先申请一整块内存，然后把它切成固定尺寸的 block，通过空闲链表管理这些 block。它适合：

- 大量尺寸相同或尺寸上界稳定的小对象
- 频繁分配和释放、但不想承担通用堆分配碎片与额外元数据开销的场景

## 生命周期与所有权

- [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` 当前返回整个池的总容量，而不是历史峰值使用量。

## 线程语义

- 当前没有锁；需要外部同步。

## 公开方法

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