docs : 增加模块的文档说明

This commit is contained in:
何冠峰
2026-01-06 17:12:07 +08:00
parent 539ca3523e
commit 454afc9ba6
24 changed files with 8254 additions and 0 deletions
@@ -0,0 +1,635 @@
# OperationSystem 异步操作系统
## 模块概述
OperationSystem 是 YooAsset 资源管理系统的**异步操作调度核心**,负责管理所有异步操作的生命周期、调度执行和状态追踪。该模块提供了统一的异步操作抽象,支持协程、async/await、回调等多种异步编程模式。
### 核心职责
- 异步操作的统一抽象和生命周期管理
- 基于优先级的操作调度
- 时间切片执行(防止主线程阻塞)
- 多种异步编程模式支持
- 操作状态追踪和调试信息收集
---
## 设计目标
| 目标 | 说明 |
|------|------|
| **统一抽象** | 所有异步操作继承同一基类,接口一致 |
| **灵活调度** | 支持优先级排序、时间切片、帧预算控制 |
| **多模式支持** | 协程(IEnumerator)、Task(async/await)、回调 |
| **可调试性** | 完整的状态追踪、耗时统计、层级关系 |
| **线程安全** | 所有调度逻辑在主线程执行 |
---
## 架构概念
### 系统架构
```
┌─────────────────────────────────────────────────────────┐
│ 上层调用者 │
│ (ResourceManager / FileSystem / 业务层) │
└─────────────────────────┬───────────────────────────────┘
│ StartOperation()
┌─────────────────────────▼───────────────────────────────┐
│ OperationSystem │
│ (调度器) │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ 优先级队列 │ │ 时间切片 │ │ 回调通知 │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
└─────────────────────────┬───────────────────────────────┘
│ UpdateOperation()
┌─────────────────────────▼───────────────────────────────┐
│ AsyncOperationBase │
│ (操作基类) │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ 状态机 │ │ 子任务管理 │ │ 异步模式 │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
└─────────────────────────────────────────────────────────┘
```
### 核心组件
- **OperationSystem**: 静态调度器,管理所有操作的执行
- **AsyncOperationBase**: 异步操作基类,定义生命周期和状态
- **GameAsyncOperation**: 游戏层操作基类,提供更友好的 API
- **EOperationStatus**: 操作状态枚举
---
## 文件结构
```
OperationSystem/
├── EOperationStatus.cs # 操作状态枚举
├── AsyncOperationBase.cs # 异步操作基类
├── OperationSystem.cs # 异步操作调度器
└── GameAsyncOperation.cs # 游戏层操作基类
```
---
## 枚举定义
### EOperationStatus(操作状态)
```csharp
public enum EOperationStatus
{
None, // 未开始
Processing, // 处理中
Succeed, // 已成功
Failed // 已失败
}
```
**状态转换:**
```
StartOperation() InternalUpdate()
None ─────────────────► Processing ─────────────────┬──► Succeed
│
└──► Failed
```
---
## 核心类说明
### AsyncOperationBase(异步操作基类)
所有异步操作的抽象基类,实现了 `IEnumerator` 和 `IComparable<AsyncOperationBase>` 接口。
#### 公共属性
| 属性 | 类型 | 说明 |
|------|------|------|
| `Priority` | `uint` | 任务优先级(值越大越优先) |
| `Status` | `EOperationStatus` | 当前状态 |
| `Error` | `string` | 错误信息(失败时) |
| `Progress` | `float` | 处理进度(0-1) |
| `PackageName` | `string` | 所属包裹名称 |
| `IsDone` | `bool` | 是否已完成(Succeed 或 Failed) |
| `Task` | `Task` | 用于 async/await |
| `BeginTime` | `string` | 开始时间(调试用) |
| `ProcessTime` | `long` | 处理耗时毫秒(调试用) |
#### 公共事件
```csharp
/// <summary>
/// 完成事件(支持后注册立即触发)
/// </summary>
public event Action<AsyncOperationBase> Completed;
```
#### 公共方法
```csharp
/// <summary>
/// 同步等待异步操作完成
/// </summary>
public void WaitForAsyncComplete();
```
#### 内部抽象方法(子类实现)
| 方法 | 说明 |
|------|------|
| `InternalStart()` | 操作开始时调用 |
| `InternalUpdate()` | 每帧更新时调用 |
| `InternalAbort()` | 操作中止时调用(可选) |
| `InternalWaitForAsyncComplete()` | 同步等待时调用(可选) |
| `InternalGetDesc()` | 获取操作描述(可选) |
#### 子任务管理
```csharp
// 子任务列表
internal readonly List<AsyncOperationBase> Childs;
// 添加/移除子任务
internal void AddChildOperation(AsyncOperationBase child);
internal void RemoveChildOperation(AsyncOperationBase child);
```
---
### OperationSystem(调度器)
静态类,负责异步操作的调度和管理。
#### 配置属性
```csharp
/// <summary>
/// 每帧最大执行时间(毫秒)
/// 默认值:long.MaxValue(无限制)
/// </summary>
public static long MaxTimeSlice { set; get; }
/// <summary>
/// 当前帧是否已超时
/// </summary>
public static bool IsBusy { get; }
```
#### 核心方法
```csharp
/// <summary>
/// 初始化异步操作系统
/// </summary>
public static void Initialize();
/// <summary>
/// 每帧更新(由 YooAssets 驱动)
/// </summary>
public static void Update();
/// <summary>
/// 销毁所有操作
/// </summary>
public static void DestroyAll();
/// <summary>
/// 清理指定包裹的所有操作
/// </summary>
public static void ClearPackageOperation(string packageName);
/// <summary>
/// 启动异步操作
/// </summary>
public static void StartOperation(string packageName, AsyncOperationBase operation);
```
#### 回调监听
```csharp
/// <summary>
/// 注册任务开始回调
/// </summary>
public static void RegisterStartCallback(Action<string, AsyncOperationBase> callback);
/// <summary>
/// 注册任务结束回调
/// </summary>
public static void RegisterFinishCallback(Action<string, AsyncOperationBase> callback);
```
---
### GameAsyncOperation(游戏层基类)
继承 `AsyncOperationBase`,为业务层提供更友好的 API。
```csharp
public abstract class GameAsyncOperation : AsyncOperationBase
{
/// <summary>
/// 异步操作开始
/// </summary>
protected abstract void OnStart();
/// <summary>
/// 异步操作更新
/// </summary>
protected abstract void OnUpdate();
/// <summary>
/// 异步操作终止
/// </summary>
protected abstract void OnAbort();
/// <summary>
/// 异步等待完成(可选重写)
/// </summary>
protected virtual void OnWaitForAsyncComplete();
/// <summary>
/// 异步操作系统是否繁忙
/// </summary>
protected bool IsBusy();
/// <summary>
/// 终止异步操作
/// </summary>
protected void Abort();
}
```
---
## 异步编程模式
### 1. 协程模式(IEnumerator)
```csharp
IEnumerator LoadAsset()
{
var operation = package.LoadAssetAsync<GameObject>("Assets/Prefab.prefab");
yield return operation;
if (operation.Status == EOperationStatus.Succeed)
{
GameObject prefab = operation.AssetObject as GameObject;
}
}
```
### 2. Task 模式(async/await)
```csharp
async Task LoadAssetAsync()
{
var operation = package.LoadAssetAsync<GameObject>("Assets/Prefab.prefab");
await operation.Task;
if (operation.Status == EOperationStatus.Succeed)
{
GameObject prefab = operation.AssetObject as GameObject;
}
}
```
### 3. 回调模式(Completed 事件)
```csharp
void LoadAsset()
{
var operation = package.LoadAssetAsync<GameObject>("Assets/Prefab.prefab");
operation.Completed += OnLoadCompleted;
}
void OnLoadCompleted(AsyncOperationBase op)
{
var operation = op as AssetHandle;
if (operation.Status == EOperationStatus.Succeed)
{
GameObject prefab = operation.AssetObject as GameObject;
}
}
```
### 4. 同步等待模式
```csharp
void LoadAssetSync()
{
var operation = package.LoadAssetAsync<GameObject>("Assets/Prefab.prefab");
operation.WaitForAsyncComplete(); // 阻塞等待完成
if (operation.Status == EOperationStatus.Succeed)
{
GameObject prefab = operation.AssetObject as GameObject;
}
}
```
---
## 调度机制
### 优先级调度
操作按 `Priority` 属性降序排列,优先级高的操作先执行。
```csharp
var operation = package.LoadAssetAsync<GameObject>(location);
operation.Priority = 100; // 设置高优先级
```
**排序规则:**
- 新操作添加时检查是否需要排序
- 仅当存在非零优先级时触发排序
- 使用 `List.Sort()` 进行原地排序
### 时间切片
通过 `MaxTimeSlice` 控制每帧最大执行时间,防止主线程阻塞。
```csharp
// 设置每帧最多执行 8 毫秒
OperationSystem.MaxTimeSlice = 8;
```
**执行流程:**
```
每帧 Update()
│
├── 记录帧开始时间 _frameTime
│
└── 遍历操作队列
│
├── 检查 IsBusy(是否超时)
│ │
│ └── 超时则中断本帧
│
└── 执行 operation.UpdateOperation()
```
### 操作生命周期
```
┌─────────────────────────────────────────────────────────────────┐
│ 操作生命周期 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ 1. 创建操作 │
│ └── Status = None │
│ │
│ 2. StartOperation() │
│ ├── Status = Processing │
│ ├── DebugBeginRecording() │
│ ├── InternalStart() │
│ └── 添加到 _newList │
│ │
│ 3. Update() - 每帧调度 │
│ ├── 移除已完成操作 │
│ ├── 合并 _newList 到 _operations │
│ ├── 按优先级排序(如需要) │
│ └── 遍历执行 UpdateOperation() │
│ │
│ 4. UpdateOperation() │
│ ├── DebugUpdateRecording() │
│ ├── InternalUpdate() │
│ └── 检查 IsDone │
│ │ │
│ └── 完成时: │
│ ├── IsFinish = true │
│ ├── Progress = 1f │
│ ├── DebugEndRecording() │
│ ├── 触发 Completed 回调 │
│ └── 设置 TaskCompletionSource │
│ │
│ 5. 下一帧移除完成的操作 │
│ │
└─────────────────────────────────────────────────────────────────┘
```
---
## 调试支持
### 调试信息结构
```csharp
internal struct DebugOperationInfo
{
public string OperationName; // 操作类型名
public string OperationDesc; // 操作描述
public uint Priority; // 优先级
public float Progress; // 进度
public string BeginTime; // 开始时间
public long ProcessTime; // 处理耗时(毫秒)
public string Status; // 状态
public List<DebugOperationInfo> Childs; // 子操作
}
```
### 获取调试信息
```csharp
// 获取指定包裹的所有操作信息
var infos = OperationSystem.GetDebugOperationInfos("DefaultPackage");
foreach (var info in infos)
{
Debug.Log($"{info.OperationName}: {info.Status}, {info.ProcessTime}ms");
}
```
### 耗时统计
在 DEBUG 模式下自动统计操作耗时:
```csharp
// 操作完成后可获取耗时
Debug.Log($"开始时间: {operation.BeginTime}");
Debug.Log($"处理耗时: {operation.ProcessTime}ms");
```
---
## 使用示例
### 自定义异步操作
```csharp
public class MyCustomOperation : GameAsyncOperation
{
private int _step = 0;
protected override void OnStart()
{
// 初始化操作
_step = 0;
}
protected override void OnUpdate()
{
// 检查系统是否繁忙(时间切片)
if (IsBusy())
return;
// 执行步骤
switch (_step)
{
case 0:
// 第一步
Progress = 0.3f;
_step = 1;
break;
case 1:
// 第二步
Progress = 0.6f;
_step = 2;
break;
case 2:
// 完成
Status = EOperationStatus.Succeed;
break;
}
}
protected override void OnAbort()
{
// 清理资源
}
}
```
### 启动自定义操作
```csharp
var operation = new MyCustomOperation();
OperationSystem.StartOperation("DefaultPackage", operation);
// 使用回调
operation.Completed += (op) =>
{
if (op.Status == EOperationStatus.Succeed)
Debug.Log("操作成功");
};
// 或使用 await
await operation.Task;
```
### 带子任务的操作
```csharp
public class ParentOperation : GameAsyncOperation
{
private ChildOperation _child;
protected override void OnStart()
{
_child = new ChildOperation();
AddChildOperation(_child); // 添加子任务
OperationSystem.StartOperation(PackageName, _child);
}
protected override void OnUpdate()
{
if (_child.IsDone)
{
if (_child.Status == EOperationStatus.Succeed)
Status = EOperationStatus.Succeed;
else
Status = EOperationStatus.Failed;
}
}
protected override void OnAbort()
{
// 子任务会自动中止
}
}
```
---
## 设计模式
### 模板方法模式
`AsyncOperationBase` 定义算法骨架,子类实现具体步骤:
```
AsyncOperationBase
│
├── StartOperation() ──► InternalStart() [子类实现]
├── UpdateOperation() ──► InternalUpdate() [子类实现]
├── AbortOperation() ──► InternalAbort() [子类实现]
└── WaitForAsyncComplete() ──► InternalWaitForAsyncComplete() [子类实现]
```
### 状态机模式
操作状态由 `EOperationStatus` 管理:
```
┌──────┐ StartOperation() ┌────────────┐ UpdateOperation() ┌─────────┐
│ None │ ─────────────────► │ Processing │ ──────────────────► │ Succeed │
└──────┘ └────────────┘ └─────────┘
│
│ UpdateOperation() / AbortOperation()
▼
┌──────────┐
│ Failed │
└──────────┘
```
### 组合模式
通过 `Childs` 列表支持父子操作关系:
```
ParentOperation
├── ChildOperation1
├── ChildOperation2
└── ChildOperation3
└── GrandChildOperation
```
---
## 类继承关系
```
IEnumerator + IComparable<AsyncOperationBase>
│
▼
AsyncOperationBase (抽象基类)
│
├── GameAsyncOperation (游戏层基类)
│ │
│ └── [业务层自定义操作]
│
└── [YooAsset 内部操作]
│
├── InitializationOperation
├── LoadAssetOperation
├── LoadSceneOperation
├── DownloadOperation
└── ...
```
---
## 注意事项
1. **主线程执行**:所有操作的调度和更新都在 Unity 主线程执行
2. **时间切片**:设置合理的 `MaxTimeSlice` 避免卡顿(建议 8-16ms)
3. **同步等待**:`WaitForAsyncComplete()` 会阻塞主线程,谨慎使用
4. **子任务中止**:父操作中止时会自动中止所有子操作
5. **回调异常**:`Completed` 回调中的异常会被捕获并记录,不会中断系统
6. **编辑器重置**:编辑器中使用 `RuntimeInitializeOnLoadMethod` 自动重置状态
7. **循环保护**:`WaitForAsyncComplete()` 有 1000 帧上限,防止无限循环
@@ -0,0 +1,7 @@
fileFormatVersion: 2
guid: 2afe3d5ffb611b241919112b40d9c7d0
TextScriptImporter:
externalObjects: {}
userData:
assetBundleName:
assetBundleVariant: