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

docs: update memory and threading API docs

Browse Source
This commit is contained in:
ssdfasd
2026-03-20 02:35:24 +08:00
parent c5b17239ca
commit fd792b7df1
103 changed files with 2485 additions and 673 deletions
Download Patch File Download Diff File Expand all files Collapse all files

35
docs/api/threading/readwritelock/constructor.md Normal file
View File

@@ -0,0 +1,35 @@
# ReadWriteLock::ReadWriteLock
```cpp
ReadWriteLock() = default;
```
默认构造函数。构造一个未锁定的读写锁。
**参数：** 无
**返回：** 无
**线程安全：** ✅
**复杂度：** O(1)
**注意：**
- 构造后的锁处于未锁定状态。
- 多个线程可以同时获取读锁。
**示例：**
```cpp
#include "XCEngine/Threading/ReadWriteLock.h"
XCEngine::Threading::ReadWriteLock rwLock;
```
## 相关文档
- [`ReadWriteLock`](readwritelock.md) - 返回类总览
- [`ReadLock`](readlock.md) - 获取读锁
- [`ReadUnlock`](readunlock.md) - 释放读锁
- [`WriteLock`](writelock.md) - 获取写锁
- [`WriteUnlock`](writeunlock.md) - 释放写锁

40
docs/api/threading/readwritelock/destructor.md Normal file
View File

@@ -0,0 +1,40 @@
# ReadWriteLock::~ReadWriteLock
```cpp
~ReadWriteLock() = default;
```
默认析构函数。销毁读写锁。
**参数：** 无
**返回：** 无
**线程安全：** ⚠️
**复杂度：** O(1)
**注意：**
- 析构前必须确保锁处于未锁定状态。
- 如果在持有锁的状态下销毁行为未定义。
**示例：**
```cpp
#include "XCEngine/Threading/ReadWriteLock.h"
{
XCEngine::Threading::ReadWriteLock rwLock;
rwLock.ReadLock();
// ... 使用共享数据 ...
rwLock.ReadUnlock();
} // rwLock 在这里销毁
```
## 相关文档
- [`ReadWriteLock`](readwritelock.md) - 返回类总览
- [`ReadLock`](readlock.md) - 获取读锁
- [`ReadUnlock`](readunlock.md) - 释放读锁
- [`WriteLock`](writelock.md) - 获取写锁
- [`WriteUnlock`](writeunlock.md) - 释放写锁

11
docs/api/threading/readwritelock/readlock.md
View File

