docs: update memory and threading API docs
This commit is contained in:
@@ -1,36 +1,44 @@
|
||||
# Thread::Detach
|
||||
|
||||
```cpp
|
||||
void Detach()
|
||||
void Detach();
|
||||
```
|
||||
|
||||
分离线程，使其成为后台线程独立运行。分离后，线程的资源将在其终止时自动释放，调用线程不会被阻塞。
|
||||
分离线程，使其在后台独立运行。调用 `Detach()` 后，线程不再受 `Thread` 对象管理，其生命周期由 C++ 运行时库自行管理，直到线程函数执行完毕。
|
||||
|
||||
分离后的线程成为"守护线程"，其资源在线程结束时自动由运行时回收。与 `Join()` 不同，`Detach()` 只能调用一次。
|
||||
|
||||
**警告：** 分离线程时必须确保其访问的所有数据在线程运行期间保持有效。分离后无法通过 `Thread` 对象同步或等待线程。
|
||||
|
||||
**参数：** 无
|
||||
|
||||
**返回：** 无
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**注意：**
|
||||
- 分离后的线程无法再被 Join 或进行任何同步操作。
|
||||
- 确保分离线程的所有资源访问都是线程安全的，因为主线程可能在分离线程结束前退出。
|
||||
- 如果 Thread 对象在分离线程结束前被销毁，行为取决于具体实现。
|
||||
**线程安全：** ❌
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
Thread background;
|
||||
background.Start([]() {
|
||||
printf("Background task running\n");
|
||||
for (int i = 0; i < 3; ++i) {
|
||||
Thread::Sleep(500);
|
||||
printf("Background: tick %d\n", i);
|
||||
}
|
||||
}, "BackgroundThread");
|
||||
#include "XCEngine/Threading/Thread.h"
|
||||
#include <iostream>
|
||||
|
||||
background.Detach();
|
||||
printf("Main thread continues immediately\n");
|
||||
using namespace XCEngine::Threading;
|
||||
|
||||
int main() {
|
||||
Thread t;
|
||||
t.Start([]() {
|
||||
for (int i = 0; i < 3; ++i) {
|
||||
std::cout << "Detached thread running: " << i << std::endl;
|
||||
Thread::Sleep(50);
|
||||
}
|
||||
}, "DetachedThread");
|
||||
|
||||
std::cout << "Thread detached, main continues..." << std::endl;
|
||||
t.Detach();
|
||||
|
||||
Thread::Sleep(200);
|
||||
return 0;
|
||||
}
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
@@ -1,27 +1,40 @@
|
||||
# Thread::GetCurrentId
|
||||
|
||||
```cpp
|
||||
static Id GetCurrentId()
|
||||
static Id GetCurrentId();
|
||||
```
|
||||
|
||||
获取当前执行线程的唯一标识符。这是一个静态方法，可以在任何线程上下文中调用。
|
||||
静态方法，返回当前执行线程的唯一标识符。此方法可在任意线程上下文中调用，包括主线程和工作线程。
|
||||
|
||||
线程 ID 通过 `std::this_thread::get_id()` 获取，并使用 `std::hash<std::thread::id>` 转换为 `uint64_t` 值。该值与 `Thread::GetId()` 返回的值格式一致，可以直接比较。
|
||||
|
||||
**参数：** 无
|
||||
|
||||
**返回：** `Thread::Id` - 当前执行线程的唯一标识符
|
||||
**返回：** 调用线程的唯一标识符
|
||||
|
||||
**复杂度：** O(1)
|
||||
**线程安全：** ✅
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
Thread worker;
|
||||
worker.Start([]() {
|
||||
printf("Worker thread id: %llu\n", (unsigned long long)Thread::GetCurrentId());
|
||||
}, "WorkerThread");
|
||||
#include "XCEngine/Threading/Thread.h"
|
||||
#include <iostream>
|
||||
|
||||
printf("Main thread id: %llu\n", (unsigned long long)Thread::GetCurrentId());
|
||||
worker.Join();
|
||||
using namespace XCEngine::Threading;
|
||||
|
||||
int main() {
|
||||
std::cout << "Main thread ID: " << Thread::GetCurrentId() << std::endl;
|
||||
|
||||
Thread t;
|
||||
t.Start([]() {
|
||||
std::cout << "Worker thread ID: " << Thread::GetCurrentId() << std::endl;
|
||||
std::cout << "Worker ID matches Thread.GetId(): "
|
||||
<< (Thread::GetCurrentId() == t.GetId() ? "Yes" : "No") << std::endl;
|
||||
}, "CheckIdThread");
|
||||
|
||||
t.Join();
|
||||
return 0;
|
||||
}
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
@@ -1,27 +1,41 @@
|
||||
# Thread::GetId
|
||||
|
||||
```cpp
|
||||
Id GetId() const
|
||||
Id GetId() const;
|
||||
```
|
||||
|
||||
获取当前线程对象的唯一标识符。该 ID 在线程启动后有效。
|
||||
返回当前线程对象的唯一标识符。线程 ID 是 `uint64_t` 类型的值，通过 `std::thread::native_handle()` 获取原生线程句柄并转换为整数。
|
||||
|
||||
线程 ID 在线程启动后生效。在调用 `Start()` 之前，`GetId()` 返回 0。
|
||||
|
||||
**参数：** 无
|
||||
|
||||
**返回：** `Thread::Id` - 线程的唯一标识符（uint64_t 类型）
|
||||
**返回：** 线程的唯一标识符，线程未启动时返回 0
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**注意：** 在调用 Start 之前返回 0。
|
||||
**线程安全：** ✅
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
Thread worker;
|
||||
printf("Before start: id=%llu\n", (unsigned long long)worker.GetId());
|
||||
worker.Start([]() {}, "Test");
|
||||
printf("After start: id=%llu\n", (unsigned long long)worker.GetId());
|
||||
worker.Join();
|
||||
#include "XCEngine/Threading/Thread.h"
|
||||
#include <iostream>
|
||||
|
||||
using namespace XCEngine::Threading;
|
||||
|
||||
int main() {
|
||||
Thread t;
|
||||
|
||||
std::cout << "Before Start - Thread ID: " << t.GetId() << std::endl;
|
||||
|
||||
t.Start([]() {
|
||||
std::cout << "Worker ID: " << Thread::GetCurrentId() << std::endl;
|
||||
}, "WorkerThread");
|
||||
|
||||
std::cout << "After Start - Thread ID: " << t.GetId() << std::endl;
|
||||
|
||||
t.Join();
|
||||
return 0;
|
||||
}
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
@@ -1,26 +1,47 @@
|
||||
# Thread::GetName
|
||||
|
||||
```cpp
|
||||
const Containers::String& GetName() const
|
||||
const Containers::String& GetName() const;
|
||||
```
|
||||
|
||||
获取线程的名称。该名称在调用 Start 时设置。
|
||||
返回线程的名称。线程名称在调用 `Start()` 时通过参数指定，默认为 "Thread"。返回的引用指向内部存储的 `Containers::String` 对象。
|
||||
|
||||
线程名称主要用于调试、日志记录和性能分析工具中标识线程。
|
||||
|
||||
**参数：** 无
|
||||
|
||||
**返回：** `const Containers::String&` - 线程名称的引用
|
||||
**返回：** 线程名称的常量引用
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**注意：** 在调用 Start 之前返回空字符串。
|
||||
**线程安全：** ✅
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
Thread worker;
|
||||
worker.Start([]() {}, "ComputeThread");
|
||||
printf("Thread name: %s\n", worker.GetName().CStr());
|
||||
worker.Join();
|
||||
#include "XCEngine/Threading/Thread.h"
|
||||
#include <iostream>
|
||||
|
||||
using namespace XCEngine::Threading;
|
||||
|
||||
int main() {
|
||||
Thread t1;
|
||||
t1.Start([]() {}, "RenderingThread");
|
||||
|
||||
Thread t2;
|
||||
t2.Start([]() {}, "PhysicsThread");
|
||||
|
||||
Thread t3;
|
||||
t3.Start([]() {});
|
||||
|
||||
std::cout << "Thread 1 name: " << t1.GetName().CStr() << std::endl;
|
||||
std::cout << "Thread 2 name: " << t2.GetName().CStr() << std::endl;
|
||||
std::cout << "Thread 3 name: " << t3.GetName().CStr() << std::endl;
|
||||
|
||||
t1.Join();
|
||||
t2.Join();
|
||||
t3.Join();
|
||||
|
||||
return 0;
|
||||
}
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
@@ -1,35 +1,45 @@
|
||||
# Thread::Join
|
||||
|
||||
```cpp
|
||||
void Join()
|
||||
void Join();
|
||||
```
|
||||
|
||||
等待线程结束并回收其资源。调用线程将被阻塞，直到目标线程完成执行。
|
||||
等待线程执行完成并回收其资源。调用 `Join()` 会阻塞当前线程，直到目标线程结束运行。如果目标线程已经结束或从未启动，则此调用立即返回。
|
||||
|
||||
`Join()` 只能调用一次。在调用 `Join()` 后，`std::thread` 对象不再代表任何线程，不能再次调用 `Join()` 或 `Detach()`。
|
||||
|
||||
析构函数会自动调用 `Join()`，确保线程对象销毁前等待线程结束。
|
||||
|
||||
**注意：** 如果线程已经被分离（Detach）或已经 Join 过，调用此方法将导致未定义行为。
|
||||
|
||||
**参数：** 无
|
||||
|
||||
**返回：** 无
|
||||
|
||||
**复杂度：** O(n)，n 为目标线程的执行时间
|
||||
|
||||
**注意：**
|
||||
- 如果线程已经被分离（Detach）或已经 Join 过，调用此方法将导致未定义行为。
|
||||
- 建议在使用完 Thread 对象后始终调用 Join 或 Detach。
|
||||
**线程安全：** ❌
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
Thread worker;
|
||||
worker.Start([]() {
|
||||
for (int i = 0; i < 5; ++i) {
|
||||
printf("Working...\n");
|
||||
Thread::Sleep(100);
|
||||
}
|
||||
}, "WorkerThread");
|
||||
#include "XCEngine/Threading/Thread.h"
|
||||
#include <iostream>
|
||||
|
||||
printf("Main thread waiting...\n");
|
||||
worker.Join();
|
||||
printf("Worker thread finished\n");
|
||||
using namespace XCEngine::Threading;
|
||||
|
||||
int main() {
|
||||
Thread t;
|
||||
t.Start([]() {
|
||||
for (int i = 0; i < 3; ++i) {
|
||||
std::cout << "Working... " << i << std::endl;
|
||||
Thread::Sleep(100);
|
||||
}
|
||||
}, "WorkerThread");
|
||||
|
||||
std::cout << "Waiting for thread to complete..." << std::endl;
|
||||
t.Join();
|
||||
std::cout << "Thread completed!" << std::endl;
|
||||
return 0;
|
||||
}
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
@@ -1,27 +1,34 @@
|
||||
# Thread::Sleep
|
||||
|
||||
```cpp
|
||||
static void Sleep(uint32_t milliseconds)
|
||||
static void Sleep(uint32_t milliseconds);
|
||||
```
|
||||
|
||||
使当前线程休眠指定的时间。线程在休眠期间不会消耗 CPU 时间。
|
||||
静态方法，使当前线程进入休眠状态指定毫秒数。在休眠期间，线程不会消耗 CPU 时间片，让系统可以将资源分配给其他线程。
|
||||
|
||||
实现基于 `std::this_thread::sleep_for`，使用 `std::chrono::milliseconds` 包装休眠时长。休眠精度取决于操作系统调度器的精度。
|
||||
|
||||
**参数：**
|
||||
- `milliseconds` - 休眠时间，以毫秒为单位
|
||||
- `milliseconds` - 休眠时长，以毫秒为单位
|
||||
|
||||
**返回：** 无
|
||||
|
||||
**复杂度：** 取决于操作系统的调度精度，通常为 O(milliseconds)
|
||||
**线程安全：** ✅
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
printf("Start\n");
|
||||
Thread::Sleep(1000); // 休眠1秒
|
||||
printf("After 1 second\n");
|
||||
#include "XCEngine/Threading/Thread.h"
|
||||
#include <iostream>
|
||||
|
||||
Thread::Sleep(500); // 再休眠0.5秒
|
||||
printf("After 0.5 more seconds\n");
|
||||
using namespace XCEngine::Threading;
|
||||
|
||||
int main() {
|
||||
std::cout << "Sleeping for 500ms..." << std::endl;
|
||||
Thread::Sleep(500);
|
||||
std::cout << "Wake up!" << std::endl;
|
||||
return 0;
|
||||
}
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
@@ -2,34 +2,44 @@
|
||||
|
||||
```cpp
|
||||
template<typename Func>
|
||||
void Start(Func&& func, const Containers::String& name = "Thread")
|
||||
void Start(Func&& func, const Containers::String& name = "Thread");
|
||||
```
|
||||
|
||||
启动线程，执行传入的可调用对象。该方法创建一个新的执行线程，立即开始运行。
|
||||
启动一个新线程并执行传入的可调用对象。该方法是模板方法，可以接受任何可调用对象，包括普通函数、Lambda 表达式、仿函数等。
|
||||
|
||||
调用 `Start()` 后，线程立即开始执行。线程 ID 通过 `native_handle()` 获取并转换为 `uint64_t` 类型。
|
||||
|
||||
**注意：** `Start()` 不是线程安全的，不应在同一 `Thread` 对象上并发调用。
|
||||
|
||||
**参数：**
|
||||
- `func` - 要在线程中执行的可调用对象（lambda、函数指针、仿函数等）
|
||||
- `name` - 线程名称，用于调试和日志输出，默认值为 "Thread"
|
||||
- `func` - 要执行的线程函数，可以是任意可调用对象
|
||||
- `name` - 线程名称，默认为 "Thread"，用于调试和日志记录
|
||||
|
||||
**返回：** 无
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**线程安全：** 该方法不是线程安全的，不应在同一 Thread 对象上并发调用。
|
||||
**线程安全：** ❌
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include "Threading/Thread.h"
|
||||
#include "XCEngine/Threading/Thread.h"
|
||||
#include <iostream>
|
||||
|
||||
Thread worker;
|
||||
worker.Start([]() {
|
||||
printf("Worker thread running\n");
|
||||
Thread::Sleep(100);
|
||||
printf("Worker thread done\n");
|
||||
}, "WorkerThread");
|
||||
using namespace XCEngine::Threading;
|
||||
|
||||
worker.Join();
|
||||
void FreeFunction(int value) {
|
||||
std::cout << "Free function called with: " << value << std::endl;
|
||||
}
|
||||
|
||||
int main() {
|
||||
Thread t;
|
||||
t.Start(FreeFunction, "FreeFuncThread");
|
||||
t.Start([]() {
|
||||
std::cout << "Lambda thread executing" << std::endl;
|
||||
}, "LambdaThread");
|
||||
t.Join();
|
||||
return 0;
|
||||
}
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
@@ -6,24 +6,26 @@
|
||||
|
||||
**头文件**: `XCEngine/Threading/Thread.h`
|
||||
|
||||
**描述**: 线程封装类，提供跨平台线程创建和管理功能。
|
||||
**描述**: 线程类，封装 std::thread 提供命名的线程管理功能。
|
||||
|
||||
## 概述
|
||||
|
||||
`Thread` 类封装了 `std::thread`，提供统一的线程管理接口，包括启动、加入、分离等操作。
|
||||
`Thread` 类封装了 `std::thread`，提供统一的线程管理接口。设计用于跨平台线程创建和管理，支持为线程指定名称便于调试和日志记录。
|
||||
|
||||
## 公共类型
|
||||
类提供实例方法用于启动、等待（Join）和分离（Detach）线程，以及静态工具方法用于获取当前线程 ID、线程睡眠和让出 CPU 时间片。
|
||||
|
||||
| 类型 | 描述 |
|
||||
|------|------|
|
||||
| `using Id = uint64_t` | 线程唯一标识符类型 |
|
||||
## 类型别名
|
||||
|
||||
| 类型 | 定义 | 描述 |
|
||||
|------|------|------|
|
||||
| `Id` | `uint64_t` | 线程唯一标识符类型 |
|
||||
|
||||
## 公共方法
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `Thread()` | 默认构造函数 |
|
||||
| `~Thread()` | 析构函数 |
|
||||
| [`Thread()`](thread.md) | 默认构造函数 |
|
||||
| [`~Thread()`](thread.md) | 析构函数 |
|
||||
| [`Start`](start.md) | 启动线程，执行传入的函数 |
|
||||
| [`Join`](join.md) | 等待线程结束 |
|
||||
| [`Detach`](detach.md) | 分离线程，使其独立运行 |
|
||||
@@ -36,25 +38,28 @@
|
||||
## 使用示例
|
||||
|
||||
```cpp
|
||||
#include "Threading/Thread.h"
|
||||
#include "XCEngine/Threading/Thread.h"
|
||||
|
||||
// 创建并启动线程
|
||||
Thread thread;
|
||||
thread.Start([]() {
|
||||
using namespace XCEngine::Threading;
|
||||
|
||||
void WorkerFunction() {
|
||||
printf("Worker thread running\n");
|
||||
}, "WorkerThread");
|
||||
}
|
||||
|
||||
// 等待线程结束
|
||||
thread.Join();
|
||||
int main() {
|
||||
Thread thread;
|
||||
thread.Start(WorkerFunction, "WorkerThread");
|
||||
thread.Join();
|
||||
|
||||
// 使用静态方法
|
||||
Thread::Sleep(1000); // 休眠1秒
|
||||
Thread::Yield(); // 让出时间片
|
||||
auto currentId = Thread::GetCurrentId();
|
||||
Thread::Sleep(1000);
|
||||
Thread::Yield();
|
||||
auto currentId = Thread::GetCurrentId();
|
||||
return 0;
|
||||
}
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [Mutex](../mutex/mutex.md) - 互斥锁
|
||||
- [TaskSystem](../task-system/task-system.md) - 任务调度系统
|
||||
- [../threading/threading.md](../threading.md) - 模块总览
|
||||
- [../threading.md](../threading.md) - 模块总览
|
||||
|
||||
@@ -1,37 +1,47 @@
|
||||
# Thread::Yield
|
||||
|
||||
```cpp
|
||||
static void Yield()
|
||||
static void Yield();
|
||||
```
|
||||
|
||||
让出当前线程的时间片，允许操作系统调度器将 CPU 时间分配给其他就绪线程。
|
||||
静态方法，向调度器提示当前线程愿意让出 CPU 时间片，让其他线程有机会执行。此方法适用于需要 busy-wait 或自旋等待的场景。
|
||||
|
||||
实现基于 `std::this_thread::yield()`。调度器行为取决于操作系统。
|
||||
|
||||
**警告：** 过度使用 `Yield()` 可能导致性能问题。在多数情况下，使用 `Sleep()` 是更好的选择。
|
||||
|
||||
**参数：** 无
|
||||
|
||||
**返回：** 无
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**使用场景：**
|
||||
- 在自旋等待某个条件时调用，避免浪费 CPU 周期。
|
||||
- 在长时间循环中定期让出时间片，提高其他线程的响应性。
|
||||
**线程安全：** ✅
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
volatile bool ready = false;
|
||||
#include "XCEngine/Threading/Thread.h"
|
||||
#include <atomic>
|
||||
#include <iostream>
|
||||
|
||||
Thread worker;
|
||||
worker.Start([]() {
|
||||
ready = true;
|
||||
}, "WorkerThread");
|
||||
using namespace XCEngine::Threading;
|
||||
|
||||
// 忙等待，但定期让出时间片
|
||||
while (!ready) {
|
||||
Thread::Yield();
|
||||
int main() {
|
||||
std::atomic<bool> ready{false};
|
||||
|
||||
Thread t;
|
||||
t.Start([&ready]() {
|
||||
while (!ready.load()) {
|
||||
Thread::Yield();
|
||||
}
|
||||
std::cout << "Worker: ready flag is set!" << std::endl;
|
||||
}, "YieldWorker");
|
||||
|
||||
Thread::Sleep(100);
|
||||
ready.store(true);
|
||||
|
||||
t.Join();
|
||||
return 0;
|
||||
}
|
||||
|
||||
worker.Join();
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
Reference in New Issue
Block a user