# TaskSystem

**命名空间**: `XCEngine::Threading`

**类型**: `class (singleton)`

**头文件**: `XCEngine/Threading/TaskSystem.h`

**描述**: 提供全局任务调度入口、工作线程池、主线程回调队列以及任务组创建接口。

## 概述

`TaskSystem` 想解决的是“把零散后台工作统一交给一套中央调度器管理”这个问题。它当前暴露的 API 形状已经覆盖了商用引擎任务系统常见的几个入口：

- 单例式全局访问。
- 工作线程池初始化与关闭。
- 按优先级提交任务。
- 批量任务入口 `ParallelFor()`。
- 任务组创建与销毁。
- 回投主线程的回调队列。

这种设计方向本身是对的。商业级引擎很少要求上层系统自己手搓 `std::thread`，而是倾向于通过中央 job system 统一调度、限流、统计和同步。

## 当前实现边界

当前 `TaskSystem` 仍然明显处于原型阶段，尤其要注意以下事实：

- [Submit](Submit.md) 当前存在严重生命周期问题: 任务指针被压入队列后，对应 `unique_ptr` 却会在函数返回时销毁对象，导致队列中留下悬空指针。
- 工作线程取任务时，`GetNextTask()` 访问 `m_taskQueue` 没有使用与入队一致的 `m_queueMutex`，当前存在未同步并发访问。
- [Wait](Wait.md) 还是空实现。
- [ParallelFor](ParallelFor.md) 会立即返回，不会等待所有分片完成。
- [Initialize](Initialize.md) 只真正使用了 `TaskSystemConfig::workerThreadCount`，其余配置项当前都被忽略。
- [Shutdown](Shutdown.md) 之后 `m_shutdown` 不会恢复为 `false`，重新初始化路径当前基本不可用。
- [TaskGroup](../TaskGroup/TaskGroup.md) 创建出来后，只是被登记到列表里，并没有接入任务执行与完成统计。

因此，当前 `TaskSystem` 不应被当成商业级 job system 使用。更准确的定位是: API 轮廓已经出现，但核心正确性还没有收敛。

## 公开方法

| 方法 | 说明 |
|------|------|
| [Get](Get.md) | 取得全局单例实例。 |
| [Initialize](Initialize.md) | 初始化工作线程池。 |
| [Shutdown](Shutdown.md) | 停止工作线程并关闭系统。 |
| [Submit](Submit.md) | 提交一个任务对象或 lambda。 |
| [CreateTaskGroup](CreateTaskGroup.md) | 创建任务组。 |
| [DestroyTaskGroup](DestroyTaskGroup.md) | 销毁任务组。 |
| [Wait](Wait.md) | 等待指定任务完成。 |
| [GetWorkerThreadCount](GetWorkerThreadCount.md) | 查询当前配置的工作线程数。 |
| [Update](Update.md) | 执行主线程回调队列。 |
| [ParallelFor](ParallelFor.md) | 把区间拆成多个高优先级任务提交。 |
| [RunOnMainThread](RunOnMainThread.md) | 把回调排入主线程队列。 |

## 设计说明

为什么引擎仍然需要这样的中心化系统，而不是到处直接开线程：

- 线程数量需要统一治理，否则很容易过量创建后台线程。
- 优先级、主线程回投、profiling 和依赖图等能力，通常都需要一个公共调度中心。
- 资源加载、脚本预处理、导航构建、烘焙和编辑器后台任务，往往都需要共享同一套任务基础设施。

这也是为什么很多商业引擎会把“线程原语”和“任务系统”都保留下来:

- 锁和线程解决底层同步与平台适配问题。
- 任务系统解决更高层的批处理、吞吐量和生命周期协调问题。

## 使用建议

- 当前源码中，低层同步原语比 `TaskSystem` 更成熟。
- 如果确实要继续推进这个模块，优先修正任务所有权、队列同步、等待语义和关闭语义，再谈 profiling、work stealing 或任务依赖图。

## 相关文档

- [当前模块](../Threading.md)
- [TaskSystemConfig](../TaskSystemConfig/TaskSystemConfig.md)
- [TaskGroup](../TaskGroup/TaskGroup.md)
- [Synchronization And Task System Limits](../../../_guides/Threading/Synchronization-And-TaskSystem-Limits.md)