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

23
docs/api/XCEngine/Threading/Mutex/Constructor.md
View File

@@ -1,28 +1,19 @@
# Mutex::Mutex()
# Mutex::Constructor
构造对象。
默认构造一个互斥锁。
```cpp
Mutex() = default;
```
该方法声明于 `XCEngine/Threading/Mutex.h`，当前页面用于固定 `Mutex` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：** 无。
当前构造函数是编译器生成的默认实现，唯一实质状态是内部的 `std::mutex`。
**返回：** `void` - 无返回值。
## 返回值
**示例：**
```cpp
#include <XCEngine/Threading/Mutex.h>
void Example() {
XCEngine::Threading::Mutex object;
}
```
- 无。
## 相关文档
- [返回类总览](Mutex.md)
- [返回模块目录](../Threading.md)
- [返回类型总览](Mutex.md)

24
docs/api/XCEngine/Threading/Mutex/Destructor.md
View File

@@ -1,29 +1,23 @@
# Mutex::~Mutex()
# Mutex::Destructor
销毁对象并释放相关资源。
销毁互斥锁对象。
```cpp
~Mutex() = default;
```
该方法声明于 `XCEngine/Threading/Mutex.h`，当前页面用于固定 `Mutex` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：** 无。
当前析构函数是默认实现，析构行为由内部 `std::mutex` 决定。
**返回：** `void` - 无返回值。
## 返回值
**示例：**
- 无。
```cpp
#include <XCEngine/Threading/Mutex.h>
## 注意事项
void Example() {
XCEngine::Threading::Mutex object;
// 对象离开作用域时会自动触发析构。
}
```
- 和标准库一样，销毁一个仍在被使用的互斥锁属于未定义行为。
## 相关文档
- [返回类总览](Mutex.md)
- [返回模块目录](../Threading.md)
- [返回类型总览](Mutex.md)

31
docs/api/XCEngine/Threading/Mutex/Lock.md Normal file
View File

@@ -0,0 +1,31 @@
# Mutex::Lock
阻塞直到获得互斥锁。
```cpp
void Lock();
void lock() const;
```
## 行为说明
当前实现有两套入口：
- `Lock()`：引擎风格命名。
- `lock()`：标准 Lockable 风格别名。
两者都直接转发到底层 `std::mutex::lock()`。
## 返回值
- 无。
## 注意事项
- 如果当前线程已经持有这把锁，再次调用会死锁。
- `lock()` 的存在使 `Mutex` 可以直接配合 `std::lock_guard<Mutex>` 等标准库工具使用。
## 相关文档
- [返回类型总览](Mutex.md)
- [Unlock](Unlock.md)

40
docs/api/XCEngine/Threading/Mutex/Mutex.md
View File

@@ -6,32 +6,36 @@
**头文件**: `XCEngine/Threading/Mutex.h`
**描述**: 定义 `XCEngine/Threading` 子目录中的 `Mutex` public API。
**描述**: 对 `std::mutex` 的薄封装，同时提供引擎风格和 STL Lockable 风格接口。
## 概述
`Mutex.h` 是 `XCEngine/Threading` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。
`Mutex` 的实现非常直接：内部只有一个 `mutable std::mutex m_mutex`，所有公开接口都是对它的转发。
## 声明概览
这类包装在引擎里常见的原因不是为了改变 `std::mutex` 的行为，而是为了：
| 声明 | 类型 | 说明 |
|------|------|------|
| `Mutex` | `class` | 头文件中的公开声明。 |
- 统一命名空间与 include 路径。
- 同时支持 `Lock()` 这种引擎风格接口。
- 也支持 `lock()` / `unlock()` / `try_lock()` 这种标准库 Lockable 习惯用法。
## 公共方法
## 当前实现边界
| 方法 | 描述 |
- 它不是递归锁；同一线程重复加锁会死锁。
- 没有超时锁接口。
- 没有显式的 owner 检查或调试断言。
- 小写接口之所以能声明成 `const`，是因为底层 `std::mutex` 被保存为 `mutable`。
## 公开方法
| 方法 | 说明 |
|------|------|
| [Mutex()](Constructor.md) | 构造对象。 |
| [~Mutex()](Destructor.md) | 销毁对象并释放相关资源。 |
| [Lock](Lock.md) | 公开方法，详见头文件声明。 |
| [Unlock](Unlock.md) | 公开方法，详见头文件声明。 |
| [TryLock](TryLock.md) | 公开方法，详见头文件声明。 |
| [lock](lock.md) | 公开方法，详见头文件声明。 |
| [unlock](unlock.md) | 公开方法，详见头文件声明。 |
| [try_lock](try_lock.md) | 公开方法，详见头文件声明。 |
| [Constructor](Constructor.md) | 默认构造互斥锁。 |
| [Destructor](Destructor.md) | 销毁互斥锁。 |
| [Lock](Lock.md) | 阻塞直到获得锁；同页也说明 `lock()` 别名。 |
| [Unlock](Unlock.md) | 释放锁；同页也说明 `unlock()` 别名。 |
| [TryLock](TryLock.md) | 尝试获得锁；同页也说明 `try_lock()` 别名。 |
## 相关文档
- [当前目录](../Threading.md) - 返回 `Threading` 平行目录
- [API 总索引](../../../main.md) - 返回顶层索引
- [当前模块](../Threading.md)
- [SpinLock](../SpinLock/SpinLock.md)

