xuanchi/XCEngine
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: rebuild Threading API content

Browse Source
This commit is contained in:
ssdfasd
2026-03-26 20:59:59 +08:00
parent 9a2d77b81d
commit 8f486611d5
78 changed files with 1648 additions and 1061 deletions
Download Patch File Download Diff File Expand all files Collapse all files

26
docs/api/XCEngine/Threading/Thread/Constructor.md
View File

@@ -1,28 +1,24 @@
# Thread::Thread()
# Thread::Constructor
构造对象。
构造一个空线程包装对象。
```cpp
Thread();
```
该方法声明于 `XCEngine/Threading/Thread.h`，当前页面用于固定 `Thread` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：** 无。
当前实现是默认构造，不会启动线程。初始状态下：
**返回：** `void` - 无返回值。
- `m_id == 0`
- `m_name` 为空
- `m_thread` 不可 join
**示例：**
## 返回值
```cpp
#include <XCEngine/Threading/Thread.h>
void Example() {
XCEngine::Threading::Thread object;
}
```
- 无。
## 相关文档
- [返回类总览](Thread.md)
- [返回模块目录](../Threading.md)
- [返回类型总览](Thread.md)
- [Start](Start.md)

27
docs/api/XCEngine/Threading/Thread/Destructor.md
View File

@@ -1,29 +1,26 @@
# Thread::~Thread()
# Thread::Destructor
销毁对象并释放相关资源。
销毁线程包装对象。
```cpp
~Thread();
```
该方法声明于 `XCEngine/Threading/Thread.h`，当前页面用于固定 `Thread` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：** 无。
当前实现会在 `m_thread.joinable()` 时自动调用 `m_thread.join()`。
**返回：** `void` - 无返回值。
## 返回值
**示例：**
- 无。
```cpp
#include <XCEngine/Threading/Thread.h>
## 注意事项
void Example() {
XCEngine::Threading::Thread object;
// 对象离开作用域时会自动触发析构。
}
```
- 这意味着析构可能阻塞直到线程函数结束。
- 如果你希望线程独立运行而不在析构时阻塞，应先显式调用 [Detach](Detach.md)。
## 相关文档
- [返回类总览](Thread.md)
- [返回模块目录](../Threading.md)
- [返回类型总览](Thread.md)
- [Join](Join.md)
- [Detach](Detach.md)

24
docs/api/XCEngine/Threading/Thread/Detach.md
View File

@@ -1,30 +1,24 @@
# Thread::Detach
公开方法，详见头文件声明。
分离线程。
```cpp
void Detach();
```
该方法声明于 `XCEngine/Threading/Thread.h`，当前页面用于固定 `Thread` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：** 无。
当前实现会在 `m_thread.joinable()` 时调用 `m_thread.detach()`；否则什么也不做。
**返回：** `void` - 无返回值。
## 返回值
**示例：**
- 无。
```cpp
#include <XCEngine/Threading/Thread.h>
## 注意事项
void Example() {
XCEngine::Threading::Thread object;
// 根据上下文补齐参数后调用 Thread::Detach(...)。
(void)object;
}
```
- 一旦分离，线程执行与 `Thread` 对象生命周期脱钩，之后析构不会再 `Join()` 这条线程。
## 相关文档
- [返回类总览](Thread.md)
- [返回模块目录](../Threading.md)
- [返回类型总览](Thread.md)
- [Join](Join.md)

28
docs/api/XCEngine/Threading/Thread/GetCurrentId.md
View File

@@ -1,30 +1,28 @@
# Thread::GetCurrentId
获取相关状态或对象。
获取当前线程标识。
```cpp
static Id GetCurrentId();
```
该方法声明于 `XCEngine/Threading/Thread.h`，当前页面用于固定 `Thread` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：** 无。
当前实现会：
**返回：** `Id` - 返回值语义详见头文件声明。
1. 获取 `std::this_thread::get_id()`
2. 通过 `std::hash<std::thread::id>` 求 hash
3. 把结果转成 `Id`
**示例：**
## 返回值
```cpp
#include <XCEngine/Threading/Thread.h>
- `Id` - 当前线程的 hash 化标识值。
void Example() {
XCEngine::Threading::Thread object;
// 根据上下文补齐参数后调用 Thread::GetCurrentId(...)。
(void)object;
}
```
## 注意事项
- 这个值不是 [GetId](GetId.md) 所用的 `native_handle()` 转换结果，因此两者不是统一编码。
## 相关文档
- [返回类总览](Thread.md)
- [返回模块目录](../Threading.md)
- [返回类型总览](Thread.md)
- [GetId](GetId.md)

26
docs/api/XCEngine/Threading/Thread/GetId.md
View File

