XCEngine/docs/api/XCEngine/Threading/TaskGroup/TaskGroup.md

# TaskGroup

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

**类型**: `class`

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

**描述**: 表示一组带依赖关系的任务集合，目标是为任务批次提供等待、进度查询和完成回调入口。

## 概述

`TaskGroup` 体现的是商业引擎里很常见的一个设计方向: 把一批相关任务组织成一个“组”，然后围绕这批任务暴露：

- 批量添加任务。
- 任务之间的依赖关系。
- 整组完成等待。
- 整组完成回调。
- 进度查询与取消。

这种抽象本身是合理的。像 Unity 的 job fence、Unreal 的 task graph event，以及很多自研引擎里的 batch/fence/group 概念，本质上都在解决同一个问题: 上层系统往往关心“一批工作什么时候整体完成”，而不是只关心单个任务对象。

## 当前实现边界

当前 `TaskGroup` 还停留在骨架阶段，文档必须按源码现实理解：

- [AddTask](AddTask.md) 会把 `std::unique_ptr<ITask>` 释放成裸指针保存，但析构函数是默认实现，当前不会回收这些任务对象。
- [AddDependency](AddDependency.md) 只记录依赖 ID，不会更新 `pendingDepCount`，也没有真正接入调度流程。
- [Wait](Wait.md) 和 [WaitFor](WaitFor.md) 依赖 `m_pendingCount == 0`，但当前代码里这个计数只增不减。
- [GetProgress](GetProgress.md) 依赖 `m_completedCount`，但当前没有任何路径会递增它。
- [SetCompleteCallback](SetCompleteCallback.md) 只是保存回调，当前不会触发。
- [Cancel](Cancel.md) 只会调用 `OnCancel()`，不会让任务组进入“已完成”状态，也不会唤醒等待者。
- 当前 `TaskGroup` 和 [TaskSystem](../TaskSystem/TaskSystem.md) 之间没有形成真正的组调度联动。

因此，当前源码中的 `TaskGroup` 更像“未来任务图系统的接口草图”，而不是已经可依赖的完成态任务栅栏。

## 公开方法

| 方法 | 说明 |
|------|------|
| [Constructor](Constructor.md) | 构造一个空任务组。 |
| [Destructor](Destructor.md) | 销毁任务组对象。 |
| [AddTask](AddTask.md) | 向任务组添加一个任务或 lambda。 |
| [AddDependency](AddDependency.md) | 为任务记录依赖关系。 |
| [Wait](Wait.md) | 阻塞等待任务组完成。 |
| [WaitFor](WaitFor.md) | 限时等待任务组完成。 |
| [SetCompleteCallback](SetCompleteCallback.md) | 设置完成回调。 |
| [IsComplete](IsComplete.md) | 查询任务组是否完成。 |
| [GetProgress](GetProgress.md) | 查询完成进度。 |
| [Cancel](Cancel.md) | 取消任务组中的未完成任务。 |

## 使用建议

- 如果你现在需要稳定的并发基础设施，优先使用 [Mutex](../Mutex/Mutex.md)、[SpinLock](../SpinLock/SpinLock.md)、[ReadWriteLock](../ReadWriteLock/ReadWriteLock.md) 和 [Thread](../Thread/Thread.md)。
- 当前不要把 `TaskGroup` 当成可用的 task fence 或 job dependency graph。
- 如果后续要把它做成商用级任务组，至少需要补齐任务所有权、依赖计数、完成通知和 `TaskSystem` 集成。

## 相关文档

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