refactor: improve test infrastructure and fix OpenGL GLAD initialization

- Rename D3D12Enum.h to D3D12Enums.h for naming consistency - Fix OpenGL unit test GLAD initialization by using gladLoadGL() instead of gladLoadGLLoader(wglGetProcAddress) for fallback support - Migrate remaining tests to use gtest_discover_tests for granular test discovery (math, core, containers, memory, threading, debug, components, scene, resources, input, opengl) - Remove obsolete TEST_RESOURCES_DIR and copy_directory commands from OpenGL unit test CMakeLists (minimal/Res doesn't exist) - Update TEST_SPEC.md with performance metrics and per-module build/test commands for faster development workflow - Update CMake path references to use lowercase paths
2026-03-23 00:43:02 +08:00
parent 0f0ab8922a
commit f427699ac6
100 changed files with 1191 additions and 1136 deletions
--- a/docs/api/threading/read-write-lock/constructor.md
+++ b/docs/api/threading/read-write-lock/constructor.md
@@ -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) - 释放写锁
--- a/docs/api/threading/read-write-lock/destructor.md
+++ b/docs/api/threading/read-write-lock/destructor.md
@@ -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) - 释放写锁
--- a/docs/api/threading/read-write-lock/read-write-lock.md
+++ b/docs/api/threading/read-write-lock/read-write-lock.md
@@ -0,0 +1,91 @@
+# ReadWriteLock
+
+**命名空间**: `XCEngine::Threading`
+
+**类型**: `class`
+
+**头文件**: `XCEngine/Threading/ReadWriteLock.h`
+
+**描述**: 读写锁，允许多个读者或单个写者
+
+## 概述
+
+`ReadWriteLock` 实现了一个经典的读写锁。它允许多个线程同时持有读锁，但在有写锁时，所有读锁都必须释放，写锁为独占访问。这对于读操作远多于写操作的共享数据非常有效。
+
+### 设计目的
+
+- 提供比普通互斥锁更高的并发性能
+- 允许多个线程同时读取共享数据
+- 确保写入操作时的独占性访问
+- 防止写者饥饿（通过写者优先策略）
+
+### 使用场景
+
+- 读多写少的共享数据访问
+- 需要保护长时间读取的数据结构
+- 数据库、缓存、配置等共享资源访问
+
+## 公共方法
+
+| 方法 | 描述 |
+|------|------|
+| [`ReadWriteLock`](constructor.md) | 构造一个读写锁 |
+| [`~ReadWriteLock`](destructor.md) | 销毁读写锁 |
+| [`ReadLock`](readlock.md) | 获取读锁（支持多个并发读者） |
+| [`ReadUnlock`](readunlock.md) | 释放读锁 |
+| [`WriteLock`](writelock.md) | 获取写锁（独占，阻塞所有读者和写者） |
+| [`WriteUnlock`](writeunlock.md) | 释放写锁 |
+
+## 使用示例
+
+```cpp
+#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 std::string& key) {
+    rwLock.ReadLock();
+    int value = 0;
+    auto it = sharedCache.find(key);
+    if (it != sharedCache.end()) {
+        value = it->second;
+    }
+    rwLock.ReadUnlock();
+    return value;
+}
+
+// 写操作（独占）
+void WriteData(const std::string& key, int value) {
+    rwLock.WriteLock();
+    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;
+}
+```
+
+## 相关文档
+
+- [`ReadLock`](readlock.md) - 获取读锁
+- [`ReadUnlock`](readunlock.md) - 释放读锁
+- [`WriteLock`](writelock.md) - 获取写锁
+- [`WriteUnlock`](writeunlock.md) - 释放写锁
--- a/docs/api/threading/read-write-lock/readlock.md
+++ b/docs/api/threading/read-write-lock/readlock.md
@@ -0,0 +1,41 @@
+# ReadWriteLock::ReadLock
+
+```cpp
+void ReadLock()
+```
+
+获取读锁。如果有写者持有锁或正在等待写锁，当前线程将阻塞，直到所有写者完成。
+
+**参数：** 无
+
+**返回：** 无
+
+**线程安全：** ✅
+
+**复杂度：** 平均 O(1)
+
+**注意：**
+- 多个读者可以同时持有读锁。
+- 写锁具有优先权——正在等待的写者会阻塞新的读者，防止写者饥饿。
+- 读锁不可重入，同一线程不可嵌套持有读锁。
+
+**示例：**
+
+```cpp
+#include "XCEngine/Threading/ReadWriteLock.h"
+
+XCEngine::Threading::ReadWriteLock rwLock;
+int sharedValue = 0;
+
+int ReadValue() {
+    rwLock.ReadLock();
+    int value = sharedValue;
+    rwLock.ReadUnlock();
+    return value;
+}
+```
+
+## 相关文档
+
+- [`ReadWriteLock`](readwritelock.md) - 返回类总览
+- [`ReadUnlock`](readunlock.md) - 释放读锁
--- a/docs/api/threading/read-write-lock/readunlock.md
+++ b/docs/api/threading/read-write-lock/readunlock.md
@@ -0,0 +1,38 @@
+# ReadWriteLock::ReadUnlock
+
+```cpp
+void ReadUnlock()
+```
+
+释放读锁。如果这是最后一个读者，将唤醒等待中的写者。
+
+**参数：** 无
+
+**返回：** 无
+
+**线程安全：** ✅
+
+**复杂度：** O(1)
+
+**注意：** 必须与 ReadLock 配对使用，且在持有读锁的线程中调用。
+
+**示例：**
+
+```cpp
+#include "XCEngine/Threading/ReadWriteLock.h"
+
+XCEngine::Threading::ReadWriteLock rwLock;
+float sharedData = 0.0f;
+
+float GetData() {
+    rwLock.ReadLock();
+    float data = sharedData;
+    rwLock.ReadUnlock();
+    return data;
+}
+```
+
+## 相关文档
+
+- [`ReadWriteLock`](readwritelock.md) - 返回类总览
+- [`ReadLock`](readlock.md) - 获取读锁
--- a/docs/api/threading/read-write-lock/writelock.md
+++ b/docs/api/threading/read-write-lock/writelock.md
@@ -0,0 +1,41 @@
+# ReadWriteLock::WriteLock
+
+```cpp
+void WriteLock()
+```
+
+获取写锁（独占）。如果有读者持有锁或有其他写者正在等待，当前线程将阻塞，直到获得独占访问权。
+
+**参数：** 无
+
+**返回：** 无
+
+**线程安全：** ✅
+
+**复杂度：** 平均 O(1)，写者饥饿时可能 O(n)
+
+**注意：**
+- 写锁为独占访问，持有期间不允许任何读锁或写锁。
+- 写锁具有优先权，会阻塞后续到达的读者。
+- 同一线程不可重复 WriteLock。
+
+**示例：**
+
+```cpp
+#include "XCEngine/Threading/ReadWriteLock.h"
+#include <vector>
+
+XCEngine::Threading::ReadWriteLock rwLock;
+std::vector<int> buffer;
+
+void Append(int value) {
+    rwLock.WriteLock();
+    buffer.push_back(value);
+    rwLock.WriteUnlock();
+}
+```
+
+## 相关文档
+
+- [`ReadWriteLock`](readwritelock.md) - 返回类总览
+- [`WriteUnlock`](writeunlock.md) - 释放写锁
--- a/docs/api/threading/read-write-lock/writeunlock.md
+++ b/docs/api/threading/read-write-lock/writeunlock.md
@@ -0,0 +1,39 @@
+# ReadWriteLock::WriteUnlock
+
+```cpp
+void WriteUnlock()
+```
+
+释放写锁。唤醒所有等待中的读者和下一个写者。
+
+**参数：** 无
+
+**返回：** 无
+
+**线程安全：** ✅
+
+**复杂度：** O(1)
+
+**注意：** 必须在持有写锁的线程中调用。
+
+**示例：**
+
+```cpp
+#include "XCEngine/Threading/ReadWriteLock.h"
+#include <unordered_map>
+#include <string>
+
+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();
+}
+```
+
+## 相关文档
+
+- [`ReadWriteLock`](readwritelock.md) - 返回类总览
+- [`WriteLock`](writelock.md) - 获取写锁