@@ -1,30 +1,26 @@
# Thread::GetId
获取相关状态或对象。
获取缓存的线程标识。
```cpp
Id GetId() const;
```
该方法声明于 `XCEngine/Threading/Thread.h`，当前页面用于固定 `Thread` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：** 无。
当前头文件内联实现直接返回 `m_id`。
**返回：** `Id` - 返回值语义详见头文件声明。
这个值只在 [Start](Start.md) 里更新，来源是 `native_handle()` 转成整数。
**示例：**
## 返回值
```cpp
#include <XCEngine/Threading/Thread.h>
- `Id` - 当前缓存的线程标识；尚未启动时通常为 `0`。
void Example() {
XCEngine::Threading::Thread object;
// 根据上下文补齐参数后调用 Thread::GetId(...)。
(void)object;
}
```
## 注意事项
- 这个值与 [GetCurrentId](GetCurrentId.md) 的实现口径不同，不应假设两者可以直接比较。
## 相关文档
- [返回类总览](Thread.md)
- [返回模块目录](../Threading.md)
- [返回类型总览](Thread.md)
- [GetCurrentId](GetCurrentId.md)

24
docs/api/XCEngine/Threading/Thread/GetName.md
View File

@@ -1,30 +1,24 @@
# Thread::GetName
获取相关状态或对象。
获取保存的线程名称。
```cpp
const Containers::String& GetName() const;
```
该方法声明于 `XCEngine/Threading/Thread.h`，当前页面用于固定 `Thread` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：** 无。
当前头文件内联实现直接返回 `m_name` 的常量引用。
**返回：** `const Containers::String&` - 返回值语义详见头文件声明。
## 返回值
**示例：**
- `const Containers::String&` - 由 [Start](Start.md) 保存下来的线程名称。
```cpp
#include <XCEngine/Threading/Thread.h>
## 注意事项
void Example() {
XCEngine::Threading::Thread object;
// 根据上下文补齐参数后调用 Thread::GetName(...)。
(void)object;
}
```
- 这只是 `Thread` 对象内部保存的名称字符串，不代表 OS 级线程名一定被设置。
## 相关文档
- [返回类总览](Thread.md)
- [返回模块目录](../Threading.md)
- [返回类型总览](Thread.md)
- [Start](Start.md)

24
docs/api/XCEngine/Threading/Thread/Join.md
View File

@@ -1,30 +1,20 @@
# Thread::Join
公开方法，详见头文件声明。
等待线程结束。
```cpp
void Join();
```
该方法声明于 `XCEngine/Threading/Thread.h`，当前页面用于固定 `Thread` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：** 无。
当前实现会在 `m_thread.joinable()` 时调用 `m_thread.join()`；否则什么也不做。
**返回：** `void` - 无返回值。
## 返回值
**示例：**
```cpp
#include <XCEngine/Threading/Thread.h>
void Example() {
XCEngine::Threading::Thread object;
// 根据上下文补齐参数后调用 Thread::Join(...)。
(void)object;
}
```
- 无。
## 相关文档
- [返回类总览](Thread.md)
- [返回模块目录](../Threading.md)
- [返回类型总览](Thread.md)
- [Detach](Detach.md)

31
docs/api/XCEngine/Threading/Thread/Sleep.md
View File

@@ -1,31 +1,28 @@
# Thread::Sleep
公开方法，详见头文件声明。
让当前线程休眠指定毫秒数。
```cpp
static void Sleep(uint32_t milliseconds);
```
该方法声明于 `XCEngine/Threading/Thread.h`，当前页面用于固定 `Thread` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：**
- `milliseconds` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。
**示例：**
当前实现直接调用：
```cpp
#include <XCEngine/Threading/Thread.h>
void Example() {
XCEngine::Threading::Thread object;
// 根据上下文补齐参数后调用 Thread::Sleep(...)。
(void)object;
}
std::this_thread::sleep_for(std::chrono::milliseconds(milliseconds));
```
## 参数
- `milliseconds` - 休眠时长，单位毫秒。
## 返回值
- 无。
## 相关文档
- [返回类总览](Thread.md)
- [返回模块目录](../Threading.md)
- [返回类型总览](Thread.md)
- [Yield](Yield.md)

40
docs/api/XCEngine/Threading/Thread/Start.md
View File

@@ -1,32 +1,36 @@
# Thread::Start
公开方法，详见头文件声明。
启动一个新线程。
```cpp
template<typename Func> void Start(Func&& func, const Containers::String& name = "Thread");
template<typename Func>
void Start(Func&& func, const Containers::String& name = "Thread");
```
该方法声明于 `XCEngine/Threading/Thread.h`，当前页面用于固定 `Thread` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：**
- `func` - 参数语义详见头文件声明。
- `name` - 参数语义详见头文件声明。
当前模板实现会：
**返回：** `template<typename Func> void` - 返回值语义详见头文件声明。
1. 把 `m_name = name`
2. 执行 `m_thread = std::thread(std::forward<Func>(func))`
3. 把 `m_thread.native_handle()` 转成整数，写入 `m_id`
**示例：**
## 参数
```cpp
#include <XCEngine/Threading/Thread.h>
- `func` - 线程入口函数或可调用对象。
- `name` - 保存在线程包装对象中的名称；默认值为 `"Thread"`。
void Example() {
XCEngine::Threading::Thread object;
// 根据上下文补齐参数后调用 Thread::Start(...)。
(void)object;
}
```
## 返回值
- 无。
## 当前实现限制
- 名称只保存在 `m_name`，不会设置到操作系统线程名。
- `m_id` 是从 `native_handle()` 转换而来的缓存值，不保证跨平台可移植，也不保证与 [GetCurrentId](GetCurrentId.md) 一致。
- 如果对一个仍然 `joinable` 的线程对象再次调用 `Start()`，会触发 `std::thread` 的终止语义。
## 相关文档
- [返回类总览](Thread.md)
- [返回模块目录](../Threading.md)
- [返回类型总览](Thread.md)
- [GetId](GetId.md)

