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

25
docs/api/XCEngine/Threading/ReadWriteLock/Constructor.md
View File

@@ -1,28 +1,23 @@
# ReadWriteLock::ReadWriteLock()
# ReadWriteLock::Constructor
构造对象。
默认构造一个读写锁。
```cpp
ReadWriteLock() = default;
```
该方法声明于 `XCEngine/Threading/ReadWriteLock.h`，当前页面用于固定 `ReadWriteLock` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：** 无。
当前构造函数是默认实现，初始状态等价于：
**返回：** `void` - 无返回值。
- `m_readers == 0`
- `m_writersWaiting == 0`
- `m_writerActive == false`
**示例：**
## 返回值
```cpp
#include <XCEngine/Threading/ReadWriteLock.h>
void Example() {
XCEngine::Threading::ReadWriteLock object;
}
```
- 无。
## 相关文档
- [返回类总览](ReadWriteLock.md)
- [返回模块目录](../Threading.md)
- [返回类型总览](ReadWriteLock.md)

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

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

33
docs/api/XCEngine/Threading/ReadWriteLock/ReadLock.md
View File

@@ -1,30 +1,31 @@
# ReadWriteLock::ReadLock
公开方法，详见头文件声明。
以共享方式进入读写锁。
```cpp
void ReadLock();
```
该方法声明于 `XCEngine/Threading/ReadWriteLock.h`，当前页面用于固定 `ReadWriteLock` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：** 无。
**返回：** `void` - 无返回值。
**示例：**
当前实现会先拿内部互斥量，然后等待下面这个条件成立：
```cpp
#include <XCEngine/Threading/ReadWriteLock.h>
void Example() {
XCEngine::Threading::ReadWriteLock object;
// 根据上下文补齐参数后调用 ReadWriteLock::ReadLock(...)。
(void)object;
}
!m_writerActive && m_writersWaiting == 0
```
条件满足后，`m_readers` 加一。
## 返回值
- 无。
## 注意事项
- 只要有写者在等待，新读者也会被拦住，因此当前策略是写者优先而不是纯读者优先。
## 相关文档
- [返回类总览](ReadWriteLock.md)
- [返回模块目录](../Threading.md)
- [返回类型总览](ReadWriteLock.md)
- [ReadUnlock](ReadUnlock.md)
- [WriteLock](WriteLock.md)

25
docs/api/XCEngine/Threading/ReadWriteLock/ReadUnlock.md
View File

@@ -1,30 +1,23 @@
# ReadWriteLock::ReadUnlock
公开方法，详见头文件声明。
释放共享读锁。
```cpp
void ReadUnlock();
```
该方法声明于 `XCEngine/Threading/ReadWriteLock.h`，当前页面用于固定 `ReadWriteLock` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：** 无。
当前实现会先拿内部互斥量，再执行：
**返回：** `void` - 无返回值。
1. `--m_readers`
2. 如果 `m_readers == 0`，调用 `m_writeCondition.notify_all()`
**示例：**
## 返回值
```cpp
#include <XCEngine/Threading/ReadWriteLock.h>
void Example() {
XCEngine::Threading::ReadWriteLock object;
// 根据上下文补齐参数后调用 ReadWriteLock::ReadUnlock(...)。
(void)object;
}
```
- 无。
## 相关文档
- [返回类总览](ReadWriteLock.md)
- [返回模块目录](../Threading.md)
- [返回类型总览](ReadWriteLock.md)
- [ReadLock](ReadLock.md)

35
docs/api/XCEngine/Threading/ReadWriteLock/ReadWriteLock.md
View File

