XCEngine/docs/api/resources/asyncloader/asyncloader.md

# 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](../resourcemanager/resourcemanager.md) - 资源管理器
- [IResourceLoader](../iloader/iloader.md) - 资源加载器接口
- [Resources 总览](../resources.md) - 返回模块总览