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

# Threading

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

**类型**: `module`

**描述**: 提供线程封装、基础同步原语和一套早期任务系统骨架。

## 概述

`XCEngine::Threading` 当前由两部分组成：

- `Mutex`、`SpinLock`、`ReadWriteLock` 和 `Thread` 这类直接可用的并发基础设施。
- `ITask`、`TaskGroup`、`TaskSystem` 这类面向 job system 的任务抽象。

这种分层很符合商业引擎常见做法：底层仍然需要明确的锁和线程封装，上层再逐步演进到任务图、主线程回调和并行 for 之类的调度模型。

## 当前实现成熟度

这一组 API 的成熟度差异很大，需要分开看：

- `Mutex` 与 `SpinLock` 本质上是对标准库原语的薄封装，语义相对直接。
- `ReadWriteLock` 实现了写者优先的读写锁，但没有 try-lock、升级/降级或 RAII 辅助类型。
- `Thread` 可以封装 `std::thread` 生命周期，但线程名称只是本地字符串，不会设置 OS 线程名，而且 ID 口径与 `GetCurrentId()` 不一致。
- `ITask` 与 `LambdaTask` 的抽象形状已经具备，但 `TaskGroup` 和 `TaskSystem` 目前仍然明显属于“骨架阶段”。
- `TaskSystem` 当前存在严重的生命周期和同步问题，因此不能把它当成商用级 job system 使用。

## 设计要点

- 大写接口如 `Lock()` / `Unlock()` 更接近引擎自身命名风格。
- 小写接口如 `lock()` / `unlock()` / `try_lock()` 的存在，是为了兼容 `std::lock_guard` 这类标准 Lockable 习惯用法。
- `ITask` 采用侵入式引用计数，说明这套任务系统原本是朝“跨线程提交和自动释放任务对象”这个方向设计的。

## 测试覆盖现状

当前测试只覆盖了：

- `Mutex`
- `SpinLock`
- `ITask` / `LambdaTask` 的最基础行为

`ReadWriteLock`、`Thread`、`TaskGroup` 和 `TaskSystem` 当前没有看到对应单测，因此相关文档会更强调源码现状和风险边界。

## 头文件

- [LambdaTask](LambdaTask/LambdaTask.md) - `LambdaTask.h`
- [Mutex](Mutex/Mutex.md) - `Mutex.h`
- [ReadWriteLock](ReadWriteLock/ReadWriteLock.md) - `ReadWriteLock.h`
- [SpinLock](SpinLock/SpinLock.md) - `SpinLock.h`
- [Task](Task/Task.md) - `Task.h`
- [TaskGroup](TaskGroup/TaskGroup.md) - `TaskGroup.h`
- [TaskSystem](TaskSystem/TaskSystem.md) - `TaskSystem.h`
- [TaskSystemConfig](TaskSystemConfig/TaskSystemConfig.md) - `TaskSystemConfig.h`
- [Thread](Thread/Thread.md) - `Thread.h`
- [Threading](Threading/Threading.md) - `Threading.h`

## 相关指南

- [Synchronization And Task System Limits](../../_guides/Threading/Synchronization-And-TaskSystem-Limits.md) - 解释为什么引擎要同时保留锁、线程和任务系统抽象，以及当前实现距离商业级 job system 还差哪些关键能力。

## 相关文档

- [上级目录](../XCEngine.md)
- [API 总索引](../../main.md)