docs: 重构 API 文档结构并修正源码准确性
- 重组文档目录结构: 每个模块的概述页移动到模块子目录 - 重命名 index.md 为 main.md - 修正所有模块文档中的错误: - math: FromEuler→FromEulerAngles, TransformDirection 包含缩放, Box 是 OBB, Color::ToRGBA 格式 - containers: 新增 operator==/!= 文档, 补充 std::hash DJB 算法细节 - core: 修复 types 链接错误 - debug: LogLevelToString 返回大写, timestamp 是秒, Profiler 空实现标注, Windows API vs ANSI - memory: 修复头文件路径, malloc vs operator new, 新增方法文档 - resources: 修复 Shader/Texture 链接错误 - threading: TaskSystem::Wait 空实现标注, ReadWriteLock 重入描述, LambdaTask 链接 - 验证: fix_links.py 确认 0 个断裂引用
This commit is contained in:
38
docs/api/memory/allocator/allocate.md
Normal file
38
docs/api/memory/allocator/allocate.md
Normal file
@@ -0,0 +1,38 @@
|
||||
# IAllocator::Allocate
|
||||
|
||||
```cpp
|
||||
virtual void* Allocate(size_t size, size_t alignment = 0) = 0;
|
||||
```
|
||||
|
||||
从分配器请求指定大小的内存块。如果 `alignment` 大于 0，则返回的地址将按该对齐值对齐。分配成功时返回有效指针，失败时返回 `nullptr` 或抛出异常（取决于具体实现）。
|
||||
|
||||
**参数：**
|
||||
- `size` - 请求的字节数
|
||||
- `alignment` - 内存对齐要求，默认为 0（表示使用实现默认对齐）
|
||||
|
||||
**返回：** 分配成功返回已分配内存块的指针，失败返回 `nullptr`
|
||||
|
||||
**复杂度：** O(1)（固定块分配器）或 O(n)（需要搜索合适大小的块）
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Memory/IAllocator.h>
|
||||
|
||||
class MyAllocator : public IAllocator {
|
||||
public:
|
||||
void* Allocate(size_t size, size_t alignment = 0) override {
|
||||
// 使用系统 new 分配
|
||||
return ::operator new(size);
|
||||
}
|
||||
// ... 其他方法实现
|
||||
};
|
||||
|
||||
MyAllocator alloc;
|
||||
void* ptr = alloc.Allocate(256); // 分配 256 字节
|
||||
void* aligned = alloc.Allocate(64, 16); // 分配 64 字节，16 字节对齐
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [IAllocator 总览](allocator.md) - 返回类总览
|
||||
@@ -16,45 +16,42 @@
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `virtual void* Allocate(size_t size, size_t alignment = 0)` | 分配内存 |
|
||||
| `virtual void Free(void* ptr)` | 释放内存 |
|
||||
| `virtual void* Reallocate(void* ptr, size_t newSize)` | 重新分配内存 |
|
||||
| `Allocate` | 分配内存 |
|
||||
| `Free` | 释放内存 |
|
||||
| `Reallocate` | 重新分配内存 |
|
||||
|
||||
### 统计信息
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `virtual size_t GetTotalAllocated() const` | 获取已分配总字节数 |
|
||||
| `virtual size_t GetTotalFreed() const` | 获取已释放总字节数 |
|
||||
| `virtual size_t GetPeakAllocated() const` | 获取峰值分配字节数 |
|
||||
| `virtual size_t GetAllocationCount() const` | 获取分配次数 |
|
||||
| `GetTotalAllocated` | 获取已分配总字节数 |
|
||||
| `GetTotalFreed` | 获取已释放总字节数 |
|
||||
| `GetPeakAllocated` | 获取峰值分配字节数 |
|
||||
| `GetAllocationCount` | 获取分配次数 |
|
||||
|
||||
### 元信息
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `virtual const char* GetName() const = 0` | 获取分配器名称 |
|
||||
| `GetName` | 获取分配器名称 |
|
||||
|
||||
## 使用示例
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Memory/IAllocator.h>
|
||||
#include <XCEngine/Memory/Allocator.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;
|
||||
}
|
||||
@@ -69,6 +66,7 @@ public:
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [MemoryManager](./memory-manager.md) - 内存管理器
|
||||
- [LinearAllocator](./memory-linear-allocator.md) - 线性分配器
|
||||
- [PoolAllocator](./memory-pool-allocator.md) - 内存池分配器
|
||||
- [Memory 模块总览](../memory.md) - 返回模块总览
|
||||
- [MemoryManager](../manager/manager.md) - 内存管理器
|
||||
- [LinearAllocator](../linear-allocator/linear-allocator.md) - 线性分配器
|
||||
- [PoolAllocator](../pool-allocator/pool-allocator.md) - 内存池分配器
|
||||
40
docs/api/memory/allocator/free.md
Normal file
40
docs/api/memory/allocator/free.md
Normal file
@@ -0,0 +1,40 @@
|
||||
# IAllocator::Free
|
||||
|
||||
```cpp
|
||||
virtual void Free(void* ptr) = 0;
|
||||
```
|
||||
|
||||
释放之前通过 `Allocate` 分配的内存块。如果 `ptr` 为 `nullptr`，则此调用无效果。部分分配器（如 LinearAllocator）可能不支持此操作。
|
||||
|
||||
**参数：**
|
||||
- `ptr` - 指向要释放内存块的指针
|
||||
|
||||
**返回：** 无
|
||||
|
||||
**复杂度：** O(1)（固定块释放）或 O(n)（需要搜索）
|
||||
|
||||
**示例：**
|
||||
|
||||
```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 {
|
||||
if (ptr) ::operator delete(ptr);
|
||||
}
|
||||
// ... 其他方法实现
|
||||
};
|
||||
|
||||
MyAllocator alloc;
|
||||
void* ptr = alloc.Allocate(512);
|
||||
alloc.Free(ptr); // 释放内存
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [IAllocator 总览](allocator.md) - 返回类总览
|
||||
52
docs/api/memory/allocator/get-allocation-count.md
Normal file
52
docs/api/memory/allocator/get-allocation-count.md
Normal file
@@ -0,0 +1,52 @@
|
||||
# IAllocator::GetAllocationCount
|
||||
|
||||
```cpp
|
||||
virtual size_t GetAllocationCount() const = 0;
|
||||
```
|
||||
|
||||
返回当前处于已分配状态（未释放）的内存块数量。此方法用于监控活跃分配的数量。
|
||||
|
||||
**参数：** 无
|
||||
|
||||
**返回：** 当前已分配块的数量
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Memory/IAllocator.h>
|
||||
|
||||
class MyAllocator : public IAllocator {
|
||||
size_t m_count = 0;
|
||||
public:
|
||||
void* Allocate(size_t size, size_t alignment = 0) override {
|
||||
++m_count;
|
||||
return ::operator new(size);
|
||||
}
|
||||
|
||||
void Free(void* ptr) override {
|
||||
if (ptr) {
|
||||
--m_count;
|
||||
::operator delete(ptr);
|
||||
}
|
||||
}
|
||||
|
||||
void* Reallocate(void* ptr, size_t newSize) override { /* ... */ }
|
||||
|
||||
size_t GetTotalAllocated() const override { return 0; }
|
||||
size_t GetTotalFreed() const override { return 0; }
|
||||
size_t GetPeakAllocated() const override { return 0; }
|
||||
size_t GetAllocationCount() const override { return m_count; }
|
||||
const char* GetName() const override { return "MyAllocator"; }
|
||||
};
|
||||
|
||||
MyAllocator alloc;
|
||||
alloc.Allocate(64);
|
||||
alloc.Allocate(128);
|
||||
size_t count = alloc.GetAllocationCount(); // 返回 2
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [IAllocator 总览](allocator.md) - 返回类总览
|
||||
40
docs/api/memory/allocator/get-name.md
Normal file
40
docs/api/memory/allocator/get-name.md
Normal file
@@ -0,0 +1,40 @@
|
||||
# IAllocator::GetName
|
||||
|
||||
```cpp
|
||||
virtual const char* GetName() const = 0;
|
||||
```
|
||||
|
||||
返回分配器的名称字符串。此方法用于调试、日志记录和内存报告，帮助识别不同分配器的使用情况。
|
||||
|
||||
**参数：** 无
|
||||
|
||||
**返回：** 分配器的名称字符串
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```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 { if (ptr) ::operator delete(ptr); }
|
||||
void* Reallocate(void* ptr, size_t newSize) override { /* ... */ }
|
||||
|
||||
size_t GetTotalAllocated() const override { return 0; }
|
||||
size_t GetTotalFreed() const override { return 0; }
|
||||
size_t GetPeakAllocated() const override { return 0; }
|
||||
size_t GetAllocationCount() const override { return 0; }
|
||||
const char* GetName() const override { return "MyAllocator"; }
|
||||
};
|
||||
|
||||
MyAllocator alloc;
|
||||
const char* name = alloc.GetName(); // 返回 "MyAllocator"
|
||||
printf("Allocator: %s\n", name);
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [IAllocator 总览](allocator.md) - 返回类总览
|
||||
57
docs/api/memory/allocator/get-peak-allocated.md
Normal file
57
docs/api/memory/allocator/get-peak-allocated.md
Normal file
@@ -0,0 +1,57 @@
|
||||
# IAllocator::GetPeakAllocated
|
||||
|
||||
```cpp
|
||||
virtual size_t GetPeakAllocated() const = 0;
|
||||
```
|
||||
|
||||
返回此分配器自创建以来达到的峰值分配字节数。该值在每次分配后更新，用于监控内存使用高峰。
|
||||
|
||||
**参数：** 无
|
||||
|
||||
**返回：** 峰值分配字节数
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Memory/IAllocator.h>
|
||||
|
||||
class MyAllocator : public IAllocator {
|
||||
size_t m_peak = 0;
|
||||
size_t m_current = 0;
|
||||
public:
|
||||
void* Allocate(size_t size, size_t alignment = 0) override {
|
||||
void* ptr = ::operator new(size);
|
||||
m_current += size;
|
||||
if (m_current > m_peak) m_peak = m_current;
|
||||
return ptr;
|
||||
}
|
||||
|
||||
void Free(void* ptr) override {
|
||||
if (ptr) {
|
||||
size_t size = 256; // 需要外部记录
|
||||
::operator delete(ptr);
|
||||
m_current -= size;
|
||||
}
|
||||
}
|
||||
|
||||
void* Reallocate(void* ptr, size_t newSize) override { /* ... */ }
|
||||
|
||||
size_t GetTotalAllocated() const override { return 0; }
|
||||
size_t GetTotalFreed() const override { return 0; }
|
||||
size_t GetPeakAllocated() const override { return m_peak; }
|
||||
size_t GetAllocationCount() const override { return 0; }
|
||||
const char* GetName() const override { return "MyAllocator"; }
|
||||
};
|
||||
|
||||
MyAllocator alloc;
|
||||
alloc.Allocate(100);
|
||||
size_t peak1 = alloc.GetPeakAllocated(); // 100
|
||||
alloc.Allocate(50);
|
||||
size_t peak2 = alloc.GetPeakAllocated(); // 150
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [IAllocator 总览](allocator.md) - 返回类总览
|
||||
50
docs/api/memory/allocator/get-total-allocated.md
Normal file
50
docs/api/memory/allocator/get-total-allocated.md
Normal file
@@ -0,0 +1,50 @@
|
||||
# IAllocator::GetTotalAllocated
|
||||
|
||||
```cpp
|
||||
virtual size_t GetTotalAllocated() const = 0;
|
||||
```
|
||||
|
||||
返回此分配器自创建以来累计分配的字节总数。这是一个只读查询操作，不会修改任何内部状态。
|
||||
|
||||
**参数：** 无
|
||||
|
||||
**返回：** 累计已分配的字节数
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Memory/IAllocator.h>
|
||||
|
||||
class MyAllocator : public IAllocator {
|
||||
size_t m_allocated = 0;
|
||||
public:
|
||||
void* Allocate(size_t size, size_t alignment = 0) override {
|
||||
void* ptr = ::operator new(size);
|
||||
m_allocated += size;
|
||||
return ptr;
|
||||
}
|
||||
|
||||
void Free(void* ptr) override {
|
||||
if (ptr) ::operator delete(ptr);
|
||||
}
|
||||
|
||||
void* Reallocate(void* ptr, size_t newSize) override { /* ... */ }
|
||||
|
||||
size_t GetTotalAllocated() const override { return m_allocated; }
|
||||
size_t GetTotalFreed() const override { return 0; }
|
||||
size_t GetPeakAllocated() const override { return m_allocated; }
|
||||
size_t GetAllocationCount() const override { return 0; }
|
||||
const char* GetName() const override { return "MyAllocator"; }
|
||||
};
|
||||
|
||||
MyAllocator alloc;
|
||||
alloc.Allocate(100);
|
||||
alloc.Allocate(200);
|
||||
size_t total = alloc.GetTotalAllocated(); // 返回 300
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [IAllocator 总览](allocator.md) - 返回类总览
|
||||
50
docs/api/memory/allocator/get-total-freed.md
Normal file
50
docs/api/memory/allocator/get-total-freed.md
Normal file
@@ -0,0 +1,50 @@
|
||||
# IAllocator::GetTotalFreed
|
||||
|
||||
```cpp
|
||||
virtual size_t GetTotalFreed() const = 0;
|
||||
```
|
||||
|
||||
返回此分配器自创建以来累计释放的字节总数。部分分配器（如 LinearAllocator）可能始终返回 0，因为它们不跟踪单个释放操作。
|
||||
|
||||
**参数：** 无
|
||||
|
||||
**返回：** 累计已释放的字节数
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Memory/IAllocator.h>
|
||||
|
||||
class MyAllocator : public IAllocator {
|
||||
size_t m_freed = 0;
|
||||
public:
|
||||
void* Allocate(size_t size, size_t alignment = 0) override { return ::operator new(size); }
|
||||
|
||||
void Free(void* ptr) override {
|
||||
if (ptr) {
|
||||
size_t size = 256; // 需要外部记录
|
||||
::operator delete(ptr);
|
||||
m_freed += size;
|
||||
}
|
||||
}
|
||||
|
||||
void* Reallocate(void* ptr, size_t newSize) override { /* ... */ }
|
||||
|
||||
size_t GetTotalAllocated() const override { return 0; }
|
||||
size_t GetTotalFreed() const override { return m_freed; }
|
||||
size_t GetPeakAllocated() const override { return 0; }
|
||||
size_t GetAllocationCount() const override { return 0; }
|
||||
const char* GetName() const override { return "MyAllocator"; }
|
||||
};
|
||||
|
||||
MyAllocator alloc;
|
||||
void* ptr = alloc.Allocate(128);
|
||||
alloc.Free(ptr);
|
||||
size_t freed = alloc.GetTotalFreed(); // 返回 128
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [IAllocator 总览](allocator.md) - 返回类总览
|
||||
55
docs/api/memory/allocator/reallocate.md
Normal file
55
docs/api/memory/allocator/reallocate.md
Normal file
@@ -0,0 +1,55 @@
|
||||
# IAllocator::Reallocate
|
||||
|
||||
```cpp
|
||||
virtual void* Reallocate(void* ptr, size_t newSize) = 0;
|
||||
```
|
||||
|
||||
调整已分配内存块的大小。如果 `ptr` 为 `nullptr`，行为等同于 `Allocate(newSize)`。如果 `newSize` 为 0，行为等同于 `Free(ptr)` 并返回 `nullptr`。如果分配器不支持重新分配，应返回 `nullptr` 并保持原内存不变。
|
||||
|
||||
**参数：**
|
||||
- `ptr` - 指向现有内存块的指针
|
||||
- `newSize` - 新的字节大小
|
||||
|
||||
**返回：** 调整后的新内存块指针（可能与原指针不同）
|
||||
|
||||
**复杂度：** O(n)，需要分配新内存并复制数据
|
||||
|
||||
**示例：**
|
||||
|
||||
```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 {
|
||||
if (ptr) ::operator delete(ptr);
|
||||
}
|
||||
|
||||
void* Reallocate(void* ptr, size_t newSize) override {
|
||||
if (newSize == 0) {
|
||||
Free(ptr);
|
||||
return nullptr;
|
||||
}
|
||||
if (!ptr) return Allocate(newSize);
|
||||
|
||||
size_t oldSize = /* 需要外部记录 */ 256; // 示例中硬编码
|
||||
void* newPtr = Allocate(newSize);
|
||||
memcpy(newPtr, ptr, oldSize < newSize ? oldSize : newSize);
|
||||
Free(ptr);
|
||||
return newPtr;
|
||||
}
|
||||
// ... 其他方法实现
|
||||
};
|
||||
|
||||
MyAllocator alloc;
|
||||
void* ptr = alloc.Allocate(128);
|
||||
void* bigger = alloc.Reallocate(ptr, 256); // 扩展到 256 字节
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [IAllocator 总览](allocator.md) - 返回类总览
|
||||
41
docs/api/memory/linear-allocator/allocate.md
Normal file
41
docs/api/memory/linear-allocator/allocate.md
Normal file
@@ -0,0 +1,41 @@
|
||||
# LinearAllocator::Allocate
|
||||
|
||||
```cpp
|
||||
void* Allocate(size_t size, size_t alignment = 8) override;
|
||||
```
|
||||
|
||||
在缓冲区的当前位置顺序分配内存。每次分配都会将内部偏移量向前推进（对齐后）。如果剩余空间不足，则分配失败返回 `nullptr`。默认对齐值为 8 字节。
|
||||
|
||||
**参数：**
|
||||
- `size` - 请求的字节数
|
||||
- `alignment` - 内存对齐要求，默认为 8 字节
|
||||
|
||||
**返回：** 分配成功返回已对齐的指针，失败返回 `nullptr`
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Memory/LinearAllocator.h>
|
||||
|
||||
LinearAllocator allocator(1024);
|
||||
|
||||
// 分配 256 字节（8 字节对齐）
|
||||
void* ptr1 = allocator.Allocate(256);
|
||||
|
||||
// 分配 128 字节（16 字节对齐）
|
||||
void* ptr2 = allocator.Allocate(128, 16);
|
||||
|
||||
// 分配 64 字节（默认 8 字节对齐）
|
||||
void* ptr3 = allocator.Allocate(64);
|
||||
|
||||
// 检查是否成功
|
||||
if (!ptr1) {
|
||||
// 分配失败，缓冲区已满
|
||||
}
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [LinearAllocator 总览](linear-allocator.md) - 返回类总览
|
||||
37
docs/api/memory/linear-allocator/clear.md
Normal file
37
docs/api/memory/linear-allocator/clear.md
Normal file
@@ -0,0 +1,37 @@
|
||||
# LinearAllocator::Clear
|
||||
|
||||
```cpp
|
||||
void Clear();
|
||||
```
|
||||
|
||||
清空分配器，将内部偏移量重置为 0，所有已分配的内存被视为已释放。下一次 `Allocate` 将从缓冲区起始位置开始。此方法不实际释放或修改底层内存，适合作为帧分配器使用，每帧开始时调用 Clear 重置。
|
||||
|
||||
**参数：** 无
|
||||
|
||||
**返回：** 无
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Memory/LinearAllocator.h>
|
||||
|
||||
LinearAllocator allocator(1024 * 1024);
|
||||
|
||||
// 第一帧
|
||||
void* frame1_ptr = allocator.Allocate(256);
|
||||
void* frame1_ptr2 = allocator.Allocate(128);
|
||||
// ... 第一帧渲染逻辑
|
||||
|
||||
// 帧结束时清空
|
||||
allocator.Clear();
|
||||
|
||||
// 第二帧重新开始
|
||||
void* frame2_ptr = allocator.Allocate(256);
|
||||
// 此时 frame1_ptr 已无效，但内存已被回收复用
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [LinearAllocator 总览](linear-allocator.md) - 返回类总览
|
||||
35
docs/api/memory/linear-allocator/free.md
Normal file
35
docs/api/memory/linear-allocator/free.md
Normal file
@@ -0,0 +1,35 @@
|
||||
# LinearAllocator::Free
|
||||
|
||||
```cpp
|
||||
void Free(void* ptr) override;
|
||||
```
|
||||
|
||||
此方法对 LinearAllocator 无实际效果。线性分配器不支持单个内存块的释放，因为内存是顺序分配的，释放中间某块会破坏后续分配的完整性。需要释放所有内存时使用 `Clear()` 方法。
|
||||
|
||||
**参数：**
|
||||
- `ptr` - 被忽略
|
||||
|
||||
**返回：** 无
|
||||
|
||||
**复杂度：** O(1)（空操作）
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Memory/LinearAllocator.h>
|
||||
|
||||
LinearAllocator allocator(1024);
|
||||
void* ptr = allocator.Allocate(256);
|
||||
void* ptr2 = allocator.Allocate(128);
|
||||
|
||||
// Free 实际上什么都不做
|
||||
allocator.Free(ptr);
|
||||
allocator.Free(ptr2);
|
||||
|
||||
// 如需释放所有内存，应使用 Clear
|
||||
allocator.Clear();
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [LinearAllocator 总览](linear-allocator.md) - 返回类总览
|
||||
33
docs/api/memory/linear-allocator/get-capacity.md
Normal file
33
docs/api/memory/linear-allocator/get-capacity.md
Normal file
@@ -0,0 +1,33 @@
|
||||
# LinearAllocator::GetCapacity
|
||||
|
||||
```cpp
|
||||
size_t GetCapacity() const;
|
||||
```
|
||||
|
||||
返回分配器的总容量，即预分配缓冲区的大小。此值在构造时确定，之后保持不变。
|
||||
|
||||
**参数：** 无
|
||||
|
||||
**返回：** 总容量（字节数）
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Memory/LinearAllocator.h>
|
||||
|
||||
LinearAllocator allocator(1024 * 1024); // 1MB
|
||||
|
||||
size_t capacity = allocator.GetCapacity(); // 1048576
|
||||
|
||||
allocator.Allocate(512);
|
||||
allocator.Allocate(256);
|
||||
|
||||
size_t used = allocator.GetUsedSize(); // 768
|
||||
size_t remaining = allocator.GetCapacity() - allocator.GetUsedSize(); // 1047808
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [LinearAllocator 总览](linear-allocator.md) - 返回类总览
|
||||
41
docs/api/memory/linear-allocator/get-marker.md
Normal file
41
docs/api/memory/linear-allocator/get-marker.md
Normal file
@@ -0,0 +1,41 @@
|
||||
# LinearAllocator::GetMarker
|
||||
|
||||
```cpp
|
||||
void* GetMarker() const;
|
||||
```
|
||||
|
||||
获取当前分配位置的标记。标记是一个指向当前偏移量的指针，可用于 `SetMarker` 恢复到该位置。此方法用于实现临时分配的撤销功能。
|
||||
|
||||
**参数：** 无
|
||||
|
||||
**返回：** 当前分配位置的指针标记
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Memory/LinearAllocator.h>
|
||||
|
||||
LinearAllocator allocator(1024);
|
||||
|
||||
// 分配一些数据
|
||||
void* ptr1 = allocator.Allocate(128);
|
||||
|
||||
// 保存标记（用于回滚点）
|
||||
void* marker = allocator.GetMarker();
|
||||
|
||||
// 分配临时数据
|
||||
void* temp = allocator.Allocate(64);
|
||||
void* temp2 = allocator.Allocate(32);
|
||||
|
||||
// 临时数据用完了，恢复到标记位置
|
||||
allocator.SetMarker(marker);
|
||||
|
||||
// 此时 temp 和 temp2 的内存已被回收
|
||||
// ptr1 仍然有效
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [LinearAllocator 总览](linear-allocator.md) - 返回类总览
|
||||
39
docs/api/memory/linear-allocator/get-used-size.md
Normal file
39
docs/api/memory/linear-allocator/get-used-size.md
Normal file
@@ -0,0 +1,39 @@
|
||||
# LinearAllocator::GetUsedSize
|
||||
|
||||
```cpp
|
||||
size_t GetUsedSize() const;
|
||||
```
|
||||
|
||||
返回当前已使用的字节数，即内部偏移量的值。此值在 `Allocate` 后增加，在 `Clear` 或 `SetMarker` 后可能减少（取决于设置的目标位置）。
|
||||
|
||||
**参数：** 无
|
||||
|
||||
**返回：** 已使用的字节数
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Memory/LinearAllocator.h>
|
||||
|
||||
LinearAllocator allocator(1024);
|
||||
|
||||
size_t before = allocator.GetUsedSize(); // 0
|
||||
|
||||
allocator.Allocate(128);
|
||||
allocator.Allocate(256);
|
||||
|
||||
size_t after = allocator.GetUsedSize(); // 384
|
||||
|
||||
void* marker = allocator.GetMarker();
|
||||
allocator.Allocate(64);
|
||||
size_t with_temp = allocator.GetUsedSize(); // 448
|
||||
|
||||
allocator.SetMarker(marker);
|
||||
size_t after_rollback = allocator.GetUsedSize(); // 384
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [LinearAllocator 总览](linear-allocator.md) - 返回类总览
|
||||
35
docs/api/memory/linear-allocator/linear-allocator.md
Normal file
35
docs/api/memory/linear-allocator/linear-allocator.md
Normal file
@@ -0,0 +1,35 @@
|
||||
# LinearAllocator::LinearAllocator
|
||||
|
||||
```cpp
|
||||
explicit LinearAllocator(size_t size, IAllocator* parent = nullptr);
|
||||
```
|
||||
|
||||
构造一个线性分配器，预分配指定大小的缓冲区。如果提供了 `parent` 分配器，则使用它分配底层缓冲区；否则使用系统默认分配（`_aligned_malloc`，8 字节对齐）。
|
||||
|
||||
**参数：**
|
||||
- `size` - 预分配的缓冲区大小（字节数）
|
||||
- `parent` - 父分配器，用于分配底层缓冲区，默认为 `nullptr`（使用系统分配）
|
||||
|
||||
**返回：** 无
|
||||
|
||||
**复杂度：** O(n)，需要分配 `size` 大小的缓冲区
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Memory/LinearAllocator.h>
|
||||
|
||||
// 使用系统分配器创建 1MB 线性分配器
|
||||
LinearAllocator allocator1(1024 * 1024);
|
||||
|
||||
// 使用指定的父分配器
|
||||
IAllocator* parent = MemoryManager::Get().GetSystemAllocator();
|
||||
LinearAllocator allocator2(1024 * 1024, parent);
|
||||
|
||||
// 默认 8 字节对齐
|
||||
void* ptr = allocator1.Allocate(256);
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [LinearAllocator 总览](linear-allocator.md) - 返回类总览
|
||||
34
docs/api/memory/linear-allocator/reallocate.md
Normal file
34
docs/api/memory/linear-allocator/reallocate.md
Normal file
@@ -0,0 +1,34 @@
|
||||
# LinearAllocator::Reallocate
|
||||
|
||||
```cpp
|
||||
void* Reallocate(void* ptr, size_t newSize) override;
|
||||
```
|
||||
|
||||
在缓冲区当前位置分配新内存。此方法始终在缓冲区末尾分配新内存，而不是尝试调整现有块的大小。返回的指针可能与输入的 `ptr` 不同。如果剩余空间不足，返回 `nullptr` 且原指针保持不变。
|
||||
|
||||
**参数：**
|
||||
- `ptr` - 被忽略（始终分配新内存）
|
||||
- `newSize` - 新请求的字节数
|
||||
|
||||
**返回：** 分配成功返回新内存指针，失败返回 `nullptr`
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Memory/LinearAllocator.h>
|
||||
|
||||
LinearAllocator allocator(1024);
|
||||
void* ptr1 = allocator.Allocate(128);
|
||||
|
||||
// Reallocate 忽略原 ptr，在当前位置分配新内存
|
||||
void* ptr2 = allocator.Reallocate(ptr1, 256);
|
||||
|
||||
// ptr1 和 ptr2 可能相同也可能不同
|
||||
// 都不会被释放，新内存始终在缓冲区末尾分配
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [LinearAllocator 总览](linear-allocator.md) - 返回类总览
|
||||
41
docs/api/memory/linear-allocator/set-marker.md
Normal file
41
docs/api/memory/linear-allocator/set-marker.md
Normal file
@@ -0,0 +1,41 @@
|
||||
# LinearAllocator::SetMarker
|
||||
|
||||
```cpp
|
||||
void SetMarker(void* marker);
|
||||
```
|
||||
|
||||
恢复到之前通过 `GetMarker` 获取的标记位置。所有在标记之后的分配都将被丢弃，内部偏移量重置为该标记位置。此方法不会释放内存，只是移动偏移量指针。
|
||||
|
||||
**参数：**
|
||||
- `marker` - 通过 `GetMarker` 获取的标记指针
|
||||
|
||||
**返回：** 无
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Memory/LinearAllocator.h>
|
||||
|
||||
LinearAllocator allocator(1024);
|
||||
|
||||
// 基础数据
|
||||
void* base = allocator.Allocate(256);
|
||||
void* marker = allocator.GetMarker();
|
||||
|
||||
// 可选的扩展数据
|
||||
void* ext1 = allocator.Allocate(64);
|
||||
void* ext2 = allocator.Allocate(128);
|
||||
|
||||
// 决定不使用扩展数据，回滚
|
||||
allocator.SetMarker(marker);
|
||||
|
||||
// 扩展数据内存已被回收
|
||||
// 可以重新分配其他数据
|
||||
void* new_data = allocator.Allocate(128);
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [LinearAllocator 总览](linear-allocator.md) - 返回类总览
|
||||
29
docs/api/memory/linear-allocator/~linear-allocator.md
Normal file
29
docs/api/memory/linear-allocator/~linear-allocator.md
Normal file
@@ -0,0 +1,29 @@
|
||||
# LinearAllocator::~LinearAllocator
|
||||
|
||||
```cpp
|
||||
~LinearAllocator() override;
|
||||
```
|
||||
|
||||
销毁线性分配器，释放预分配的缓冲区。如果提供了 `parent` 分配器，则使用它释放缓冲区；否则使用系统默认释放（`::operator delete`）。
|
||||
|
||||
**参数：** 无
|
||||
|
||||
**返回：** 无
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Memory/LinearAllocator.h>
|
||||
|
||||
{
|
||||
LinearAllocator allocator(1024 * 1024);
|
||||
void* ptr = allocator.Allocate(256);
|
||||
// ... 使用 allocator
|
||||
} // 析构时自动释放 1MB 缓冲区
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [LinearAllocator 总览](linear-allocator.md) - 返回类总览
|
||||
32
docs/api/memory/manager/create-linear-allocator.md
Normal file
32
docs/api/memory/manager/create-linear-allocator.md
Normal file
@@ -0,0 +1,32 @@
|
||||
# MemoryManager::CreateLinearAllocator
|
||||
|
||||
```cpp
|
||||
std::unique_ptr<LinearAllocator> CreateLinearAllocator(size_t size);
|
||||
```
|
||||
|
||||
创建并返回一个新的 LinearAllocator 实例，使用系统分配器作为底层。返回的 `unique_ptr` 管理分配器生命周期。
|
||||
|
||||
**参数：**
|
||||
- `size` - 分配器缓冲区大小（字节）
|
||||
|
||||
**返回：** LinearAllocator 的 unique_ptr
|
||||
|
||||
**复杂度：** O(size)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Memory/MemoryManager.h>
|
||||
|
||||
auto linear = MemoryManager::Get().CreateLinearAllocator(1024 * 1024);
|
||||
void* ptr = linear->Allocate(256);
|
||||
void* marker = linear->GetMarker();
|
||||
linear->Allocate(128);
|
||||
linear->SetMarker(marker);
|
||||
linear->Clear();
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [MemoryManager 总览](manager.md) - 返回类总览
|
||||
- [LinearAllocator](../linear-allocator/linear-allocator.md) - 线性分配器
|
||||
37
docs/api/memory/manager/create-pool-allocator.md
Normal file
37
docs/api/memory/manager/create-pool-allocator.md
Normal file
@@ -0,0 +1,37 @@
|
||||
# MemoryManager::CreatePoolAllocator
|
||||
|
||||
```cpp
|
||||
std::unique_ptr<PoolAllocator> CreatePoolAllocator(size_t blockSize, size_t count);
|
||||
```
|
||||
|
||||
创建并返回一个新的 PoolAllocator 实例，使用系统分配器作为底层。返回的 `unique_ptr` 管理分配器生命周期。
|
||||
|
||||
**参数：**
|
||||
- `blockSize` - 每个内存块的大小（字节）
|
||||
- `count` - 内存池中块的数量
|
||||
|
||||
**返回：** PoolAllocator 的 unique_ptr
|
||||
|
||||
**复杂度：** O(blockSize * count)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Memory/MemoryManager.h>
|
||||
|
||||
struct Particle {
|
||||
float x, y, z;
|
||||
float life;
|
||||
};
|
||||
|
||||
auto pool = MemoryManager::Get().CreatePoolAllocator(sizeof(Particle), 1000);
|
||||
void* block = pool->Allocate();
|
||||
auto* p = new (block) Particle{1.0f, 2.0f, 3.0f, 5.0f};
|
||||
p->~Particle();
|
||||
pool->Free(block);
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [MemoryManager 总览](manager.md) - 返回类总览
|
||||
- [PoolAllocator](../pool-allocator/pool-allocator.md) - 内存池分配器
|
||||
36
docs/api/memory/manager/create-proxy-allocator.md
Normal file
36
docs/api/memory/manager/create-proxy-allocator.md
Normal file
@@ -0,0 +1,36 @@
|
||||
# MemoryManager::CreateProxyAllocator
|
||||
|
||||
```cpp
|
||||
std::unique_ptr<ProxyAllocator> CreateProxyAllocator(const char* name);
|
||||
```
|
||||
|
||||
创建并返回一个新的 ProxyAllocator 实例，包装系统分配器并使用指定名称。返回的 `unique_ptr` 管理分配器生命周期。
|
||||
|
||||
**参数：**
|
||||
- `name` - 代理分配器的名称
|
||||
|
||||
**返回：** ProxyAllocator 的 unique_ptr
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Memory/MemoryManager.h>
|
||||
|
||||
auto proxy = MemoryManager::Get().CreateProxyAllocator("FrameData");
|
||||
void* ptr = proxy->Allocate(1024);
|
||||
void* ptr2 = proxy->Allocate(512);
|
||||
|
||||
const auto& stats = proxy->GetStats();
|
||||
printf("Peak: %zu bytes, Count: %zu\n",
|
||||
stats.peakAllocated, stats.allocationCount);
|
||||
|
||||
proxy->Free(ptr);
|
||||
proxy->Free(ptr2);
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [MemoryManager 总览](manager.md) - 返回类总览
|
||||
- [ProxyAllocator](../proxy-allocator/proxy-allocator.md) - 代理分配器
|
||||
31
docs/api/memory/manager/dump-memory-leaks.md
Normal file
31
docs/api/memory/manager/dump-memory-leaks.md
Normal file
@@ -0,0 +1,31 @@
|
||||
# MemoryManager::DumpMemoryLeaks
|
||||
|
||||
```cpp
|
||||
void DumpMemoryLeaks();
|
||||
```
|
||||
|
||||
输出当前未释放的内存分配信息。如果启用了内存跟踪，此方法会遍历所有记录并报告疑似泄漏的分配。应在程序退出前调用，以便发现资源泄漏。
|
||||
|
||||
**参数：** 无
|
||||
|
||||
**返回：** 无
|
||||
|
||||
**复杂度：** O(n)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Memory/MemoryManager.h>
|
||||
|
||||
MemoryManager::Get().Initialize();
|
||||
|
||||
// ... 程序运行 ...
|
||||
|
||||
// 程序退出前检查泄漏
|
||||
MemoryManager::Get().DumpMemoryLeaks();
|
||||
MemoryManager::Get().Shutdown();
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [MemoryManager 总览](manager.md) - 返回类总览
|
||||
37
docs/api/memory/manager/generate-memory-report.md
Normal file
37
docs/api/memory/manager/generate-memory-report.md
Normal file
@@ -0,0 +1,37 @@
|
||||
# MemoryManager::GenerateMemoryReport
|
||||
|
||||
```cpp
|
||||
void GenerateMemoryReport();
|
||||
```
|
||||
|
||||
生成并输出当前内存使用情况的详细报告。报告内容包括各分配器的统计信息、峰值使用量、分配次数等。应在启用内存跟踪后调用。
|
||||
|
||||
**参数：** 无
|
||||
|
||||
**返回：** 无
|
||||
|
||||
**复杂度：** O(n)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Memory/MemoryManager.h>
|
||||
|
||||
MemoryManager::Get().Initialize();
|
||||
|
||||
auto proxy = MemoryManager::Get().CreateProxyAllocator("GameFrame");
|
||||
proxy->Allocate(1024 * 1024);
|
||||
proxy->Allocate(512 * 1024);
|
||||
|
||||
// 生成内存报告
|
||||
MemoryManager::Get().GenerateMemoryReport();
|
||||
|
||||
proxy->Free(proxy->Allocate(256 * 1024));
|
||||
MemoryManager::Get().GenerateMemoryReport();
|
||||
|
||||
MemoryManager::Get().Shutdown();
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [MemoryManager 总览](manager.md) - 返回类总览
|
||||
27
docs/api/memory/manager/get-system-allocator.md
Normal file
27
docs/api/memory/manager/get-system-allocator.md
Normal file
@@ -0,0 +1,27 @@
|
||||
# MemoryManager::GetSystemAllocator
|
||||
|
||||
```cpp
|
||||
IAllocator* GetSystemAllocator();
|
||||
```
|
||||
|
||||
获取系统默认分配器。该分配器使用标准 C 库的 `std::malloc` 和平台特定的对齐分配函数（如 Windows 的 `_aligned_malloc`）作为后端，适用于通用内存分配场景。
|
||||
|
||||
**参数：** 无
|
||||
|
||||
**返回：** 系统分配器指针
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Memory/MemoryManager.h>
|
||||
|
||||
IAllocator* sysAlloc = MemoryManager::Get().GetSystemAllocator();
|
||||
void* ptr = sysAlloc->Allocate(1024);
|
||||
sysAlloc->Free(ptr);
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [MemoryManager 总览](manager.md) - 返回类总览
|
||||
39
docs/api/memory/manager/get.md
Normal file
39
docs/api/memory/manager/get.md
Normal file
@@ -0,0 +1,39 @@
|
||||
# MemoryManager::Get
|
||||
|
||||
```cpp
|
||||
static MemoryManager& Get();
|
||||
```
|
||||
|
||||
获取 MemoryManager 单例实例。如果尚未创建则内部构造。此方法是获取内存管理器实例的唯一途径。
|
||||
|
||||
**参数：** 无
|
||||
|
||||
**返回：** MemoryManager 单例引用
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Memory/MemoryManager.h>
|
||||
|
||||
// 获取单例
|
||||
MemoryManager& manager = MemoryManager::Get();
|
||||
|
||||
// 初始化
|
||||
manager.Initialize();
|
||||
|
||||
// 访问系统分配器
|
||||
IAllocator* sysAlloc = manager.GetSystemAllocator();
|
||||
|
||||
// 关闭
|
||||
manager.Shutdown();
|
||||
|
||||
// 多次调用返回同一实例
|
||||
MemoryManager& manager2 = MemoryManager::Get();
|
||||
// manager == manager2 为 true
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [MemoryManager 总览](manager.md) - 返回类总览
|
||||
33
docs/api/memory/manager/initialize.md
Normal file
33
docs/api/memory/manager/initialize.md
Normal file
@@ -0,0 +1,33 @@
|
||||
# MemoryManager::Initialize
|
||||
|
||||
```cpp
|
||||
void Initialize();
|
||||
```
|
||||
|
||||
初始化内存管理器。创建系统默认分配器，设置内存跟踪标志。应在程序启动早期调用，且仅可调用一次。
|
||||
|
||||
**参数：** 无
|
||||
|
||||
**返回：** 无
|
||||
|
||||
**复杂度：** O(n)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Memory/MemoryManager.h>
|
||||
|
||||
int main() {
|
||||
// 程序启动时初始化
|
||||
MemoryManager::Get().Initialize();
|
||||
|
||||
// 使用内存系统...
|
||||
|
||||
MemoryManager::Get().Shutdown();
|
||||
return 0;
|
||||
}
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [MemoryManager 总览](manager.md) - 返回类总览
|
||||
@@ -14,7 +14,7 @@
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `static MemoryManager& Get()` | 获取单例实例 |
|
||||
| `Get` | 获取单例实例 |
|
||||
|
||||
## 公共方法
|
||||
|
||||
@@ -22,30 +22,30 @@
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `void Initialize()` | 初始化内存管理器 |
|
||||
| `void Shutdown()` | 关闭内存管理器 |
|
||||
| `Initialize` | 初始化内存管理器 |
|
||||
| `Shutdown` | 关闭内存管理器 |
|
||||
|
||||
### 系统分配器
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `IAllocator* GetSystemAllocator()` | 获取系统默认分配器 |
|
||||
| `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)` | 创建代理分配器 |
|
||||
| `CreateLinearAllocator` | 创建线性分配器 |
|
||||
| `CreatePoolAllocator` | 创建内存池分配器 |
|
||||
| `CreateProxyAllocator` | 创建代理分配器 |
|
||||
|
||||
### 内存管理
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `void SetTrackAllocations(bool track)` | 设置是否跟踪分配 |
|
||||
| `void DumpMemoryLeaks()` | 输出内存泄漏报告 |
|
||||
| `void GenerateMemoryReport()` | 生成内存使用报告 |
|
||||
| `SetTrackAllocations` | 设置是否跟踪分配 |
|
||||
| `DumpMemoryLeaks` | 输出内存泄漏报告 |
|
||||
| `GenerateMemoryReport` | 生成内存使用报告 |
|
||||
|
||||
## 宏定义
|
||||
|
||||
@@ -68,6 +68,8 @@
|
||||
## 使用示例
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Memory/MemoryManager.h>
|
||||
|
||||
// 初始化
|
||||
MemoryManager::Get().Initialize();
|
||||
|
||||
@@ -93,7 +95,8 @@ MemoryManager::Get().Shutdown();
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [IAllocator](./memory-allocator.md) - 分配器接口
|
||||
- [LinearAllocator](./memory-linear-allocator.md) - 线性分配器
|
||||
- [PoolAllocator](./memory-pool-allocator.md) - 内存池分配器
|
||||
- [ProxyAllocator](./memory-proxy-allocator.md) - 代理分配器
|
||||
- [Memory 模块总览](../memory.md) - 返回模块总览
|
||||
- [IAllocator](../allocator/allocator.md) - 分配器接口
|
||||
- [LinearAllocator](../linear-allocator/linear-allocator.md) - 线性分配器
|
||||
- [PoolAllocator](../pool-allocator/pool-allocator.md) - 内存池分配器
|
||||
- [ProxyAllocator](../proxy-allocator/proxy-allocator.md) - 代理分配器
|
||||
35
docs/api/memory/manager/set-track-allocations.md
Normal file
35
docs/api/memory/manager/set-track-allocations.md
Normal file
@@ -0,0 +1,35 @@
|
||||
# MemoryManager::SetTrackAllocations
|
||||
|
||||
```cpp
|
||||
void SetTrackAllocations(bool track);
|
||||
```
|
||||
|
||||
设置是否启用内存分配跟踪。启用后系统会记录所有分配操作，用于生成内存报告和泄漏检测。
|
||||
|
||||
**参数：**
|
||||
- `track` - true 启用跟踪，false 禁用跟踪
|
||||
|
||||
**返回：** 无
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Memory/MemoryManager.h>
|
||||
|
||||
MemoryManager::Get().Initialize();
|
||||
|
||||
// 禁用跟踪（提升性能）
|
||||
MemoryManager::Get().SetTrackAllocations(false);
|
||||
|
||||
// ... 大量内存操作 ...
|
||||
|
||||
// 重新启用跟踪进行分析
|
||||
MemoryManager::Get().SetTrackAllocations(true);
|
||||
MemoryManager::Get().GenerateMemoryReport();
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [MemoryManager 总览](manager.md) - 返回类总览
|
||||
35
docs/api/memory/manager/shutdown.md
Normal file
35
docs/api/memory/manager/shutdown.md
Normal file
@@ -0,0 +1,35 @@
|
||||
# MemoryManager::Shutdown
|
||||
|
||||
```cpp
|
||||
void Shutdown();
|
||||
```
|
||||
|
||||
关闭内存管理器。执行内存泄漏检测报告，释放系统分配器。应在程序退出前调用。
|
||||
|
||||
**参数：** 无
|
||||
|
||||
**返回：** 无
|
||||
|
||||
**复杂度：** O(n)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Memory/MemoryManager.h>
|
||||
|
||||
int main() {
|
||||
MemoryManager::Get().Initialize();
|
||||
|
||||
// ... 游戏主循环 ...
|
||||
|
||||
// 程序退出前关闭
|
||||
MemoryManager::Get().DumpMemoryLeaks();
|
||||
MemoryManager::Get().Shutdown();
|
||||
|
||||
return 0;
|
||||
}
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [MemoryManager 总览](manager.md) - 返回类总览
|
||||
@@ -1,82 +0,0 @@
|
||||
# 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) - 代理分配器
|
||||
@@ -1,75 +0,0 @@
|
||||
# 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) - 代理分配器
|
||||
@@ -1,71 +0,0 @@
|
||||
# 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) - 内存管理器
|
||||
@@ -16,21 +16,21 @@ Memory 模块提供了一套完整的内存管理解决方案，包括基础分
|
||||
|
||||
| 组件 | 文件 | 描述 |
|
||||
|------|------|------|
|
||||
| [IAllocator](./memory-allocator.md) | `Allocator.h` | 内存分配器抽象接口 |
|
||||
| [IAllocator](allocator/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` | 代理分配器，用于统计和跟踪 |
|
||||
| [LinearAllocator](linear-allocator/linear-allocator.md) | `LinearAllocator.h` | 线性分配器，适合帧分配 |
|
||||
| [PoolAllocator](pool-allocator/pool-allocator.md) | `PoolAllocator.h` | 内存池分配器，适合固定大小对象 |
|
||||
| [ProxyAllocator](proxy-allocator/proxy-allocator.md) | `ProxyAllocator.h` | 代理分配器，用于统计和跟踪 |
|
||||
|
||||
### 管理器
|
||||
|
||||
| 组件 | 文件 | 描述 |
|
||||
|------|------|------|
|
||||
| [MemoryManager](./memory-manager.md) | `MemoryManager.h` | 全局内存管理器 |
|
||||
| [MemoryManager](manager/manager.md) | `MemoryManager.h` | 全局内存管理器 |
|
||||
|
||||
## 分配器类型对比
|
||||
|
||||
@@ -69,4 +69,4 @@ XE_FREE(linearAlloc, ptr);
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [Containers 模块](../containers/container-overview.md) - 使用分配器的容器
|
||||
- [Containers 模块](../containers/containers.md) - 使用分配器的容器
|
||||
37
docs/api/memory/pool-allocator/allocate.md
Normal file
37
docs/api/memory/pool-allocator/allocate.md
Normal file
@@ -0,0 +1,37 @@
|
||||
# PoolAllocator::Allocate
|
||||
|
||||
```cpp
|
||||
void* Allocate(size_t size, size_t alignment = 0) override;
|
||||
```
|
||||
|
||||
从内存池中分配一个空闲块。此方法忽略 `size` 参数，始终分配一个固定大小的块。如果池中没有空闲块，返回 `nullptr`。分配操作从空闲链表头部取出一个块。
|
||||
|
||||
**参数：**
|
||||
- `size` - 被忽略（始终分配固定块大小）
|
||||
- `alignment` - 被忽略（构造时确定）
|
||||
|
||||
**返回：** 分配成功返回块指针，池空返回 `nullptr`
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Memory/PoolAllocator.h>
|
||||
|
||||
PoolAllocator pool(sizeof(int) * 100, 50, alignof(int));
|
||||
|
||||
// 分配（忽略 size 参数）
|
||||
void* block1 = pool.Allocate(1); // 分配 1 字节
|
||||
void* block2 = pool.Allocate(10000); // 也分配一块
|
||||
|
||||
if (block1 && block2) {
|
||||
// 使用分配的内存块
|
||||
int* arr = static_cast<int*>(block1);
|
||||
arr[0] = 42;
|
||||
}
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [PoolAllocator 总览](pool-allocator.md) - 返回类总览
|
||||
38
docs/api/memory/pool-allocator/contains.md
Normal file
38
docs/api/memory/pool-allocator/contains.md
Normal file
@@ -0,0 +1,38 @@
|
||||
# PoolAllocator::Contains
|
||||
|
||||
```cpp
|
||||
bool Contains(void* ptr) const;
|
||||
```
|
||||
|
||||
检查给定的指针是否属于此内存池的地址范围。由于池在构造时预分配连续内存，可通过指针地址区间判断所有权。此方法用于调试和内存验证。
|
||||
|
||||
**参数：**
|
||||
- `ptr` - 要检查的指针
|
||||
|
||||
**返回：** 指针属于此池返回 `true`，否则返回 `false`
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Memory/PoolAllocator.h>
|
||||
|
||||
PoolAllocator pool(sizeof(int), 100);
|
||||
|
||||
void* inside = pool.Allocate();
|
||||
void* outside = ::operator new(sizeof(int));
|
||||
|
||||
if (pool.Contains(inside)) {
|
||||
// inside 属于此内存池，可以安全 Free
|
||||
}
|
||||
|
||||
if (!pool.Contains(outside)) {
|
||||
// outside 不属于此池，不能调用 pool.Free()
|
||||
::operator delete(outside);
|
||||
}
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [PoolAllocator 总览](pool-allocator.md) - 返回类总览
|
||||
38
docs/api/memory/pool-allocator/free.md
Normal file
38
docs/api/memory/pool-allocator/free.md
Normal file
@@ -0,0 +1,38 @@
|
||||
# PoolAllocator::Free
|
||||
|
||||
```cpp
|
||||
void Free(void* ptr) override;
|
||||
```
|
||||
|
||||
将内存块归还到空闲链表中。如果 `ptr` 为 `nullptr` 则无效果。释放操作将块插入空闲链表头部。必须传入从此池分配的指针，传入外部指针会导致未定义行为。
|
||||
|
||||
**参数：**
|
||||
- `ptr` - 指向要释放的内存块
|
||||
|
||||
**返回：** 无
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Memory/PoolAllocator.h>
|
||||
|
||||
PoolAllocator pool(sizeof(int), 100);
|
||||
|
||||
void* block = pool.Allocate();
|
||||
if (block) {
|
||||
int* num = static_cast<int*>(block);
|
||||
*num = 123;
|
||||
|
||||
pool.Free(block); // 归还到空闲链表
|
||||
block = nullptr;
|
||||
}
|
||||
|
||||
// 检查空闲块数量
|
||||
size_t freeCount = pool.GetFreeBlockCount();
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [PoolAllocator 总览](pool-allocator.md) - 返回类总览
|
||||
31
docs/api/memory/pool-allocator/get-block-size.md
Normal file
31
docs/api/memory/pool-allocator/get-block-size.md
Normal file
@@ -0,0 +1,31 @@
|
||||
# PoolAllocator::GetBlockSize
|
||||
|
||||
```cpp
|
||||
size_t GetBlockSize() const;
|
||||
```
|
||||
|
||||
返回内存池中每个内存块的大小。此值在构造时确定，之后保持不变。
|
||||
|
||||
**参数：** 无
|
||||
|
||||
**返回：** 每个内存块的字节大小
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Memory/PoolAllocator.h>
|
||||
|
||||
PoolAllocator pool(sizeof(int) * 100, 50);
|
||||
|
||||
size_t blockSize = pool.GetBlockSize(); // 400 字节
|
||||
|
||||
void* block = pool.Allocate();
|
||||
int* arr = static_cast<int*>(block);
|
||||
// arr 指向的大小为 blockSize 字节的内存块
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [PoolAllocator 总览](pool-allocator.md) - 返回类总览
|
||||
40
docs/api/memory/pool-allocator/get-free-block-count.md
Normal file
40
docs/api/memory/pool-allocator/get-free-block-count.md
Normal file
@@ -0,0 +1,40 @@
|
||||
# PoolAllocator::GetFreeBlockCount
|
||||
|
||||
```cpp
|
||||
size_t GetFreeBlockCount() const;
|
||||
```
|
||||
|
||||
返回当前空闲块的的数量。每次 `Allocate` 成功后减 1，每次 `Free` 后加 1。
|
||||
|
||||
**参数：** 无
|
||||
|
||||
**返回：** 当前可分配的空闲块数量
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Memory/PoolAllocator.h>
|
||||
|
||||
PoolAllocator pool(sizeof(int), 100);
|
||||
|
||||
size_t initial = pool.GetFreeBlockCount(); // 100
|
||||
|
||||
void* blocks[10];
|
||||
for (int i = 0; i < 10; ++i) {
|
||||
blocks[i] = pool.Allocate();
|
||||
}
|
||||
|
||||
size_t after = pool.GetFreeBlockCount(); // 90
|
||||
|
||||
for (int i = 0; i < 5; ++i) {
|
||||
pool.Free(blocks[i]);
|
||||
}
|
||||
|
||||
size_t final = pool.GetFreeBlockCount(); // 95
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [PoolAllocator 总览](pool-allocator.md) - 返回类总览
|
||||
34
docs/api/memory/pool-allocator/get-total-block-count.md
Normal file
34
docs/api/memory/pool-allocator/get-total-block-count.md
Normal file
@@ -0,0 +1,34 @@
|
||||
# PoolAllocator::GetTotalBlockCount
|
||||
|
||||
```cpp
|
||||
size_t GetTotalBlockCount() const;
|
||||
```
|
||||
|
||||
返回内存池中的总块数。此值在构造时确定，之后保持不变。
|
||||
|
||||
**参数：** 无
|
||||
|
||||
**返回：** 内存池的总块数
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Memory/PoolAllocator.h>
|
||||
|
||||
PoolAllocator pool(sizeof(int), 100);
|
||||
|
||||
size_t total = pool.GetTotalBlockCount(); // 100
|
||||
size_t free = pool.GetFreeBlockCount(); // 100
|
||||
|
||||
void* block = pool.Allocate();
|
||||
size_t freeAfter = pool.GetFreeBlockCount(); // 99
|
||||
|
||||
pool.Free(block);
|
||||
size_t freeRestored = pool.GetFreeBlockCount(); // 100
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [PoolAllocator 总览](pool-allocator.md) - 返回类总览
|
||||
44
docs/api/memory/pool-allocator/pool-allocator.md
Normal file
44
docs/api/memory/pool-allocator/pool-allocator.md
Normal file
@@ -0,0 +1,44 @@
|
||||
# PoolAllocator::PoolAllocator / ~PoolAllocator
|
||||
|
||||
```cpp
|
||||
PoolAllocator(size_t blockSize, size_t poolSize, size_t alignment = 8);
|
||||
~PoolAllocator() override;
|
||||
```
|
||||
|
||||
构造内存池分配器，预分配 `poolSize` 个大小为 `blockSize` 字节的内存块。内存块按 `alignment` 对齐（默认 8 字节）。内部维护一个空闲块链表来管理分配。析构函数释放整个内存池。
|
||||
|
||||
**参数：**
|
||||
- `blockSize` - 每个内存块的大小（字节）
|
||||
- `poolSize` - 内存池中总块数
|
||||
- `alignment` - 对齐要求，默认为 8
|
||||
|
||||
**返回：** 无
|
||||
|
||||
**复杂度：** O(n)，需要预分配所有块
|
||||
|
||||
**示例：**
|
||||
|
||||
```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);
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [PoolAllocator 总览](pool-allocator.md) - 返回类总览
|
||||
35
docs/api/memory/pool-allocator/reallocate.md
Normal file
35
docs/api/memory/pool-allocator/reallocate.md
Normal file
@@ -0,0 +1,35 @@
|
||||
# PoolAllocator::Reallocate
|
||||
|
||||
```cpp
|
||||
void* Reallocate(void* ptr, size_t newSize) override;
|
||||
```
|
||||
|
||||
内存池分配器不支持重新分配。此方法始终返回 `nullptr`，原内存块保持不变。
|
||||
|
||||
**参数：**
|
||||
- `ptr` - 不被使用
|
||||
- `newSize` - 不被使用
|
||||
|
||||
**返回：** 始终返回 `nullptr`
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Memory/PoolAllocator.h>
|
||||
|
||||
PoolAllocator pool(sizeof(int), 100);
|
||||
void* block = pool.Allocate();
|
||||
|
||||
// Reallocate 不支持
|
||||
void* newBlock = pool.Reallocate(block, 256);
|
||||
if (!newBlock) {
|
||||
// 内存池不支持重新分配
|
||||
// 原 block 仍然有效
|
||||
}
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [PoolAllocator 总览](pool-allocator.md) - 返回类总览
|
||||
37
docs/api/memory/proxy-allocator/allocate.md
Normal file
37
docs/api/memory/proxy-allocator/allocate.md
Normal file
@@ -0,0 +1,37 @@
|
||||
# ProxyAllocator::Allocate
|
||||
|
||||
```cpp
|
||||
void* Allocate(size_t size, size_t alignment = 0) override;
|
||||
```
|
||||
|
||||
分配内存并记录统计。调用转发到底层分配器，同时递增分配计数和总分配字节数，并更新峰值记录。
|
||||
|
||||
**参数：**
|
||||
- `size` - 请求的字节数
|
||||
- `alignment` - 内存对齐要求
|
||||
|
||||
**返回：** 分配成功返回指针，失败返回 `nullptr`
|
||||
|
||||
**复杂度：** O(1)（底层分配器复杂度 + 统计更新）
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Memory/MemoryManager.h>
|
||||
#include <XCEngine/Memory/ProxyAllocator.h>
|
||||
|
||||
IAllocator* sysAlloc = MemoryManager::Get().GetSystemAllocator();
|
||||
ProxyAllocator proxy(sysAlloc, "TrackedAlloc");
|
||||
|
||||
void* p1 = proxy.Allocate(100);
|
||||
void* p2 = proxy.Allocate(200);
|
||||
void* p3 = proxy.Allocate(300, 16);
|
||||
|
||||
const auto& stats = proxy.GetStats();
|
||||
printf("Total: %zu, Peak: %zu, Count: %zu\n",
|
||||
stats.totalAllocated, stats.peakAllocated, stats.allocationCount);
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [ProxyAllocator 总览](proxy-allocator.md) - 返回类总览
|
||||
39
docs/api/memory/proxy-allocator/free.md
Normal file
39
docs/api/memory/proxy-allocator/free.md
Normal file
@@ -0,0 +1,39 @@
|
||||
# ProxyAllocator::Free
|
||||
|
||||
```cpp
|
||||
void Free(void* ptr) override;
|
||||
```
|
||||
|
||||
释放内存并记录统计。调用转发到底层分配器，同时更新统计信息：增加总释放计数（而非字节大小，因为 ProxyAllocator 不记录释放的字节数），并递减当前分配计数。
|
||||
|
||||
**参数：**
|
||||
- `ptr` - 指向要释放的内存块
|
||||
|
||||
**返回：** 无
|
||||
|
||||
**复杂度：** O(1)（底层释放 + 统计更新）
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Memory/MemoryManager.h>
|
||||
#include <XCEngine/Memory/ProxyAllocator.h>
|
||||
|
||||
IAllocator* sysAlloc = MemoryManager::Get().GetSystemAllocator();
|
||||
ProxyAllocator proxy(sysAlloc, "TrackedAlloc");
|
||||
|
||||
void* p1 = proxy.Allocate(512);
|
||||
void* p2 = proxy.Allocate(256);
|
||||
|
||||
proxy.Free(p1);
|
||||
proxy.Free(p2);
|
||||
|
||||
const auto& stats = proxy.GetStats();
|
||||
printf("Total allocated: %zu, Total freed: %zu, Current: %zu\n",
|
||||
stats.totalAllocated, stats.totalFreed,
|
||||
stats.totalAllocated - stats.totalFreed);
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [ProxyAllocator 总览](proxy-allocator.md) - 返回类总览
|
||||
40
docs/api/memory/proxy-allocator/get-stats.md
Normal file
40
docs/api/memory/proxy-allocator/get-stats.md
Normal file
@@ -0,0 +1,40 @@
|
||||
# ProxyAllocator::GetStats
|
||||
|
||||
```cpp
|
||||
const Stats& GetStats() const;
|
||||
```
|
||||
|
||||
返回详细的统计信息结构体引用。包含累计分配、累计释放、峰值分配、分配次数和额外开销。返回 const 引用，无锁开销（内部已有互斥保护）。
|
||||
|
||||
**参数：** 无
|
||||
|
||||
**返回：** Stats 结构体 const 引用
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Memory/MemoryManager.h>
|
||||
#include <XCEngine/Memory/ProxyAllocator.h>
|
||||
|
||||
IAllocator* sysAlloc = MemoryManager::Get().GetSystemAllocator();
|
||||
ProxyAllocator proxy(sysAlloc, "FrameData");
|
||||
|
||||
proxy.Allocate(1024);
|
||||
proxy.Allocate(512);
|
||||
proxy.Free(proxy.Allocate(256));
|
||||
|
||||
const ProxyAllocator::Stats& stats = proxy.GetStats();
|
||||
printf("Total allocated: %zu bytes\n", stats.totalAllocated);
|
||||
printf("Total freed: %zu bytes\n", stats.totalFreed);
|
||||
printf("Peak allocated: %zu bytes\n", stats.peakAllocated);
|
||||
printf("Allocation count: %zu\n", stats.allocationCount);
|
||||
printf("Memory overhead: %zu bytes\n", stats.memoryOverhead);
|
||||
printf("Current in use: %zu bytes\n",
|
||||
stats.totalAllocated - stats.totalFreed);
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [ProxyAllocator 总览](proxy-allocator.md) - 返回类总览
|
||||
36
docs/api/memory/proxy-allocator/proxy-allocator.md
Normal file
36
docs/api/memory/proxy-allocator/proxy-allocator.md
Normal file
@@ -0,0 +1,36 @@
|
||||
# ProxyAllocator::ProxyAllocator
|
||||
|
||||
```cpp
|
||||
ProxyAllocator(IAllocator* underlying, const char* name);
|
||||
```
|
||||
|
||||
构造一个代理分配器，包装底层分配器并记录分配统计。所有 `Allocate`、`Free`、`Reallocate` 调用都会被转发到底层分配器，同时记录统计信息。名称用于日志和报告。
|
||||
|
||||
**参数：**
|
||||
- `underlying` - 被包装的底层分配器，不能为 `nullptr`
|
||||
- `name` - 代理分配器的名称字符串
|
||||
|
||||
**返回：** 无
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Memory/MemoryManager.h>
|
||||
#include <XCEngine/Memory/ProxyAllocator.h>
|
||||
|
||||
MemoryManager::Get().Initialize();
|
||||
|
||||
// 使用系统分配器作为底层
|
||||
IAllocator* sysAlloc = MemoryManager::Get().GetSystemAllocator();
|
||||
ProxyAllocator proxy(sysAlloc, "TempAllocations");
|
||||
|
||||
// 通过代理分配
|
||||
void* ptr = proxy.Allocate(1024);
|
||||
proxy.Free(ptr);
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [ProxyAllocator 总览](proxy-allocator.md) - 返回类总览
|
||||
40
docs/api/memory/proxy-allocator/reallocate.md
Normal file
40
docs/api/memory/proxy-allocator/reallocate.md
Normal file
@@ -0,0 +1,40 @@
|
||||
# ProxyAllocator::Reallocate
|
||||
|
||||
```cpp
|
||||
void* Reallocate(void* ptr, size_t newSize) override;
|
||||
```
|
||||
|
||||
重新分配内存并记录统计。调用转发到底层分配器。此方法仅更新 totalAllocated 统计为新大小，不记录原内存的释放（这是简化实现）。如果底层分配失败返回 `nullptr`，但原指针仍然有效。
|
||||
|
||||
**参数：**
|
||||
- `ptr` - 现有内存块指针
|
||||
- `newSize` - 新的字节大小
|
||||
|
||||
**返回：** 成功返回新指针，失败返回 `nullptr`
|
||||
|
||||
**复杂度：** O(n)（底层分配器 + 数据复制）
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Memory/MemoryManager.h>
|
||||
#include <XCEngine/Memory/ProxyAllocator.h>
|
||||
|
||||
IAllocator* sysAlloc = MemoryManager::Get().GetSystemAllocator();
|
||||
ProxyAllocator proxy(sysAlloc, "TrackedAlloc");
|
||||
|
||||
void* p1 = proxy.Allocate(128);
|
||||
void* p2 = proxy.Reallocate(p1, 256);
|
||||
|
||||
if (p2) {
|
||||
// 重新分配成功
|
||||
const auto& stats = proxy.GetStats();
|
||||
printf("Reallocated: %zu bytes total\n", stats.totalAllocated);
|
||||
} else {
|
||||
// 失败，p1 仍然有效
|
||||
}
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [ProxyAllocator 总览](proxy-allocator.md) - 返回类总览
|
||||
Reference in New Issue
Block a user