XCEngine/docs/api/memory/pool-allocator/pool-allocator.md

# PoolAllocator

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

**类型**: `class`

**描述**: 内存池分配器，预分配固定大小的内存块池。

## 概述

`PoolAllocator` 是一种高效固定块分配器，适合需要频繁分配和释放相同大小对象的场景，如对象池、粒子系统等。它预分配 `poolSize` 个大小为 `blockSize` 字节的内存块，通过空闲链表管理分配和回收。

## 公共方法

### 生命周期

| 方法 | 描述 |
|------|------|
| `PoolAllocator` | 构造内存池分配器 |
| `~PoolAllocator` | 析构函数，释放整个内存池 |

### 内存操作

| 方法 | 描述 |
|------|------|
| `Allocate` | 分配一个内存块 |
| `Free` | 释放内存块回空闲链表 |
| `Reallocate` | 不支持（始终返回 nullptr） |

### 查询方法

| 方法 | 描述 |
|------|------|
| `Contains` | 检查指针是否属于此池 |
| `GetBlockSize` | 获取块大小 |
| `GetFreeBlockCount` | 获取空闲块数量 |
| `GetTotalBlockCount` | 获取总块数 |

## 构造函数

```cpp
PoolAllocator(size_t blockSize, size_t poolSize, size_t alignment = 8);
~PoolAllocator() override;
```

构造内存池分配器，预分配 `poolSize` 个大小为 `blockSize` 字节的内存块。内存块按 `alignment` 对齐（默认 8 字节）。内部维护一个空闲块链表来管理分配。析构函数释放整个内存池。

**参数：**
- `blockSize` - 每个内存块的大小（字节）
- `poolSize` - 内存池中总块数
- `alignment` - 对齐要求，默认为 8

**返回：** 无

**复杂度：** O(n)，需要预分配所有块

**注意：** `Reallocate` 方法始终返回 `nullptr`，此分配器不支持重新分配。

**示例：**

```cpp
#include <XCEngine/Memory/PoolAllocator.h>

struct Particle {
    float x, y, z;
    float vx, vy, vz;
    float life;
};

// 创建一个能容纳 1000 个 Particle 的内存池，16 字节对齐
PoolAllocator pool(sizeof(Particle), 1000, alignof(Particle));

size_t blockSize = pool.GetBlockSize();   // sizeof(Particle)
size_t total = pool.GetTotalBlockCount(); // 1000
size_t free = pool.GetFreeBlockCount();   // 1000

// 分配和释放
void* block = pool.Allocate();
pool.Free(block);
```

## 相关文档

- [Memory 模块总览](../memory.md) - 返回模块总览
- [IAllocator](../allocator/allocator.md) - 分配器接口