From 98c764bab94179de94a3bdc48456784a4684b4a5 Mon Sep 17 00:00:00 2001 From: ssdfasd <2156608475@qq.com> Date: Thu, 19 Mar 2026 00:48:44 +0800 Subject: [PATCH] docs: Fix memory module documentation discrepancies - Add missing PoolAllocator class overview with methods table - Add missing LinearAllocator class overview with methods table - Add missing ProxyAllocator class overview with methods table - Fix PoolAllocator::Allocate example code and comments - Clarify ProxyAllocator::Free totalFreed calculation behavior - Fix CreateLinearAllocator complexity from O(size) to O(1) - Add note about Reallocate thread safety in ProxyAllocator --- .../linear-allocator/linear-allocator.md | 52 ++++++++++++++++++- .../memory/manager/create-linear-allocator.md | 2 +- .../memory/manager/create-pool-allocator.md | 2 +- docs/api/memory/pool-allocator/allocate.md | 9 ++-- .../memory/pool-allocator/pool-allocator.md | 45 +++++++++++++++- docs/api/memory/proxy-allocator/free.md | 4 +- .../memory/proxy-allocator/proxy-allocator.md | 40 +++++++++++++- docs/api/memory/proxy-allocator/reallocate.md | 2 +- 8 files changed, 142 insertions(+), 14 deletions(-) diff --git a/docs/api/memory/linear-allocator/linear-allocator.md b/docs/api/memory/linear-allocator/linear-allocator.md index 3e8c376b..5b93b6cc 100644 --- a/docs/api/memory/linear-allocator/linear-allocator.md +++ b/docs/api/memory/linear-allocator/linear-allocator.md @@ -1,7 +1,52 @@ -# LinearAllocator::LinearAllocator +# LinearAllocator + +**命名空间**: `XCEngine::Memory` + +**类型**: `class` + +**描述**: 线性分配器，适合帧分配和临时对象。 + +## 概述 + +`LinearAllocator` 是一种顺序分配器，预分配一个大缓冲区，每次分配从缓冲区起始位置顺序分配，偏移量递增。它不适合需要释放任意块的场景，但分配和清除非常高效，常用于帧分配器。 + +## 公共方法 + +### 生命周期 + +| 方法 | 描述 | +|------|------| +| `LinearAllocator` | 构造线性分配器 | +| `~LinearAllocator` | 析构函数，释放底层缓冲区 | + +### 内存操作 + +| 方法 | 描述 | +|------|------| +| `Allocate` | 顺序分配内存 | +| `Free` | 无效果（不支持） | +| `Reallocate` | 不支持（始终返回 nullptr） | +| `Clear` | 清空所有分配 | + +### 标记和回滚 + +| 方法 | 描述 | +|------|------| +| `GetMarker` | 获取当前位置标记 | +| `SetMarker` | 回滚到指定标记位置 | + +### 查询方法 + +| 方法 | 描述 | +|------|------| +| `GetUsedSize` | 获取已使用字节数 | +| `GetCapacity` | 获取总容量 | + +## 构造函数 ```cpp explicit LinearAllocator(size_t size, IAllocator* parent = nullptr); +~LinearAllocator() override; ``` 构造一个线性分配器，预分配指定大小的缓冲区。如果提供了 `parent` 分配器，则使用它分配底层缓冲区；否则使用系统默认分配（`_aligned_malloc`，8 字节对齐）。 @@ -14,6 +59,8 @@ explicit LinearAllocator(size_t size, IAllocator* parent = nullptr); **复杂度：** O(n)，需要分配 `size` 大小的缓冲区 +**注意：** `Free` 和 `Reallocate` 方法无实际效果。`Free` 是空操作，`Reallocate` 始终返回 `nullptr`。 + **示例：** ```cpp @@ -32,4 +79,5 @@ void* ptr = allocator1.Allocate(256); ## 相关文档 -- [LinearAllocator 总览](linear-allocator.md) - 返回类总览 +- [Memory 模块总览](../memory.md) - 返回模块总览 +- [IAllocator](../allocator/allocator.md) - 分配器接口 diff --git a/docs/api/memory/manager/create-linear-allocator.md b/docs/api/memory/manager/create-linear-allocator.md index 2e6d7e3e..c0475b6b 100644 --- a/docs/api/memory/manager/create-linear-allocator.md +++ b/docs/api/memory/manager/create-linear-allocator.md @@ -11,7 +11,7 @@ std::unique_ptr CreateLinearAllocator(size_t size); **返回：** LinearAllocator 的 unique_ptr -**复杂度：** O(size) +**复杂度：** O(1) **示例：** diff --git a/docs/api/memory/manager/create-pool-allocator.md b/docs/api/memory/manager/create-pool-allocator.md index 752a94e8..4f096d58 100644 --- a/docs/api/memory/manager/create-pool-allocator.md +++ b/docs/api/memory/manager/create-pool-allocator.md @@ -12,7 +12,7 @@ std::unique_ptr CreatePoolAllocator(size_t blockSize, size_t coun **返回：** PoolAllocator 的 unique_ptr -**复杂度：** O(blockSize * count) +**复杂度：** O(blockSize * count)（需要预分配所有块） **示例：** diff --git a/docs/api/memory/pool-allocator/allocate.md b/docs/api/memory/pool-allocator/allocate.md index 35f17f8f..ce71f8d5 100644 --- a/docs/api/memory/pool-allocator/allocate.md +++ b/docs/api/memory/pool-allocator/allocate.md @@ -19,11 +19,12 @@ void* Allocate(size_t size, size_t alignment = 0) override; ```cpp #include -PoolAllocator pool(sizeof(int) * 100, 50, alignof(int)); +// 创建能容纳 1000 个整数的内存池 +PoolAllocator pool(sizeof(int), 1000, alignof(int)); -// 分配（忽略 size 参数） -void* block1 = pool.Allocate(1); // 分配 1 字节 -void* block2 = pool.Allocate(10000); // 也分配一块 +// 分配（忽略 size 参数，只分配固定大小的块） +void* block1 = pool.Allocate(1); // 分配一块（实际大小为 sizeof(int)） +void* block2 = pool.Allocate(10000); // 也分配一块（实际大小为 sizeof(int)） if (block1 && block2) { // 使用分配的内存块 diff --git a/docs/api/memory/pool-allocator/pool-allocator.md b/docs/api/memory/pool-allocator/pool-allocator.md index 0c18964b..31da1ddf 100644 --- a/docs/api/memory/pool-allocator/pool-allocator.md +++ b/docs/api/memory/pool-allocator/pool-allocator.md @@ -1,4 +1,42 @@ -# PoolAllocator::PoolAllocator / ~PoolAllocator +# 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); @@ -16,6 +54,8 @@ PoolAllocator(size_t blockSize, size_t poolSize, size_t alignment = 8); **复杂度：** O(n)，需要预分配所有块 +**注意：** `Reallocate` 方法始终返回 `nullptr`，此分配器不支持重新分配。 + **示例：** ```cpp @@ -41,4 +81,5 @@ pool.Free(block); ## 相关文档 -- [PoolAllocator 总览](pool-allocator.md) - 返回类总览 +- [Memory 模块总览](../memory.md) - 返回模块总览 +- [IAllocator](../allocator/allocator.md) - 分配器接口 diff --git a/docs/api/memory/proxy-allocator/free.md b/docs/api/memory/proxy-allocator/free.md index bb88289b..c4ebd3b8 100644 --- a/docs/api/memory/proxy-allocator/free.md +++ b/docs/api/memory/proxy-allocator/free.md @@ -4,7 +4,9 @@ void Free(void* ptr) override; ``` -释放内存并记录统计。调用转发到底层分配器，同时更新统计信息：递增 `totalFreed`（累加当前分配计数），并递减 `allocationCount`。由于 ProxyAllocator 不记录单独释放的字节数，`totalFreed` 累加的是 `allocationCount` 而非实际字节大小。 +释放内存并记录统计。调用转发到底层分配器，同时更新统计信息：递增 `totalFreed`（累加当前 `allocationCount`），并递减 `allocationCount`。 + +**注意：** `totalFreed` 累加的是每次释放时的 `allocationCount`（分配计数）而非实际字节大小。这是一个简化的实现，用于追踪释放操作次数。 **参数：** - `ptr` - 指向要释放的内存块 diff --git a/docs/api/memory/proxy-allocator/proxy-allocator.md b/docs/api/memory/proxy-allocator/proxy-allocator.md index fe8875b8..d993edb4 100644 --- a/docs/api/memory/proxy-allocator/proxy-allocator.md +++ b/docs/api/memory/proxy-allocator/proxy-allocator.md @@ -1,4 +1,38 @@ -# ProxyAllocator::ProxyAllocator +# ProxyAllocator + +**命名空间**: `XCEngine::Memory` + +**类型**: `class` + +**描述**: 代理分配器，用于统计和跟踪底层分配器的分配情况。 + +## 概述 + +`ProxyAllocator` 包装一个底层分配器，转发所有分配请求，同时记录详细的统计信息。它线程安全（使用互斥锁保护统计数据），适合需要监控内存使用的场景。 + +## 公共方法 + +### 生命周期 + +| 方法 | 描述 | +|------|------| +| `ProxyAllocator` | 构造代理分配器 | + +### 内存操作 + +| 方法 | 描述 | +|------|------| +| `Allocate` | 分配内存并记录统计 | +| `Free` | 释放内存并记录统计 | +| `Reallocate` | 转发到底层分配器 | + +### 统计查询 + +| 方法 | 描述 | +|------|------| +| `GetStats` | 获取详细统计信息 | + +## 构造函数 ```cpp ProxyAllocator(IAllocator* underlying, const char* name); @@ -33,4 +67,6 @@ proxy.Free(ptr); ## 相关文档 -- [ProxyAllocator 总览](proxy-allocator.md) - 返回类总览 +- [Memory 模块总览](../memory.md) - 返回模块总览 +- [IAllocator](../allocator/allocator.md) - 分配器接口 +- [MemoryManager](../manager/manager.md) - 内存管理器 diff --git a/docs/api/memory/proxy-allocator/reallocate.md b/docs/api/memory/proxy-allocator/reallocate.md index 30a2b340..6d1f0e8c 100644 --- a/docs/api/memory/proxy-allocator/reallocate.md +++ b/docs/api/memory/proxy-allocator/reallocate.md @@ -4,7 +4,7 @@ void* Reallocate(void* ptr, size_t newSize) override; ``` -重新分配内存。调用直接转发到底层分配器，不记录任何统计信息（简化实现）。此方法仅将调用转发给底层分配器。 +重新分配内存。调用转发到底层分配器，不记录额外统计信息（底层分配器的返回值直接返回）。此方法线程安全，内部使用互斥锁保护。 **参数：** - `ptr` - 现有内存块指针