@@ -10,17 +10,21 @@ void ReadLock()
**返回：** 无
**线程安全：** ✅
**复杂度：** 平均 O(1)
**注意：**
- 多个读者可以同时持有读锁。
- 写锁具有优先权——正在等待的写者会阻塞新的读者，防止写者饥饿。
- 读锁不可重入，同一线程不可嵌套持有读锁（会导致死锁）。
- 读锁不可重入，同一线程不可嵌套持有读锁。
**示例：**
```cpp
ReadWriteLock rwLock;
#include "XCEngine/Threading/ReadWriteLock.h"
XCEngine::Threading::ReadWriteLock rwLock;
int sharedValue = 0;
int ReadValue() {
@@ -33,4 +37,5 @@ int ReadValue() {
## 相关文档
- [ReadWriteLock 总览](readwritelock.md) - 返回类总览
- [`ReadWriteLock`](readwritelock.md) - 返回类总览
- [`ReadUnlock`](readunlock.md) - 释放读锁

9
docs/api/threading/readwritelock/readunlock.md
View File

@@ -10,6 +10,8 @@ void ReadUnlock()
**返回：** 无
**线程安全：** ✅
**复杂度：** O(1)
**注意：** 必须与 ReadLock 配对使用，且在持有读锁的线程中调用。
@@ -17,7 +19,9 @@ void ReadUnlock()
**示例：**
```cpp
ReadWriteLock rwLock;
#include "XCEngine/Threading/ReadWriteLock.h"
XCEngine::Threading::ReadWriteLock rwLock;
float sharedData = 0.0f;
float GetData() {
@@ -30,4 +34,5 @@ float GetData() {
## 相关文档
- [ReadWriteLock 总览](readwritelock.md) - 返回类总览
- [`ReadWriteLock`](readwritelock.md) - 返回类总览
- [`ReadLock`](readlock.md) - 获取读锁

70
docs/api/threading/readwritelock/readwritelock.md
View File

@@ -6,52 +6,86 @@
**头文件**: `XCEngine/Threading/ReadWriteLock.h`
**描述**: 读写锁实现，支持多个并发读取或单一写入，提高读多写少场景的并发性能。
**描述**: 读写锁，允许多个读者或单个写者
## 概述
`ReadWriteLock` 实现了一个经典的读写锁。它允许多个线程同时持有读锁，但在有写锁时，所有读锁都必须释放，写锁为独占访问。这对于读操作远多于写操作的共享数据非常有效。
### 设计目的
- 提供比普通互斥锁更高的并发性能
- 允许多个线程同时读取共享数据
- 确保写入操作时的独占性访问
- 防止写者饥饿（通过写者优先策略）
### 使用场景
- 读多写少的共享数据访问
- 需要保护长时间读取的数据结构
- 数据库、缓存、配置等共享资源访问
## 公共方法
### 读锁
| 方法 | 描述 |
|------|------|
| [`ReadLock`](readlock.md) | 获取读锁（可重入，支持多个并发读者） |
| [`ReadWriteLock`](constructor.md) | 构造一个读写锁 |
| [`~ReadWriteLock`](destructor.md) | 销毁读写锁 |
| [`ReadLock`](readlock.md) | 获取读锁（支持多个并发读者） |
| [`ReadUnlock`](readunlock.md) | 释放读锁 |
### 写锁
| 方法 | 描述 |
|------|------|
| [`WriteLock`](writelock.md) | 获取写锁（独占，阻塞所有读者和写者） |
| [`WriteUnlock`](writeunlock.md) | 释放写锁 |
## 使用示例
```cpp
Threading::ReadWriteLock rwLock;
Containers::HashMap<String, int> sharedMap;
#include "XCEngine/Threading/ReadWriteLock.h"
#include <thread>
#include <vector>
#include <iostream>
#include <map>
XCEngine::Threading::ReadWriteLock rwLock;
std::map<std::string, int> sharedCache;
// 读操作（多个线程可同时读）
int* ReadData(const String& key) {
int ReadData(const std::string& key) {
rwLock.ReadLock();
int* value = sharedMap.Find(key);
int value = 0;
auto it = sharedCache.find(key);
if (it != sharedCache.end()) {
value = it->second;
}
rwLock.ReadUnlock();
return value;
}
// 写操作（独占）
void WriteData(const String& key, int value) {
void WriteData(const std::string& key, int value) {
rwLock.WriteLock();
sharedMap.Insert(key, value);
sharedCache[key] = value;
rwLock.WriteUnlock();
}
int main() {
std::vector<std::thread> threads;
threads.emplace_back(WriteData, "score", 100);
threads.emplace_back(ReadData, "score");
threads.emplace_back(WriteData, "health", 200);
threads.emplace_back(ReadData, "health");
for (auto& t : threads) {
t.join();
}
return 0;
}
```
## 相关文档
- [Mutex](../mutex/mutex.md) - 互斥锁
- [SpinLock](../spinlock/spinlock.md) - 自旋锁
- [../threading/threading.md](../threading.md) - 模块总览
- [`ReadLock`](readlock.md) - 获取读锁
- [`ReadUnlock`](readunlock.md) - 释放读锁
- [`WriteLock`](writelock.md) - 获取写锁
- [`WriteUnlock`](writeunlock.md) - 释放写锁

10
docs/api/threading/readwritelock/writelock.md
View File

@@ -10,6 +10,8 @@ void WriteLock()
**返回：** 无
**线程安全：** ✅
**复杂度：** 平均 O(1)，写者饥饿时可能 O(n)
**注意：**
@@ -20,7 +22,10 @@ void WriteLock()
**示例：**
```cpp
ReadWriteLock rwLock;
#include "XCEngine/Threading/ReadWriteLock.h"
#include <vector>
XCEngine::Threading::ReadWriteLock rwLock;
std::vector<int> buffer;
void Append(int value) {
@@ -32,4 +37,5 @@ void Append(int value) {
## 相关文档
- [ReadWriteLock 总览](readwritelock.md) - 返回类总览
- [`ReadWriteLock`](readwritelock.md) - 返回类总览
- [`WriteUnlock`](writeunlock.md) - 释放写锁

15
docs/api/threading/readwritelock/writeunlock.md
View File

@@ -10,6 +10,8 @@ void WriteUnlock()
**返回：** 无
**线程安全：** ✅
**复杂度：** O(1)
**注意：** 必须在持有写锁的线程中调用。
@@ -17,10 +19,14 @@ void WriteUnlock()
**示例：**
```cpp
ReadWriteLock rwLock;
std::unordered_map<String, int> cache;
#include "XCEngine/Threading/ReadWriteLock.h"
#include <unordered_map>
#include <string>
void UpdateCache(const String& key, int value) {
XCEngine::Threading::ReadWriteLock rwLock;
std::unordered_map<std::string, int> cache;
void UpdateCache(const std::string& key, int value) {
rwLock.WriteLock();
cache[key] = value;
rwLock.WriteUnlock();
@@ -29,4 +35,5 @@ void UpdateCache(const String& key, int value) {
## 相关文档
- [ReadWriteLock 总览](readwritelock.md) - 返回类总览
- [`ReadWriteLock`](readwritelock.md) - 返回类总览
- [`WriteLock`](writelock.md) - 获取写锁