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

# PoolAllocator

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

**类型**: `class`

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

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

## 概述

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

## 公共方法

| 方法 | 描述 |
|------|------|
| [`PoolAllocator`](constructor.md) | 构造内存池分配器 |
| [`~PoolAllocator`](~pool-allocator.md) | 析构函数，释放整个内存池 |
| [`Allocate`](allocate.md) | 分配一个内存块 |
| [`Free`](free.md) | 释放内存块回空闲链表 |
| [`Reallocate`](reallocate.md) | 不支持（始终返回 nullptr） |
| [`Contains`](contains.md) | 检查指针是否属于此池 |
| [`GetBlockSize`](get-block-size.md) | 获取块大小 |
| [`GetFreeBlockCount`](get-free-block-count.md) | 获取空闲块数量 |
| [`GetTotalBlockCount`](get-total-block-count.md) | 获取总块数 |
| [`GetName`](get-name.md) | 获取分配器名称 |
| [`GetTotalAllocated`](get-total-allocated.md) | 获取当前已分配内存 |
| [`GetTotalFreed`](get-total-freed.md) | 获取当前空闲内存 |
| [`GetPeakAllocated`](get-peak-allocated.md) | 获取峰值分配内存 |
| [`GetAllocationCount`](get-allocation-count.md) | 获取当前分配块数量 |

## 构造函数

```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) - 分配器接口