XCEngine/docs/api/XCEngine/Threading/Task/Task.md

# ITask

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

**类型**: `class (abstract interface)` + `enum class`

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

**描述**: 定义任务优先级、任务状态以及带侵入式引用计数的抽象任务基类 `ITask`。

## 概述

`Task.h` 暴露了三类核心概念：

- `TaskPriority`：任务优先级枚举。
- `TaskStatus`：任务状态枚举。
- `ITask`：任务执行、完成回调、取消回调和引用计数的统一基类。

这种设计很像很多商业引擎早期 job system 的起点：先用一个稳定任务抽象把“执行单元”统一起来，再围绕它搭调度器、主线程回调和任务组。

## 枚举

### `TaskPriority`

当前优先级从高到低依次是：

- `Critical`
- `High`
- `Normal`
- `Low`
- `Idle`

### `TaskStatus`

当前状态包括：

- `Pending`
- `Scheduled`
- `Running`
- `Completed`
- `Failed`
- `Canceled`

## 当前实现边界

- `ITask` 采用侵入式引用计数；`Release()` 在计数归零时直接 `delete this`，因此这套生命周期默认假设任务对象位于堆上。
- `m_status` 是原子值，但 `m_priority` 和 `m_id` 不是。
- 当前 `TaskSystem` 并没有完整使用这套状态机，例如提交时不会自动写入 `Scheduled`。

## 公开方法

| 方法 | 说明 |
|------|------|
| [Destructor](Destructor.md) | 虚析构函数。 |
| [Execute](Execute.md) | 执行任务主体。 |
| [OnComplete](OnComplete.md) | 完成回调。 |
| [OnCancel](OnCancel.md) | 取消回调。 |
| [GetPriority](GetPriority.md) | 读取优先级。 |
| [GetStatus](GetStatus.md) | 读取状态。 |
| [GetId](GetId.md) | 读取任务 ID。 |
| [SetId](SetId.md) | 设置任务 ID。 |
| [SetPriority](SetPriority.md) | 设置优先级。 |
| [SetStatus](SetStatus.md) | 设置状态。 |
| [AddRef](AddRef.md) | 增加引用计数。 |
| [Release](Release.md) | 释放引用。 |

## 已知实现

- [LambdaTask](../LambdaTask/LambdaTask.md)

## 相关文档

- [当前模块](../Threading.md)
- [TaskSystem](../TaskSystem/TaskSystem.md)