refactor: reorganize docs into plan/ and add skills/
This commit is contained in:
74
docs/api/memory/memory-allocator.md
Normal file
74
docs/api/memory/memory-allocator.md
Normal file
@@ -0,0 +1,74 @@
|
||||
# IAllocator
|
||||
|
||||
**命名空间**: `XCEngine::Memory`
|
||||
|
||||
**类型**: `class` (abstract interface)
|
||||
|
||||
**描述**: 内存分配器抽象接口，定义标准分配协议。
|
||||
|
||||
## 概述
|
||||
|
||||
`IAllocator` 是 XCEngine 内存管理系统的核心抽象接口。它定义了分配、释放和重新分配内存的标准方法，以及内存统计接口。所有专用分配器（LinearAllocator、PoolAllocator、ProxyAllocator）都实现此接口。
|
||||
|
||||
## 公共方法
|
||||
|
||||
### 内存操作
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `virtual void* Allocate(size_t size, size_t alignment = 0)` | 分配内存 |
|
||||
| `virtual void Free(void* ptr)` | 释放内存 |
|
||||
| `virtual void* Reallocate(void* ptr, size_t newSize)` | 重新分配内存 |
|
||||
|
||||
### 统计信息
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `virtual size_t GetTotalAllocated() const` | 获取已分配总字节数 |
|
||||
| `virtual size_t GetTotalFreed() const` | 获取已释放总字节数 |
|
||||
| `virtual size_t GetPeakAllocated() const` | 获取峰值分配字节数 |
|
||||
| `virtual size_t GetAllocationCount() const` | 获取分配次数 |
|
||||
|
||||
### 元信息
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `virtual const char* GetName() const = 0` | 获取分配器名称 |
|
||||
|
||||
## 使用示例
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Memory/IAllocator.h>
|
||||
|
||||
class MyAllocator : public IAllocator {
|
||||
public:
|
||||
void* Allocate(size_t size, size_t alignment = 0) override {
|
||||
// 实现分配逻辑
|
||||
return ::operator new(size);
|
||||
}
|
||||
|
||||
void Free(void* ptr) override {
|
||||
// 实现释放逻辑
|
||||
::operator delete(ptr);
|
||||
}
|
||||
|
||||
void* Reallocate(void* ptr, size_t newSize) override {
|
||||
void* newPtr = Allocate(newSize);
|
||||
// 拷贝旧数据...
|
||||
Free(ptr);
|
||||
return newPtr;
|
||||
}
|
||||
|
||||
size_t GetTotalAllocated() const override { return m_allocated; }
|
||||
size_t GetTotalFreed() const override { return m_freed; }
|
||||
size_t GetPeakAllocated() const override { return m_peak; }
|
||||
size_t GetAllocationCount() const override { return m_count; }
|
||||
const char* GetName() const override { return "MyAllocator"; }
|
||||
};
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [MemoryManager](./memory-manager.md) - 内存管理器
|
||||
- [LinearAllocator](./memory-linear-allocator.md) - 线性分配器
|
||||
- [PoolAllocator](./memory-pool-allocator.md) - 内存池分配器
|
||||
82
docs/api/memory/memory-linear-allocator.md
Normal file
82
docs/api/memory/memory-linear-allocator.md
Normal file
@@ -0,0 +1,82 @@
|
||||
# LinearAllocator
|
||||
|
||||
**命名空间**: `XCEngine::Memory`
|
||||
|
||||
**类型**: `class`
|
||||
|
||||
**描述**: 线性分配器，提供顺序分配和一次性释放的内存管理，适用于帧分配和临时对象。
|
||||
|
||||
## 概述
|
||||
|
||||
`LinearAllocator` 以顺序方式分配内存，每次分配都紧接在上一次分配之后。它不支持单个内存块的释放，只能通过 `Clear()` 一次性清空所有内存。这使得它非常适合作为帧分配器，每帧开始时 Clear 即可。
|
||||
|
||||
## 公共方法
|
||||
|
||||
### 构造/析构
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `explicit LinearAllocator(size_t size, IAllocator* parent = nullptr)` | 构造函数，预分配指定大小的缓冲区 |
|
||||
| `~LinearAllocator()` | 析构函数，释放所有内存 |
|
||||
|
||||
### IAllocator 实现
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `void* Allocate(size_t size, size_t alignment = 8) override` | 顺序分配内存 |
|
||||
| `void Free(void* ptr) override` | 空操作（不支持单个释放） |
|
||||
| `void* Reallocate(void* ptr, size_t newSize) override` | 重新分配（总是分配新内存） |
|
||||
|
||||
### 线性操作
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `void Clear()` | 清空所有分配，下一次分配从头开始 |
|
||||
| `void* GetMarker() const` | 获取当前分配位置标记 |
|
||||
| `void SetMarker(void* marker)` | 恢复到指定标记位置 |
|
||||
|
||||
### 状态查询
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `size_t GetUsedSize() const` | 获取已使用的字节数 |
|
||||
| `size_t GetCapacity() const` | 获取总容量 |
|
||||
|
||||
### 统计
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `size_t GetTotalAllocated() const` | 返回已使用字节数 |
|
||||
| `size_t GetTotalFreed() const` | 返回 0 |
|
||||
| `size_t GetPeakAllocated() const` | 返回容量大小 |
|
||||
| `size_t GetAllocationCount() const` | 返回 0 |
|
||||
|
||||
## 使用示例
|
||||
|
||||
```cpp
|
||||
// 创建 1MB 的线性分配器
|
||||
auto allocator = std::make_unique<LinearAllocator>(1024 * 1024);
|
||||
|
||||
// 分配临时内存
|
||||
void* ptr1 = allocator->Allocate(256);
|
||||
void* ptr2 = allocator->Allocate(512);
|
||||
void* ptr3 = allocator->Allocate(128);
|
||||
|
||||
// 保存标记
|
||||
void* marker = allocator->GetMarker();
|
||||
|
||||
// 分配一些临时内存
|
||||
void* temp = allocator->Allocate(64);
|
||||
|
||||
// 恢复到标记位置（释放 temp）
|
||||
allocator->SetMarker(marker);
|
||||
|
||||
// 每帧结束时清空
|
||||
allocator->Clear();
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [IAllocator](./memory-allocator.md) - 分配器接口
|
||||
- [PoolAllocator](./memory-pool-allocator.md) - 内存池分配器
|
||||
- [ProxyAllocator](./memory-proxy-allocator.md) - 代理分配器
|
||||
99
docs/api/memory/memory-manager.md
Normal file
99
docs/api/memory/memory-manager.md
Normal file
@@ -0,0 +1,99 @@
|
||||
# MemoryManager
|
||||
|
||||
**命名空间**: `XCEngine::Memory`
|
||||
|
||||
**类型**: `class` (singleton)
|
||||
|
||||
**描述**: 全局内存管理器单例，提供系统分配器和各种专用分配器的创建。
|
||||
|
||||
## 概述
|
||||
|
||||
`MemoryManager` 是 XCEngine 内存管理系统的核心单例。它负责维护系统分配器，提供分配器工厂方法，并支持内存泄漏检测和报告。
|
||||
|
||||
## 单例访问
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `static MemoryManager& Get()` | 获取单例实例 |
|
||||
|
||||
## 公共方法
|
||||
|
||||
### 生命周期
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `void Initialize()` | 初始化内存管理器 |
|
||||
| `void Shutdown()` | 关闭内存管理器 |
|
||||
|
||||
### 系统分配器
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `IAllocator* GetSystemAllocator()` | 获取系统默认分配器 |
|
||||
|
||||
### 分配器创建
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `std::unique_ptr<LinearAllocator> CreateLinearAllocator(size_t size)` | 创建线性分配器 |
|
||||
| `std::unique_ptr<PoolAllocator> CreatePoolAllocator(size_t blockSize, size_t count)` | 创建内存池分配器 |
|
||||
| `std::unique_ptr<ProxyAllocator> CreateProxyAllocator(const char* name)` | 创建代理分配器 |
|
||||
|
||||
### 内存管理
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `void SetTrackAllocations(bool track)` | 设置是否跟踪分配 |
|
||||
| `void DumpMemoryLeaks()` | 输出内存泄漏报告 |
|
||||
| `void GenerateMemoryReport()` | 生成内存使用报告 |
|
||||
|
||||
## 宏定义
|
||||
|
||||
### XE_ALLOC
|
||||
|
||||
```cpp
|
||||
#define XE_ALLOC(allocator, size, ...) allocator->Allocate(size, ##__VA_ARGS__)
|
||||
```
|
||||
|
||||
内存分配宏。
|
||||
|
||||
### XE_FREE
|
||||
|
||||
```cpp
|
||||
#define XE_FREE(allocator, ptr) allocator->Free(ptr)
|
||||
```
|
||||
|
||||
内存释放宏。
|
||||
|
||||
## 使用示例
|
||||
|
||||
```cpp
|
||||
// 初始化
|
||||
MemoryManager::Get().Initialize();
|
||||
|
||||
// 获取系统分配器
|
||||
IAllocator* sysAlloc = MemoryManager::Get().GetSystemAllocator();
|
||||
|
||||
// 创建专用分配器
|
||||
auto linearAlloc = MemoryManager::Get().CreateLinearAllocator(1024 * 1024);
|
||||
auto poolAlloc = MemoryManager::Get().CreatePoolAllocator(sizeof(MyObject), 1000);
|
||||
auto proxyAlloc = MemoryManager::Get().CreateProxyAllocator("GameFrame");
|
||||
|
||||
// 使用宏分配
|
||||
void* ptr = XE_ALLOC(proxyAlloc, 256);
|
||||
XE_FREE(proxyAlloc, ptr);
|
||||
|
||||
// 跟踪内存
|
||||
MemoryManager::Get().SetTrackAllocations(true);
|
||||
MemoryManager::Get().GenerateMemoryReport();
|
||||
|
||||
// 关闭
|
||||
MemoryManager::Get().Shutdown();
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [IAllocator](./memory-allocator.md) - 分配器接口
|
||||
- [LinearAllocator](./memory-linear-allocator.md) - 线性分配器
|
||||
- [PoolAllocator](./memory-pool-allocator.md) - 内存池分配器
|
||||
- [ProxyAllocator](./memory-proxy-allocator.md) - 代理分配器
|
||||
72
docs/api/memory/memory-overview.md
Normal file
72
docs/api/memory/memory-overview.md
Normal file
@@ -0,0 +1,72 @@
|
||||
# Memory 模块概览
|
||||
|
||||
**命名空间**: `XCEngine::Memory`
|
||||
|
||||
**类型**: `module`
|
||||
|
||||
**描述**: XCEngine 的内存管理模块，提供多种内存分配器实现。
|
||||
|
||||
## 概述
|
||||
|
||||
Memory 模块提供了一套完整的内存管理解决方案，包括基础分配器接口和各种专用分配器实现。
|
||||
|
||||
## 模块内容
|
||||
|
||||
### 分配器接口
|
||||
|
||||
| 组件 | 文件 | 描述 |
|
||||
|------|------|------|
|
||||
| [IAllocator](./memory-allocator.md) | `Allocator.h` | 内存分配器抽象接口 |
|
||||
|
||||
### 分配器实现
|
||||
|
||||
| 组件 | 文件 | 描述 |
|
||||
|------|------|------|
|
||||
| [LinearAllocator](./memory-linear-allocator.md) | `LinearAllocator.h` | 线性分配器，适合帧分配 |
|
||||
| [PoolAllocator](./memory-pool-allocator.md) | `PoolAllocator.h` | 内存池分配器，适合固定大小对象 |
|
||||
| [ProxyAllocator](./memory-proxy-allocator.md) | `ProxyAllocator.h` | 代理分配器，用于统计和跟踪 |
|
||||
|
||||
### 管理器
|
||||
|
||||
| 组件 | 文件 | 描述 |
|
||||
|------|------|------|
|
||||
| [MemoryManager](./memory-manager.md) | `MemoryManager.h` | 全局内存管理器 |
|
||||
|
||||
## 分配器类型对比
|
||||
|
||||
| 分配器 | 适用场景 | 特点 |
|
||||
|--------|----------|------|
|
||||
| `IAllocator` | 基类接口 | 定义标准分配协议 |
|
||||
| `LinearAllocator` | 帧分配、临时对象 | 快速分配，只支持按顺序释放 |
|
||||
| `PoolAllocator` | 同尺寸对象池 | 高效分配，消除碎片 |
|
||||
| `ProxyAllocator` | 调试和统计 | 记录分配信息，跟踪内存使用 |
|
||||
|
||||
## 宏定义
|
||||
|
||||
| 宏 | 描述 |
|
||||
|----|------|
|
||||
| `XE_ALLOC(allocator, size, ...)` | 内存分配宏 |
|
||||
| `XE_FREE(allocator, ptr)` | 内存释放宏 |
|
||||
|
||||
## 使用示例
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Memory/MemoryManager.h>
|
||||
|
||||
// 获取系统分配器
|
||||
IAllocator* sysAlloc = MemoryManager::Get().GetSystemAllocator();
|
||||
|
||||
// 创建线性分配器
|
||||
auto linearAlloc = MemoryManager::Get().CreateLinearAllocator(1024 * 1024);
|
||||
|
||||
// 使用代理分配器跟踪统计
|
||||
auto proxyAlloc = MemoryManager::Get().CreateProxyAllocator("FrameData");
|
||||
|
||||
// 分配内存
|
||||
void* ptr = XE_ALLOC(linearAlloc, 1024);
|
||||
XE_FREE(linearAlloc, ptr);
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [Containers 模块](../containers/container-overview.md) - 使用分配器的容器
|
||||
75
docs/api/memory/memory-pool-allocator.md
Normal file
75
docs/api/memory/memory-pool-allocator.md
Normal file
@@ -0,0 +1,75 @@
|
||||
# PoolAllocator
|
||||
|
||||
**命名空间**: `XCEngine::Memory`
|
||||
|
||||
**类型**: `class`
|
||||
|
||||
**描述**: 内存池分配器，为固定大小的对象提供高效分配，消除内存碎片。
|
||||
|
||||
## 概述
|
||||
|
||||
`PoolAllocator` 预分配一大块内存，并将其划分为等大小的内存块。它维护一个空闲块链表，分配时从链表中取出一块，释放时归还到链表。这使得分配和释放都是 O(1) 时间复杂度，非常适合需要频繁分配/释放同尺寸对象的场景（如对象池）。
|
||||
|
||||
## 公共方法
|
||||
|
||||
### 构造/析构
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `PoolAllocator(size_t blockSize, size_t poolSize, size_t alignment = 8)` | 构造函数 |
|
||||
| `~PoolAllocator()` | 析构函数 |
|
||||
|
||||
### IAllocator 实现
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `void* Allocate(size_t size, size_t alignment = 0) override` | 分配一个内存块（忽略 size 参数） |
|
||||
| `void Free(void* ptr) override` | 释放内存块 |
|
||||
| `void* Reallocate(void* ptr, size_t newSize) override` | 不支持，返回 nullptr |
|
||||
|
||||
### 内存块管理
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `bool Contains(void* ptr) const` | 检查指针是否属于此池 |
|
||||
| `size_t GetBlockSize() const` | 获取内存块大小 |
|
||||
| `size_t GetFreeBlockCount() const` | 获取空闲块数量 |
|
||||
| `size_t GetTotalBlockCount() const` | 获取总块数 |
|
||||
|
||||
### 统计
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `size_t GetTotalAllocated() const` | 已分配的字节数 |
|
||||
| `size_t GetTotalFreed() const` | 空闲块占用的字节数 |
|
||||
| `size_t GetPeakAllocated() const` | 总块数乘以块大小 |
|
||||
| `size_t GetAllocationCount() const` | 当前已分配块数 |
|
||||
|
||||
## 使用示例
|
||||
|
||||
```cpp
|
||||
// 创建一个能分配 100 个 64 字节块的内存池
|
||||
PoolAllocator pool(sizeof(MyObject), 100, alignof(MyObject));
|
||||
|
||||
// 分配（O(1)）
|
||||
void* block = pool.Allocate();
|
||||
// 或者使用 Allocate(size) 但忽略 size
|
||||
void* block2 = pool.Allocate(sizeof(MyObject));
|
||||
|
||||
// 检查空闲块
|
||||
printf("Free blocks: %zu\n", pool.GetFreeBlockCount());
|
||||
|
||||
// 释放（O(1)）
|
||||
pool.Free(block2);
|
||||
|
||||
// 检查指针是否属于此池
|
||||
if (pool.Contains(block)) {
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [IAllocator](./memory-allocator.md) - 分配器接口
|
||||
- [LinearAllocator](./memory-linear-allocator.md) - 线性分配器
|
||||
- [ProxyAllocator](./memory-proxy-allocator.md) - 代理分配器
|
||||
71
docs/api/memory/memory-proxy-allocator.md
Normal file
71
docs/api/memory/memory-proxy-allocator.md
Normal file
@@ -0,0 +1,71 @@
|
||||
# ProxyAllocator
|
||||
|
||||
**命名空间**: `XCEngine::Memory`
|
||||
|
||||
**类型**: `class`
|
||||
|
||||
**描述**: 代理分配器，包装另一个分配器并记录分配统计信息，用于内存跟踪和调试。
|
||||
|
||||
## 概述
|
||||
|
||||
`ProxyAllocator` 是对另一个分配器的包装，它将所有分配请求转发给底层分配器，同时记录分配统计信息。这对于分析内存使用模式和调试内存问题非常有用。
|
||||
|
||||
## 公共方法
|
||||
|
||||
### 构造
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `ProxyAllocator(IAllocator* underlying, const char* name)` | 构造函数，指定底层分配器和名称 |
|
||||
|
||||
### IAllocator 实现
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `void* Allocate(size_t size, size_t alignment = 0) override` | 分配并统计 |
|
||||
| `void Free(void* ptr) override` | 释放并统计 |
|
||||
| `void* Reallocate(void* ptr, size_t newSize) override` | 重新分配并统计 |
|
||||
|
||||
### 统计
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `size_t GetTotalAllocated() const override` | 总分配字节数 |
|
||||
| `size_t GetTotalFreed() const override` | 总释放字节数 |
|
||||
| `size_t GetPeakAllocated() const override` | 峰值分配字节数 |
|
||||
| `size_t GetAllocationCount() const override` | 分配次数 |
|
||||
| `const Stats& GetStats() const` | 获取详细统计信息 |
|
||||
|
||||
## Stats 结构体
|
||||
|
||||
| 成员 | 类型 | 描述 |
|
||||
|------|------|------|
|
||||
| `totalAllocated` | `size_t` | 累计分配字节数 |
|
||||
| `totalFreed` | `size_t` | 累计释放字节数 |
|
||||
| `peakAllocated` | `size_t` | 峰值分配字节数 |
|
||||
| `allocationCount` | `size_t` | 分配次数 |
|
||||
| `memoryOverhead` | `size_t` | 额外开销（字节） |
|
||||
|
||||
## 使用示例
|
||||
|
||||
```cpp
|
||||
// 包装系统分配器
|
||||
IAllocator* sysAlloc = MemoryManager::Get().GetSystemAllocator();
|
||||
ProxyAllocator proxy(sysAlloc, "FrameData");
|
||||
|
||||
// 使用代理分配器
|
||||
void* ptr = proxy.Allocate(1024);
|
||||
|
||||
// 获取统计
|
||||
const ProxyAllocator::Stats& stats = proxy.GetStats();
|
||||
printf("Total allocated: %zu bytes\n", stats.totalAllocated);
|
||||
printf("Peak allocated: %zu bytes\n", stats.peakAllocated);
|
||||
printf("Allocation count: %zu\n", stats.allocationCount);
|
||||
printf("Current in use: %zu bytes\n",
|
||||
stats.totalAllocated - stats.totalFreed);
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [IAllocator](./memory-allocator.md) - 分配器接口
|
||||
- [MemoryManager](./memory-manager.md) - 内存管理器
|
||||
Reference in New Issue
Block a user