@@ -6,30 +6,33 @@
**头文件**: `XCEngine/Threading/ReadWriteLock.h`
**描述**: 定义 `XCEngine/Threading` 子目录中的 `ReadWriteLock` public API。
**描述**: 基于互斥量和条件变量实现的写者优先读写锁。
## 概述
`ReadWriteLock.h` 是 `XCEngine/Threading` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。
`ReadWriteLock` 允许多个读者并发进入，但写者需要独占访问。
## 声明概览
当前实现的一个关键策略是：只要有写者在等待，新读者就不能继续进入。这意味着它更偏向“写者优先”，可以降低写者长期饥饿的风险，但也可能让高频写入场景里的读者等待更久。
| 声明 | 类型 | 说明 |
|------|------|------|
| `ReadWriteLock` | `class` | 头文件中的公开声明。 |
## 当前实现边界
## 公共方法
- 没有 `TryReadLock()` / `TryWriteLock()`。
- 没有升级、降级或 RAII guard 类型。
- 当前策略会在 `m_writersWaiting > 0` 时阻止新读者进入，因此可能出现读者饥饿。
- 没有单测覆盖这把锁的并发行为。
| 方法 | 描述 |
## 公开方法
| 方法 | 说明 |
|------|------|
| [ReadWriteLock()](Constructor.md) | 构造对象。 |
| [~ReadWriteLock()](Destructor.md) | 销毁对象并释放相关资源。 |
| [ReadLock](ReadLock.md) | 公开方法，详见头文件声明。 |
| [ReadUnlock](ReadUnlock.md) | 公开方法，详见头文件声明。 |
| [WriteLock](WriteLock.md) | 公开方法，详见头文件声明。 |
| [WriteUnlock](WriteUnlock.md) | 公开方法，详见头文件声明。 |
| [Constructor](Constructor.md) | 默认构造读写锁。 |
| [Destructor](Destructor.md) | 销毁读写锁。 |
| [ReadLock](ReadLock.md) | 以共享方式进入。 |
| [ReadUnlock](ReadUnlock.md) | 释放共享读锁。 |
| [WriteLock](WriteLock.md) | 以独占方式进入。 |
| [WriteUnlock](WriteUnlock.md) | 释放独占写锁。 |
## 相关文档
- [当前目录](../Threading.md) - 返回 `Threading` 平行目录
- [API 总索引](../../../main.md) - 返回顶层索引
- [当前模块](../Threading.md)
- [Mutex](../Mutex/Mutex.md)

28
docs/api/XCEngine/Threading/ReadWriteLock/WriteLock.md
View File

@@ -1,30 +1,26 @@
# ReadWriteLock::WriteLock
公开方法，详见头文件声明。
以独占方式进入读写锁。
```cpp
void WriteLock();
```
该方法声明于 `XCEngine/Threading/ReadWriteLock.h`，当前页面用于固定 `ReadWriteLock` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：** 无。
当前实现会：
**返回：** `void` - 无返回值。
1. 拿内部互斥量。
2. 先执行 `++m_writersWaiting`。
3. 等待 `m_readers == 0 && !m_writerActive`。
4. 条件满足后执行 `--m_writersWaiting` 并把 `m_writerActive = true`。
**示例：**
## 返回值
```cpp
#include <XCEngine/Threading/ReadWriteLock.h>
void Example() {
XCEngine::Threading::ReadWriteLock object;
// 根据上下文补齐参数后调用 ReadWriteLock::WriteLock(...)。
(void)object;
}
```
- 无。
## 相关文档
- [返回类总览](ReadWriteLock.md)
- [返回模块目录](../Threading.md)
- [返回类型总览](ReadWriteLock.md)
- [WriteUnlock](WriteUnlock.md)
- [ReadLock](ReadLock.md)

26
docs/api/XCEngine/Threading/ReadWriteLock/WriteUnlock.md
View File

@@ -1,30 +1,24 @@
# ReadWriteLock::WriteUnlock
公开方法，详见头文件声明。
释放独占写锁。
```cpp
void WriteUnlock();
```
该方法声明于 `XCEngine/Threading/ReadWriteLock.h`，当前页面用于固定 `ReadWriteLock` 类目录下的方法级 canonical 路径。
## 行为说明
**参数：** 无。
当前实现会先拿内部互斥量，然后：
**返回：** `void` - 无返回值。
1. 把 `m_writerActive = false`
2. 调用 `m_readCondition.notify_all()`
3. 调用 `m_writeCondition.notify_one()`
**示例：**
## 返回值
```cpp
#include <XCEngine/Threading/ReadWriteLock.h>
void Example() {
XCEngine::Threading::ReadWriteLock object;
// 根据上下文补齐参数后调用 ReadWriteLock::WriteUnlock(...)。
(void)object;
}
```
- 无。
## 相关文档
- [返回类总览](ReadWriteLock.md)
- [返回模块目录](../Threading.md)
- [返回类型总览](ReadWriteLock.md)
- [WriteLock](WriteLock.md)