122 lines
4.5 KiB
Markdown
122 lines
4.5 KiB
Markdown
# AsyncLoader
|
||
|
||
**命名空间**: `XCEngine::Resources`
|
||
|
||
**类型**: `class` (singleton)
|
||
|
||
**头文件**: `XCEngine/Resources/AsyncLoader.h`
|
||
|
||
**描述**: 异步资源加载器单例，负责多线程后台资源加载和完成回调调度。
|
||
|
||
## 概述
|
||
|
||
`AsyncLoader` 是 XCEngine 的后台异步加载系统。它使用独立工作线程从磁盘加载资源，并在加载完成后通过回调通知调用者。它维护待处理队列和完成队列，通过双缓冲机制实现无锁的线程安全操作。
|
||
|
||
## 单例访问
|
||
|
||
| 方法 | 描述 |
|
||
|------|------|
|
||
| `static AsyncLoader& Get()` | 获取单例实例 |
|
||
|
||
## LoadRequest 结构体
|
||
|
||
异步加载请求结构体。
|
||
|
||
| 成员 | 类型 | 描述 |
|
||
|------|------|------|
|
||
| `path` | `Containers::String` | 资源路径 |
|
||
| `type` | `ResourceType` | 资源类型 |
|
||
| `callback` | `std::function<void(LoadResult)>` | 加载完成回调函数 |
|
||
| `settings` | `ImportSettings*` | 导入设置（可为 nullptr） |
|
||
| `requestId` | `Core::uint64` | 请求唯一标识符 |
|
||
|
||
### 构造方法
|
||
|
||
| 方法 | 描述 |
|
||
|------|------|
|
||
| `LoadRequest()` | 默认构造 |
|
||
| `LoadRequest(const Containers::String& p, ResourceType t, std::function<void(LoadResult)> cb, ImportSettings* s = nullptr)` | 从参数构造 |
|
||
| `LoadRequest(LoadRequest&& other) noexcept` | 移动构造 |
|
||
| `LoadRequest(const LoadRequest&) = default` | 拷贝构造 |
|
||
|
||
### 赋值
|
||
|
||
| 方法 | 描述 |
|
||
|------|------|
|
||
| `LoadRequest& operator=(LoadRequest&& other) noexcept` | 移动赋值 |
|
||
| `LoadRequest& operator=(const LoadRequest&) = default` | 拷贝赋值 |
|
||
|
||
## 公共方法
|
||
|
||
| 方法 | 描述 |
|
||
|------|------|
|
||
| `void Initialize(Core::uint32 workerThreadCount = 2)` | 初始化异步加载器，创建工作线程 |
|
||
| `void Shutdown()` | 关闭异步加载器，等待所有挂起任务完成 |
|
||
| `void Submit(const Containers::String& path, ResourceType type, std::function<void(LoadResult)> callback)` | 提交异步加载请求 |
|
||
| `void Submit(const Containers::String& path, ResourceType type, ImportSettings* settings, std::function<void(LoadResult)> callback)` | 带设置的异步加载请求 |
|
||
| `void Update()` | 更新函数，在主线程调用，处理完成的加载请求 |
|
||
| `bool IsLoading() const` | 是否有正在加载的资源 |
|
||
| `Core::uint32 GetPendingCount() const` | 获取待处理加载请求数量 |
|
||
| `float GetProgress() const` | 获取整体加载进度（0.0f ~ 1.0f） |
|
||
| `void CancelAll()` | 取消所有待处理的加载请求 |
|
||
| `void Cancel(Core::uint64 requestId)` | 取消指定 ID 的加载请求 |
|
||
|
||
### 方法详情
|
||
|
||
- [Initialize](initialize.md) - 初始化异步加载器
|
||
- [Shutdown](shutdown.md) - 关闭异步加载器
|
||
- [Submit](submit.md) - 提交异步加载请求
|
||
- [Update](update.md) - 更新函数，处理完成的加载请求
|
||
- [IsLoading](isloading.md) - 检查是否有正在加载的资源
|
||
- [GetPendingCount](getpendingcount.md) - 获取待处理加载请求数量
|
||
- [GetProgress](getprogress.md) - 获取整体加载进度
|
||
- [CancelAll](cancelall.md) - 取消所有待处理的加载请求
|
||
- [Cancel](cancel.md) - 取消指定 ID 的加载请求
|
||
|
||
## 实现说明
|
||
|
||
**注意**: 当前 `AsyncLoader` 的实现为部分完成状态（stub）：
|
||
- `Initialize()` 工作线程数参数被忽略
|
||
- `Submit()` 仅将请求加入队列，不进行实际异步加载
|
||
- `Update()` 不执行实际加载，直接调用回调返回成功
|
||
- `Cancel()` 为空实现
|
||
|
||
## 使用示例
|
||
|
||
```cpp
|
||
// 初始化（使用 4 个工作线程）
|
||
AsyncLoader::Get().Initialize(4);
|
||
|
||
// 提交多个异步加载请求
|
||
AsyncLoader::Get().Submit("textures/player.png", ResourceType::Texture,
|
||
[](LoadResult result) {
|
||
if (result.success) {
|
||
ResourceHandle<Texture> tex(result.resource);
|
||
printf("Texture loaded: %s\n", tex->GetPath().CStr());
|
||
}
|
||
});
|
||
|
||
AsyncLoader::Get().Submit("models/player.fbx", ResourceType::Mesh,
|
||
[](LoadResult result) {
|
||
if (result.success) {
|
||
ResourceHandle<Mesh> mesh(result.resource);
|
||
printf("Mesh loaded: %s\n", mesh->GetPath().CStr());
|
||
}
|
||
});
|
||
|
||
// 在主循环中调用 Update 处理完成回调
|
||
while (AsyncLoader::Get().IsLoading()) {
|
||
AsyncLoader::Get().Update(); // 在主线程分发回调
|
||
// 其他渲染逻辑...
|
||
}
|
||
|
||
// 关闭
|
||
AsyncLoader::Get().Shutdown();
|
||
```
|
||
|
||
## 相关文档
|
||
|
||
- [ResourceManager](../resource-manager/resource-manager.md) - 资源管理器
|
||
- [IResourceLoader](../iloader/iloader.md) - 资源加载器接口
|
||
- [Resources 总览](../resources.md) - 返回模块总览
|