47
docs/api/XCEngine/Threading/Thread/Thread.md
View File

@@ -6,34 +6,41 @@
**头文件**: `XCEngine/Threading/Thread.h`
**描述**: 定义 `XCEngine/Threading` 子目录中的 `Thread` public API。
**描述**: 对 `std::thread` 的轻量包装，附带名称字符串和一个缓存的线程标识值。
## 概述
`Thread.h` 是 `XCEngine/Threading` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。
`Thread` 不是线程系统，而是一个非常薄的 `std::thread` 外壳。它主要额外做了两件事：
## 声明概览
- 保存一个 `Containers::String m_name`
- 在 `Start()` 时缓存一个 `m_id`
| 声明 | 类型 | 说明 |
|------|------|------|
| `Thread` | `class` | 头文件中的公开声明。 |
这类包装在引擎里很常见，因为很多系统希望在不直接暴露标准库类型的前提下，统一线程 API、线程名和工具层调试信息。
## 公共方法
## 当前实现边界
| 方法 | 描述 |
- [Destructor](Destructor.md) 会在对象析构时自动 `Join()`，因此析构可能阻塞。
- [Start](Start.md) 只保存名称字符串，不会设置 OS 层面的线程名。
- [GetId](GetId.md) 的来源是 `native_handle()` 转成整数，而 [GetCurrentId](GetCurrentId.md) 的来源是 `std::thread::id` 的 hash；两者不是同一口径。
- [Start](Start.md) 当前没有防御“对一个仍然 joinable 的线程再次 Start”的情况；这会落到 `std::thread` 的终止语义。
- 当前没有对应单测覆盖。
## 公开方法
| 方法 | 说明 |
|------|------|
| [Thread()](Constructor.md) | 构造对象。 |
| [~Thread()](Destructor.md) | 销毁对象并释放相关资源。 |
| [Start](Start.md) | 公开方法，详见头文件声明。 |
| [Join](Join.md) | 公开方法，详见头文件声明。 |
| [Detach](Detach.md) | 公开方法，详见头文件声明。 |
| [GetId](GetId.md) | 获取相关状态或对象。 |
| [GetName](GetName.md) | 获取相关状态或对象。 |
| [GetCurrentId](GetCurrentId.md) | 获取相关状态或对象。 |
| [Sleep](Sleep.md) | 公开方法，详见头文件声明。 |
| [Yield](Yield.md) | 公开方法，详见头文件声明。 |
| [Constructor](Constructor.md) | 构造空线程对象。 |
| [Destructor](Destructor.md) | 析构时自动 join。 |
| [Start](Start.md) | 启动线程。 |
| [Join](Join.md) | 等待线程结束。 |
| [Detach](Detach.md) | 分离线程。 |
| [GetId](GetId.md) | 获取缓存的线程标识。 |
| [GetName](GetName.md) | 获取保存的线程名称。 |
| [GetCurrentId](GetCurrentId.md) | 获取当前线程标识。 |
| [Sleep](Sleep.md) | 让当前线程休眠。 |
| [Yield](Yield.md) | 让出当前线程时间片。 |
## 相关文档
- [当前目录](../Threading.md) - 返回 `Threading` 平行目录
- [API 总索引](../../../main.md) - 返回顶层索引
- [当前模块](../Threading.md)
- [Synchronization And Task System Limits](../../../_guides/Threading/Synchronization-And-TaskSystem-Limits.md)

24
docs/api/XCEngine/Threading/Thread/Yield.md
View File

@@ -1,30 +1,20 @@
# Thread::Yield
公开方法，详见头文件声明。
让出当前线程时间片。
```cpp
static void Yield();
```
该方法声明于 `XCEngine/Threading/Thread.h`，当前页面用于固定 `Thread` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：** 无。
当前实现直接调用 `std::this_thread::yield()`。
**返回：** `void` - 无返回值。
## 返回值
**示例：**
```cpp
#include <XCEngine/Threading/Thread.h>
void Example() {
XCEngine::Threading::Thread object;
// 根据上下文补齐参数后调用 Thread::Yield(...)。
(void)object;
}
```
- 无。
## 相关文档
- [返回类总览](Thread.md)
- [返回模块目录](../Threading.md)
- [返回类型总览](Thread.md)
- [Sleep](Sleep.md)