26
docs/api/XCEngine/Threading/Mutex/TryLock.md
View File

@@ -1,30 +1,26 @@
# Mutex::TryLock
公开方法，详见头文件声明。
尝试获得互斥锁。
```cpp
bool TryLock();
bool try_lock() const;
```
该方法声明于 `XCEngine/Threading/Mutex.h`，当前页面用于固定 `Mutex` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：** 无。
当前实现有两套入口：
**返回：** `bool` - 返回值语义详见头文件声明。
- `TryLock()`：引擎风格命名。
- `try_lock()`：标准 Lockable 风格别名。
**示例：**
两者都直接调用底层 `std::mutex::try_lock()`。
```cpp
#include <XCEngine/Threading/Mutex.h>
## 返回值
void Example() {
XCEngine::Threading::Mutex object;
// 根据上下文补齐参数后调用 Mutex::TryLock(...)。
(void)object;
}
```
- `bool` - 成功获得锁时返回 `true`；否则返回 `false`。
## 相关文档
- [返回类总览](Mutex.md)
- [返回模块目录](../Threading.md)
- [返回类型总览](Mutex.md)
- [Lock](Lock.md)

26
docs/api/XCEngine/Threading/Mutex/Unlock.md Normal file
View File

@@ -0,0 +1,26 @@
# Mutex::Unlock
释放互斥锁。
```cpp
void Unlock();
void unlock() const;
```
## 行为说明
当前实现有两套入口：
- `Unlock()`：引擎风格命名。
- `unlock()`：标准 Lockable 风格别名。
两者都直接转发到底层 `std::mutex::unlock()`。
## 返回值
- 无。
## 相关文档
- [返回类型总览](Mutex.md)
- [Lock](Lock.md)

30
docs/api/XCEngine/Threading/Mutex/lock.md
View File

@@ -1,30 +0,0 @@
# Mutex::lock
公开方法，详见头文件声明。
```cpp
void lock() const;
```
该方法声明于 `XCEngine/Threading/Mutex.h`，当前页面用于固定 `Mutex` 类目录下的方法级 canonical 路径。
**参数：** 无。
**返回：** `void` - 无返回值。
**示例：**
```cpp
#include <XCEngine/Threading/Mutex.h>
void Example() {
XCEngine::Threading::Mutex object;
// 根据上下文补齐参数后调用 Mutex::lock(...)。
(void)object;
}
```
## 相关文档
- [返回类总览](Mutex.md)
- [返回模块目录](../Threading.md)

30
docs/api/XCEngine/Threading/Mutex/try_lock.md
View File

@@ -1,30 +0,0 @@
# Mutex::try_lock
公开方法，详见头文件声明。
```cpp
bool try_lock() const;
```
该方法声明于 `XCEngine/Threading/Mutex.h`，当前页面用于固定 `Mutex` 类目录下的方法级 canonical 路径。
**参数：** 无。
**返回：** `bool` - 返回值语义详见头文件声明。
**示例：**
```cpp
#include <XCEngine/Threading/Mutex.h>
void Example() {
XCEngine::Threading::Mutex object;
// 根据上下文补齐参数后调用 Mutex::try_lock(...)。
(void)object;
}
```
## 相关文档
- [返回类总览](Mutex.md)
- [返回模块目录](../Threading.md)

30
docs/api/XCEngine/Threading/Mutex/unlock.md
View File

@@ -1,30 +0,0 @@
# Mutex::unlock
公开方法，详见头文件声明。
```cpp
void unlock() const;
```
该方法声明于 `XCEngine/Threading/Mutex.h`，当前页面用于固定 `Mutex` 类目录下的方法级 canonical 路径。
**参数：** 无。
**返回：** `void` - 无返回值。
**示例：**
```cpp
#include <XCEngine/Threading/Mutex.h>
void Example() {
XCEngine::Threading::Mutex object;
// 根据上下文补齐参数后调用 Mutex::unlock(...)。
(void)object;
}
```
## 相关文档
- [返回类总览](Mutex.md)
- [返回模块目录](../Threading.md)