docs: update memory and threading API docs
This commit is contained in:
90
docs/api/threading/task-group/add-dependency.md
Normal file
90
docs/api/threading/task-group/add-dependency.md
Normal file
@@ -0,0 +1,90 @@
|
||||
# TaskGroup::AddDependency
|
||||
|
||||
```cpp
|
||||
void AddDependency(uint64_t taskId, uint64_t dependsOn);
|
||||
```
|
||||
|
||||
为任务添加依赖关系。指定的任务 `taskId` 将在 `dependsOn` 任务完成后才会开始执行。
|
||||
|
||||
**参数：**
|
||||
- `taskId` - 从属任务的 ID
|
||||
- `dependsOn` - 被依赖任务的 ID，taskId 将在此任务完成后才执行
|
||||
|
||||
**返回：** 无
|
||||
|
||||
**线程安全：** ✅ 线程安全
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include "XCEngine/Threading/TaskGroup.h"
|
||||
#include "XCEngine/Threading/Task.h"
|
||||
#include <iostream>
|
||||
#include <memory>
|
||||
|
||||
using namespace XCEngine::Threading;
|
||||
|
||||
int main() {
|
||||
TaskGroup group;
|
||||
|
||||
uint64_t loadData = group.AddTask(
|
||||
[]() { std::cout << "Loading data...\n"; },
|
||||
TaskPriority::High
|
||||
);
|
||||
|
||||
uint64_t processData = group.AddTask(
|
||||
[]() { std::cout << "Processing data...\n"; },
|
||||
TaskPriority::Normal
|
||||
);
|
||||
|
||||
uint64_t saveData = group.AddTask(
|
||||
[]() { std::cout << "Saving data...\n"; },
|
||||
TaskPriority::Low
|
||||
);
|
||||
|
||||
group.AddDependency(processData, loadData);
|
||||
group.AddDependency(saveData, processData);
|
||||
|
||||
std::cout << "Execution order: loadData -> processData -> saveData\n";
|
||||
|
||||
group.Wait();
|
||||
return 0;
|
||||
}
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [TaskGroup 总览](task-group.md) - 返回类总览
|
||||
|
||||
## 详细描述
|
||||
|
||||
`AddDependency` 方法用于设置任务间的依赖关系。`taskId` 指定的任务将等待 `dependsOn` 指定的任务完成后才能开始执行。
|
||||
|
||||
依赖关系必须在任务执行前设置，建议在所有任务添加完成后统一设置依赖。
|
||||
|
||||
## 参数
|
||||
|
||||
| 参数 | 类型 | 描述 |
|
||||
|------|------|------|
|
||||
| `taskId` | `uint64_t` | 依赖其他任务的任务ID |
|
||||
| `dependsOn` | `uint64_t` | 被依赖的任务ID |
|
||||
|
||||
## 返回值
|
||||
|
||||
无
|
||||
|
||||
## 示例
|
||||
|
||||
```cpp
|
||||
TaskGroup* group = TaskSystem::Get().CreateTaskGroup();
|
||||
|
||||
uint64_t loadData = group->AddTask([]() { /* 加载数据 */ });
|
||||
uint64_t processData = group->AddTask([]() { /* 处理数据 */ });
|
||||
uint64_t saveData = group->AddTask([]() { /* 保存数据 */ });
|
||||
|
||||
// processData必须在loadData完成后才能执行
|
||||
group->AddDependency(processData, loadData);
|
||||
|
||||
// saveData必须在processData完成后才能执行
|
||||
group->AddDependency(saveData, processData);
|
||||
```
|
||||
55
docs/api/threading/task-group/add-task-callback.md
Normal file
55
docs/api/threading/task-group/add-task-callback.md
Normal file
@@ -0,0 +1,55 @@
|
||||
# TaskGroup::AddTask (Callback)
|
||||
|
||||
```cpp
|
||||
uint64_t AddTask(Callback&& func, TaskPriority priority = TaskPriority::Normal);
|
||||
```
|
||||
|
||||
将函数回调添加为任务。该方法接受一个可调用对象（lambda、函数指针、std::function 等）作为任务执行体。
|
||||
|
||||
**参数：**
|
||||
- `func` - 可调用对象，执行任务逻辑
|
||||
- `priority` - 任务优先级，默认为 Normal
|
||||
|
||||
**返回：** 返回分配给任务的唯一 ID，可用于后续添加依赖关系
|
||||
|
||||
**线程安全：** ✅ 线程安全
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include "XCEngine/Threading/TaskGroup.h"
|
||||
#include "XCEngine/Threading/Task.h"
|
||||
#include <iostream>
|
||||
|
||||
using namespace XCEngine::Threading;
|
||||
|
||||
int main() {
|
||||
TaskGroup group;
|
||||
|
||||
uint64_t task1 = group.AddTask(
|
||||
[]() { std::cout << "Task 1 executing\n"; },
|
||||
TaskPriority::Normal
|
||||
);
|
||||
|
||||
uint64_t task2 = group.AddTask(
|
||||
[]() { std::cout << "Task 2 executing (High priority)\n"; },
|
||||
TaskPriority::High
|
||||
);
|
||||
|
||||
uint64_t task3 = group.AddTask(
|
||||
[]() { std::cout << "Task 3 executing (Low priority)\n"; },
|
||||
TaskPriority::Low
|
||||
);
|
||||
|
||||
group.AddDependency(task2, task1);
|
||||
|
||||
group.Wait();
|
||||
return 0;
|
||||
}
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [TaskGroup 总览](task-group.md) - 返回类总览
|
||||
- [AddTask(ITask)](add-task.md) - 添加 ITask 对象形式的任务
|
||||
- [TaskPriority](task-priority.md) - 任务优先级说明
|
||||
62
docs/api/threading/task-group/add-task.md
Normal file
62
docs/api/threading/task-group/add-task.md
Normal file
@@ -0,0 +1,62 @@
|
||||
# TaskGroup::AddTask
|
||||
|
||||
```cpp
|
||||
uint64_t AddTask(std::unique_ptr<ITask> task);
|
||||
uint64_t AddTask(Callback&& func, TaskPriority priority = TaskPriority::Normal);
|
||||
```
|
||||
|
||||
将任务添加到任务组。支持两种添加方式：传入 ITask 对象或传入回调函数。
|
||||
|
||||
**参数：**
|
||||
- `task` - 唯一指针管理的 ITask 对象
|
||||
- `func` - 要执行的回调函数
|
||||
- `priority` - 任务优先级，默认为 `TaskPriority::Normal`
|
||||
|
||||
**返回：** 返回分配的任务 ID，可用于设置依赖关系
|
||||
|
||||
**线程安全：** ✅ 线程安全
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include "XCEngine/Threading/TaskGroup.h"
|
||||
#include "XCEngine/Threading/Task.h"
|
||||
#include <iostream>
|
||||
#include <memory>
|
||||
|
||||
using namespace XCEngine::Threading;
|
||||
|
||||
class MyTask : public ITask {
|
||||
public:
|
||||
explicit MyTask(const std::string& name) : m_name(name) {}
|
||||
|
||||
void Execute() override {
|
||||
std::cout << "Executing: " << m_name << "\n";
|
||||
}
|
||||
|
||||
private:
|
||||
std::string m_name;
|
||||
};
|
||||
|
||||
int main() {
|
||||
TaskGroup group;
|
||||
|
||||
auto task = std::make_unique<MyTask>("DataLoading");
|
||||
uint64_t taskId = group.AddTask(std::move(task));
|
||||
|
||||
uint64_t callbackId = group.AddTask([]() {
|
||||
std::cout << "Lambda task executing\n";
|
||||
}, TaskPriority::High);
|
||||
|
||||
group.AddDependency(callbackId, taskId);
|
||||
|
||||
group.Wait();
|
||||
return 0;
|
||||
}
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [TaskGroup 总览](task-group.md) - 返回类总览
|
||||
@@ -1,44 +0,0 @@
|
||||
# TaskGroup::AddDependency
|
||||
|
||||
```cpp
|
||||
void AddDependency(uint64_t taskId, uint64_t dependsOn)
|
||||
```
|
||||
|
||||
为任务添加依赖关系。被依赖的任务必须先完成，当前任务才会开始执行。
|
||||
|
||||
**参数：**
|
||||
- `taskId` - 任务 ID（需要等待的任务）
|
||||
- `dependsOn` - 依赖的父任务 ID
|
||||
|
||||
**返回：** 无
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**注意：**
|
||||
- 如果被依赖的任务不存在或已完成，调用无效果。
|
||||
- 支持添加多个依赖，但不支持循环依赖。
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
TaskGroup* group = TaskSystem::Get().CreateTaskGroup();
|
||||
|
||||
uint64_t init = group->AddTask([]() { Initialize(); });
|
||||
uint64_t task1 = group->AddTask([]() { Phase1(); });
|
||||
uint64_t task2 = group->AddTask([]() { Phase2(); });
|
||||
uint64_t cleanup = group->AddTask([]() { Cleanup(); });
|
||||
|
||||
// task1 和 task2 依赖 init
|
||||
group->AddDependency(task1, init);
|
||||
group->AddDependency(task2, init);
|
||||
|
||||
// cleanup 依赖 task1 和 task2
|
||||
group->AddDependency(cleanup, task1);
|
||||
group->AddDependency(cleanup, task2);
|
||||
|
||||
group->Wait();
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [TaskGroup 总览](task-group.md) - 返回类总览
|
||||
@@ -1,60 +0,0 @@
|
||||
# TaskGroup::AddTask
|
||||
|
||||
添加任务到任务组。有两个重载版本。
|
||||
|
||||
## 重载 1: 添加 ITask 对象
|
||||
|
||||
```cpp
|
||||
uint64_t AddTask(std::unique_ptr<ITask> task)
|
||||
```
|
||||
|
||||
将一个已有的 ITask 对象添加到任务组。
|
||||
|
||||
**参数：**
|
||||
- `task` - 要添加的 unique_ptr 任务对象
|
||||
|
||||
**返回：** `uint64_t` - 分配的任务 ID
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
## 重载 2: 添加 lambda 任务
|
||||
|
||||
```cpp
|
||||
uint64_t AddTask(Callback&& func, TaskPriority priority = TaskPriority::Normal)
|
||||
```
|
||||
|
||||
将一个 lambda 函数包装为任务添加到任务组。
|
||||
|
||||
**参数：**
|
||||
- `func` - 要执行的可调用对象
|
||||
- `priority` - 任务优先级，默认 TaskPriority::Normal
|
||||
|
||||
**返回：** `uint64_t` - 分配的任务 ID
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
TaskGroup* group = TaskSystem::Get().CreateTaskGroup();
|
||||
|
||||
// 添加 lambda 任务
|
||||
uint64_t id1 = group->AddTask([]() {
|
||||
printf("Task A running\n");
|
||||
});
|
||||
|
||||
uint64_t id2 = group->AddTask([]() {
|
||||
printf("Task B running\n");
|
||||
}, TaskPriority::High);
|
||||
|
||||
// 添加自定义 ITask
|
||||
class MyTask : public ITask {
|
||||
public:
|
||||
void Execute() override { printf("Custom task\n"); }
|
||||
};
|
||||
uint64_t id3 = group->AddTask(std::make_unique<MyTask>());
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [TaskGroup 总览](task-group.md) - 返回类总览
|
||||
@@ -1,43 +1,47 @@
|
||||
# TaskGroup::Cancel
|
||||
|
||||
```cpp
|
||||
void Cancel()
|
||||
void Cancel();
|
||||
```
|
||||
|
||||
**注意：** 此方法为**部分实现**，存在已知问题。
|
||||
|
||||
取消任务组中所有尚未执行的任务。正在执行的任务将不受影响。
|
||||
取消任务组中所有尚未开始执行的任务。已经执行完成的任务和正在执行的任务不受影响。
|
||||
|
||||
**参数：** 无
|
||||
|
||||
**返回：** 无
|
||||
|
||||
**复杂度：** O(n)
|
||||
|
||||
**当前状态：** 此方法会调用各任务的 `OnCancel()` 回调，但不会减少 `m_pendingCount` 计数器。因此调用 `Wait()` 会导致永久阻塞。建议在 `Cancel()` 后使用 `IsComplete()` 轮询或使用带超时的 `WaitFor()`。
|
||||
**线程安全：** ✅ 线程安全
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
TaskGroup* group = TaskSystem::Get().CreateTaskGroup();
|
||||
#include "XCEngine/Threading/TaskGroup.h"
|
||||
#include "XCEngine/Threading/Task.h"
|
||||
#include <iostream>
|
||||
#include <chrono>
|
||||
|
||||
for (int i = 0; i < 100; ++i) {
|
||||
group->AddTask([i]() {
|
||||
if (ShouldCancel()) {
|
||||
return; // 检查取消状态
|
||||
}
|
||||
ProcessLongTask(i);
|
||||
});
|
||||
using namespace XCEngine::Threading;
|
||||
|
||||
int main() {
|
||||
TaskGroup group;
|
||||
|
||||
for (int i = 0; i < 10; ++i) {
|
||||
group.AddTask([i]() {
|
||||
std::cout << "Task " << i << " executing\n";
|
||||
std::this_thread::sleep_for(std::chrono::milliseconds(100));
|
||||
});
|
||||
}
|
||||
|
||||
std::this_thread::sleep_for(std::chrono::milliseconds(150));
|
||||
|
||||
std::cout << "Cancelling remaining tasks...\n";
|
||||
group.Cancel();
|
||||
|
||||
group.Wait();
|
||||
std::cout << "Tasks cancelled. Final progress: " << (group.GetProgress() * 100) << "%\n";
|
||||
|
||||
return 0;
|
||||
}
|
||||
|
||||
// 如果用户点击取消按钮
|
||||
if (userClickedCancel) {
|
||||
group->Cancel();
|
||||
printf("Tasks canceled. Progress: %.1f%%\n", group->GetProgress() * 100.0f);
|
||||
}
|
||||
|
||||
// 注意：Cancel() 后 Wait() 会永久阻塞，应使用 WaitFor()
|
||||
group->WaitFor(std::chrono::seconds(1));
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
50
docs/api/threading/task-group/get-progress.md
Normal file
50
docs/api/threading/task-group/get-progress.md
Normal file
@@ -0,0 +1,50 @@
|
||||
# TaskGroup::GetProgress
|
||||
|
||||
```cpp
|
||||
float GetProgress() const;
|
||||
```
|
||||
|
||||
获取任务组的完成进度。
|
||||
|
||||
**参数：** 无
|
||||
|
||||
**返回：**
|
||||
- `float` - 0.0 到 1.0 之间的进度值，0.0 表示没有任务或都没有完成，1.0 表示全部完成
|
||||
|
||||
**线程安全：** ✅ 线程安全
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include "XCEngine/Threading/TaskGroup.h"
|
||||
#include "XCEngine/Threading/Task.h"
|
||||
#include <iostream>
|
||||
#include <chrono>
|
||||
|
||||
using namespace XCEngine::Threading;
|
||||
|
||||
int main() {
|
||||
TaskGroup group;
|
||||
|
||||
for (int i = 0; i < 4; ++i) {
|
||||
group.AddTask([i]() {
|
||||
std::this_thread::sleep_for(std::chrono::milliseconds(100));
|
||||
});
|
||||
}
|
||||
|
||||
while (!group.IsComplete()) {
|
||||
float progress = group.GetProgress();
|
||||
std::cout << "Progress: " << (progress * 100) << "%\n";
|
||||
std::this_thread::sleep_for(std::chrono::milliseconds(50));
|
||||
}
|
||||
|
||||
std::cout << "Final Progress: " << (group.GetProgress() * 100) << "%\n";
|
||||
|
||||
return 0;
|
||||
}
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [TaskGroup 总览](task-group.md) - 返回类总览
|
||||
- [IsComplete](is-complete.md) - 检查是否完成
|
||||
@@ -1,40 +0,0 @@
|
||||
# TaskGroup::GetProgress
|
||||
|
||||
```cpp
|
||||
float GetProgress() const
|
||||
```
|
||||
|
||||
**注意：** 此方法当前为**空实现/桩代码**。
|
||||
|
||||
获取任务组的完成进度。
|
||||
|
||||
**参数：** 无
|
||||
|
||||
**返回：** `float` - 始终返回 `0.0f`（任务组为空时返回 `1.0f`）
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**当前状态：** 此方法为空实现，始终返回 `0.0f`，因为 `m_completedCount` 未被更新。
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
TaskGroup* group = TaskSystem::Get().CreateTaskGroup();
|
||||
|
||||
for (int i = 0; i < 1000; ++i) {
|
||||
group->AddTask([i]() { ProcessItem(i); });
|
||||
}
|
||||
|
||||
// 显示进度（注意：当前实现始终返回 0.0f）
|
||||
while (!group->IsComplete()) {
|
||||
float progress = group->GetProgress();
|
||||
printf("\rProgress: %.1f%%", progress * 100.0f);
|
||||
Thread::Sleep(100);
|
||||
}
|
||||
printf("\n");
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [TaskGroup 总览](task-group.md) - 返回类总览
|
||||
- [IsComplete](iscomplete.md) - 检查是否完成
|
||||
50
docs/api/threading/task-group/is-complete.md
Normal file
50
docs/api/threading/task-group/is-complete.md
Normal file
@@ -0,0 +1,50 @@
|
||||
# TaskGroup::IsComplete
|
||||
|
||||
```cpp
|
||||
bool IsComplete() const;
|
||||
```
|
||||
|
||||
检查任务组中的所有任务是否已完成。
|
||||
|
||||
**参数：** 无
|
||||
|
||||
**返回：**
|
||||
- `true` - 所有任务已完成（包括被取消的）
|
||||
- `false` - 仍有任务在执行或等待执行
|
||||
|
||||
**线程安全：** ✅ 线程安全
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include "XCEngine/Threading/TaskGroup.h"
|
||||
#include "XCEngine/Threading/Task.h"
|
||||
#include <iostream>
|
||||
#include <chrono>
|
||||
|
||||
using namespace XCEngine::Threading;
|
||||
|
||||
int main() {
|
||||
TaskGroup group;
|
||||
|
||||
group.AddTask([]() {
|
||||
std::this_thread::sleep_for(std::chrono::milliseconds(100));
|
||||
std::cout << "Task completed\n";
|
||||
});
|
||||
|
||||
std::cout << "Immediately after AddTask, IsComplete: "
|
||||
<< (group.IsComplete() ? "true" : "false") << "\n";
|
||||
|
||||
group.Wait();
|
||||
|
||||
std::cout << "After Wait, IsComplete: "
|
||||
<< (group.IsComplete() ? "true" : "false") << "\n";
|
||||
|
||||
return 0;
|
||||
}
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [TaskGroup 总览](task-group.md) - 返回类总览
|
||||
- [GetProgress](get-progress.md) - 获取进度百分比
|
||||
@@ -1,38 +0,0 @@
|
||||
# TaskGroup::IsComplete
|
||||
|
||||
```cpp
|
||||
bool IsComplete() const
|
||||
```
|
||||
|
||||
**注意：** 此方法当前为**空实现/桩代码**。
|
||||
|
||||
检查任务组中所有任务是否已完成。
|
||||
|
||||
**参数：** 无
|
||||
|
||||
**返回：** `bool` - 始终返回 `false`（空实现）
|
||||
|
||||
**复杂度：** O(1)（空实现）
|
||||
|
||||
**当前状态：** 此方法为空实现，始终返回 `false`，因为 `m_pendingCount` 计数器未正确递减。
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
TaskGroup* group = TaskSystem::Get().CreateTaskGroup();
|
||||
|
||||
for (int i = 0; i < 100; ++i) {
|
||||
group->AddTask([i]() { HeavyCompute(i); });
|
||||
}
|
||||
|
||||
// 非阻塞轮询
|
||||
while (!group->IsComplete()) {
|
||||
printf("Progress: %.1f%%\n", group->GetProgress() * 100.0f);
|
||||
Thread::Sleep(500);
|
||||
}
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [TaskGroup 总览](task-group.md) - 返回类总览
|
||||
- [GetProgress](getprogress.md) - 获取完成进度
|
||||
82
docs/api/threading/task-group/set-complete-callback.md
Normal file
82
docs/api/threading/task-group/set-complete-callback.md
Normal file
@@ -0,0 +1,82 @@
|
||||
# TaskGroup::SetCompleteCallback
|
||||
|
||||
```cpp
|
||||
void SetCompleteCallback(Callback&& callback);
|
||||
```
|
||||
|
||||
设置任务组完成时的回调函数。当所有任务都执行完成后（包括被取消的任务），该回调将被调用。
|
||||
|
||||
**参数：**
|
||||
- `callback` - 可调用对象，在所有任务完成后执行
|
||||
|
||||
**返回：** 无
|
||||
|
||||
**线程安全：** ✅ 线程安全
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include "XCEngine/Threading/TaskGroup.h"
|
||||
#include "XCEngine/Threading/Task.h"
|
||||
#include <iostream>
|
||||
|
||||
using namespace XCEngine::Threading;
|
||||
|
||||
int main() {
|
||||
TaskGroup group;
|
||||
|
||||
group.SetCompleteCallback([]() {
|
||||
std::cout << "All tasks have been completed!\n";
|
||||
});
|
||||
|
||||
for (int i = 0; i < 3; ++i) {
|
||||
group.AddTask([i]() {
|
||||
std::cout << "Task " << i << " executing\n";
|
||||
});
|
||||
}
|
||||
|
||||
group.Wait();
|
||||
std::cout << "Back in main after Wait()\n";
|
||||
|
||||
return 0;
|
||||
}
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [TaskGroup 总览](task-group.md) - 返回类总览
|
||||
|
||||
## 详细描述
|
||||
|
||||
`SetCompleteCallback` 方法用于设置当任务组中所有任务都完成时调用的回调函数。回调在最后一个任务完成时触发。
|
||||
|
||||
## 参数
|
||||
|
||||
| 参数 | 类型 | 描述 |
|
||||
|------|------|------|
|
||||
| `callback` | `Callback&&` | 回调函数，类型为 `std::function<void()>` |
|
||||
|
||||
## 返回值
|
||||
|
||||
无
|
||||
|
||||
## 示例
|
||||
|
||||
```cpp
|
||||
TaskGroup* group = TaskSystem::Get().CreateTaskGroup();
|
||||
|
||||
group->SetCompleteCallback([]() {
|
||||
printf("All tasks in group have completed!\n");
|
||||
});
|
||||
|
||||
for (int i = 0; i < 10; ++i) {
|
||||
group->AddTask([i]() {
|
||||
printf("Task %d completed\n", i);
|
||||
});
|
||||
}
|
||||
|
||||
// 等待所有任务完成，回调会被触发
|
||||
group->Wait();
|
||||
|
||||
TaskSystem::Get().DestroyTaskGroup(group);
|
||||
```
|
||||
@@ -1,36 +0,0 @@
|
||||
# TaskGroup::SetCompleteCallback
|
||||
|
||||
```cpp
|
||||
void SetCompleteCallback(Callback&& callback)
|
||||
```
|
||||
|
||||
设置任务组完成回调。当所有任务都完成后，回调函数将在某个工作线程中被调用。
|
||||
|
||||
**参数：**
|
||||
- `callback` - 完成时要调用的回调函数
|
||||
|
||||
**返回：** 无
|
||||
|
||||
**复杂度：** O(1)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
TaskGroup* group = TaskSystem::Get().CreateTaskGroup();
|
||||
|
||||
group->AddTask([]() { LoadTextures(); });
|
||||
group->AddTask([]() { LoadMeshes(); });
|
||||
group->AddTask([]() { LoadAudio(); });
|
||||
|
||||
group->SetCompleteCallback([]() {
|
||||
printf("All assets loaded!\n");
|
||||
ResourceManager::InitGPUResources();
|
||||
});
|
||||
|
||||
group->Wait();
|
||||
TaskSystem::Get().DestroyTaskGroup(group);
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [TaskGroup 总览](task-group.md) - 返回类总览
|
||||
@@ -6,61 +6,83 @@
|
||||
|
||||
**头文件**: `XCEngine/Threading/TaskGroup.h`
|
||||
|
||||
**描述**: 任务组管理类，用于组织多个任务并支持批量等待、进度跟踪和依赖管理。
|
||||
**描述**: 管理一组相关任务的执行和同步
|
||||
|
||||
## 概述
|
||||
|
||||
`TaskGroup` 提供了一种批量管理任务的机制。它允许添加多个任务、设置任务依赖关系、等待所有任务完成，并提供进度回调功能。
|
||||
TaskGroup 用于将多个相关任务组织在一起，统一管理它们的执行和同步。任务组内的任务可以声明依赖关系，确保任务按照正确的顺序执行。支持任务优先级设置、完成回调、进度查询和取消操作。
|
||||
|
||||
## 公共类型
|
||||
|
||||
| 类型 | 描述 |
|
||||
|------|------|
|
||||
| `Callback = std::function<void()>` | 任务组回调函数类型 |
|
||||
主要功能：
|
||||
- 添加任务（ITask 对象或函数回调）
|
||||
- 声明任务间依赖关系
|
||||
- 等待所有任务完成
|
||||
- 设置完成回调
|
||||
- 查询完成进度
|
||||
- 取消未执行的任务
|
||||
|
||||
## 公共方法
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| `TaskGroup()` | 默认构造函数 |
|
||||
| `~TaskGroup()` | 析构函数 |
|
||||
| [`AddTask(unique_ptr)`](addtask.md) | 添加任务对象 |
|
||||
| [`AddTask(callback)`](addtask.md) | 添加 lambda 任务 |
|
||||
| [`AddDependency`](adddependency.md) | 添加任务依赖关系 |
|
||||
| [`Task()`](task-group.md) | 默认构造函数 |
|
||||
| [`~Task()`](task-group.md) | 析构函数 |
|
||||
| [`AddTask`](add-task.md) | 添加任务到组（支持 ITask 或 Callback） |
|
||||
| [`AddDependency`](add-dependency.md) | 添加任务依赖关系 |
|
||||
| [`Wait`](wait.md) | 阻塞等待所有任务完成 |
|
||||
| [`WaitFor`](waitfor.md) | 超时等待 |
|
||||
| [`SetCompleteCallback`](setcompletecallback.md) | 设置完成回调 |
|
||||
| [`IsComplete`](iscomplete.md) | 检查所有任务是否完成 |
|
||||
| [`GetProgress`](getprogress.md) | 获取完成进度（0.0f ~ 1.0f） |
|
||||
| [`Cancel`](cancel.md) | 取消所有任务 |
|
||||
| [`WaitFor`](wait-for.md) | 等待指定超时时间 |
|
||||
| [`SetCompleteCallback`](set-complete-callback.md) | 设置完成回调函数 |
|
||||
| [`IsComplete`](is-complete.md) | 检查所有任务是否完成 |
|
||||
| [`GetProgress`](get-progress.md) | 获取任务组完成进度 |
|
||||
| [`Cancel`](cancel.md) | 取消所有未执行的任务 |
|
||||
|
||||
## 使用示例
|
||||
|
||||
```cpp
|
||||
TaskGroup* group = TaskSystem::Get().CreateTaskGroup();
|
||||
#include "XCEngine/Threading/TaskGroup.h"
|
||||
#include "XCEngine/Threading/Task.h"
|
||||
#include <iostream>
|
||||
|
||||
// 添加多个任务
|
||||
uint64_t task1 = group->AddTask([]() { /* 任务1 */ });
|
||||
uint64_t task2 = group->AddTask([]() { /* 任务2 */ });
|
||||
using namespace XCEngine::Threading;
|
||||
|
||||
// 设置依赖：task3 等待 task1 完成
|
||||
uint64_t task3 = group->AddTask([]() { /* 任务3 */ });
|
||||
group->AddDependency(task3, task1);
|
||||
class MyTask : public ITask {
|
||||
public:
|
||||
explicit MyTask(const std::string& name) : m_name(name) {}
|
||||
|
||||
// 设置完成回调
|
||||
group->SetCompleteCallback([]() {
|
||||
printf("All tasks completed!\n");
|
||||
});
|
||||
void Execute() override {
|
||||
std::cout << "Task " << m_name << " executing\n";
|
||||
}
|
||||
|
||||
// 等待完成
|
||||
group->Wait();
|
||||
void OnComplete() override {
|
||||
std::cout << "Task " << m_name << " completed\n";
|
||||
}
|
||||
|
||||
// 销毁
|
||||
TaskSystem::Get().DestroyTaskGroup(group);
|
||||
private:
|
||||
std::string m_name;
|
||||
};
|
||||
|
||||
int main() {
|
||||
TaskGroup group;
|
||||
|
||||
uint64_t task1 = group.AddTask(std::make_unique<MyTask>("Task1"));
|
||||
uint64_t task2 = group.AddTask([]() {
|
||||
std::cout << "Lambda task executing\n";
|
||||
}, TaskPriority::High);
|
||||
|
||||
group.AddDependency(task2, task1);
|
||||
|
||||
group.SetCompleteCallback([]() {
|
||||
std::cout << "All tasks completed!\n";
|
||||
});
|
||||
|
||||
group.Wait();
|
||||
|
||||
std::cout << "Progress: " << group.GetProgress() * 100 << "%\n";
|
||||
|
||||
return 0;
|
||||
}
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [ITask](../task/task.md) - 任务基类
|
||||
- [TaskSystem](../task-system/task-system.md) - 任务系统
|
||||
- [../threading/threading.md](../threading.md) - 模块总览
|
||||
- [ITask](../task/task.md) - 任务接口基类
|
||||
- [TaskSystem](../task-system/task-system.md) - 任务调度系统
|
||||
|
||||
59
docs/api/threading/task-group/task-priority.md
Normal file
59
docs/api/threading/task-group/task-priority.md
Normal file
@@ -0,0 +1,59 @@
|
||||
# TaskPriority
|
||||
|
||||
**命名空间**: `XCEngine::Threading`
|
||||
|
||||
**类型**: `enum class`
|
||||
|
||||
**头文件**: `XCEngine/Threading/Task.h`
|
||||
|
||||
## 概述
|
||||
|
||||
`TaskPriority` 定义了任务的优先级，用于控制任务在任务系统中的执行顺序。优先级较高的任务会在优先级较低的任务之前执行。
|
||||
|
||||
## 枚举值
|
||||
|
||||
| 枚举值 | 数值 | 描述 |
|
||||
|--------|------|------|
|
||||
| `Critical` | 0 | 最高优先级，关键任务 |
|
||||
| `High` | 1 | 高优先级 |
|
||||
| `Normal` | 2 | 普通优先级（默认） |
|
||||
| `Low` | 3 | 低优先级 |
|
||||
| `Idle` | 4 | 最低优先级，仅在无其他任务时执行 |
|
||||
|
||||
## 使用示例
|
||||
|
||||
```cpp
|
||||
#include "XCEngine/Threading/TaskGroup.h"
|
||||
#include "XCEngine/Threading/Task.h"
|
||||
#include <iostream>
|
||||
|
||||
using namespace XCEngine::Threading;
|
||||
|
||||
int main() {
|
||||
TaskGroup group;
|
||||
|
||||
group.AddTask([]() {
|
||||
std::cout << "Critical task\n";
|
||||
}, TaskPriority::Critical);
|
||||
|
||||
group.AddTask([]() {
|
||||
std::cout << "High priority task\n";
|
||||
}, TaskPriority::High);
|
||||
|
||||
group.AddTask([]() {
|
||||
std::cout << "Normal task\n";
|
||||
}, TaskPriority::Normal);
|
||||
|
||||
group.AddTask([]() {
|
||||
std::cout << "Low priority task\n";
|
||||
}, TaskPriority::Low);
|
||||
|
||||
group.Wait();
|
||||
return 0;
|
||||
}
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [TaskGroup 总览](task-group.md) - 任务组类总览
|
||||
- [ITask](../task/task.md) - 任务接口基类
|
||||
89
docs/api/threading/task-group/wait-for.md
Normal file
89
docs/api/threading/task-group/wait-for.md
Normal file
@@ -0,0 +1,89 @@
|
||||
# TaskGroup::WaitFor
|
||||
|
||||
```cpp
|
||||
bool WaitFor(std::chrono::milliseconds timeout);
|
||||
```
|
||||
|
||||
等待任务组中的所有任务完成，最多等待指定的超时时间。
|
||||
|
||||
**参数：**
|
||||
- `timeout` - 最大等待时间
|
||||
|
||||
**返回：**
|
||||
- `true` - 所有任务在超时前已完成
|
||||
- `false` - 等待超时，仍有任务未完成
|
||||
|
||||
**线程安全：** ✅ 线程安全
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include "XCEngine/Threading/TaskGroup.h"
|
||||
#include "XCEngine/Threading/Task.h"
|
||||
#include <iostream>
|
||||
#include <chrono>
|
||||
|
||||
using namespace XCEngine::Threading;
|
||||
|
||||
int main() {
|
||||
TaskGroup group;
|
||||
|
||||
group.AddTask([]() {
|
||||
std::this_thread::sleep_for(std::chrono::seconds(5));
|
||||
std::cout << "Long running task completed\n";
|
||||
});
|
||||
|
||||
std::cout << "Waiting with 1 second timeout...\n";
|
||||
|
||||
if (group.WaitFor(std::chrono::milliseconds(1000))) {
|
||||
std::cout << "All tasks completed within timeout\n";
|
||||
} else {
|
||||
std::cout << "Timeout! Some tasks still running.\n";
|
||||
}
|
||||
|
||||
group.Wait();
|
||||
std::cout << "All tasks finally completed after second wait.\n";
|
||||
|
||||
return 0;
|
||||
}
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [TaskGroup 总览](task-group.md) - 返回类总览
|
||||
- [Wait](wait.md) - 无限等待
|
||||
|
||||
## 详细描述
|
||||
|
||||
`WaitFor` 方法会阻塞当前线程，直到所有任务完成或超过指定的超时时间。
|
||||
|
||||
## 参数
|
||||
|
||||
| 参数 | 类型 | 描述 |
|
||||
|------|------|------|
|
||||
| `timeout` | `std::chrono::milliseconds` | 超时时间（毫秒） |
|
||||
|
||||
## 返回值
|
||||
|
||||
返回 `bool` 类型：
|
||||
- `true`: 所有任务在超时前完成
|
||||
- `false`: 发生超时
|
||||
|
||||
## 示例
|
||||
|
||||
```cpp
|
||||
TaskGroup* group = TaskSystem::Get().CreateTaskGroup();
|
||||
|
||||
group->AddTask([]() {
|
||||
std::this_thread::sleep_for(std::chrono::seconds(5));
|
||||
});
|
||||
|
||||
// 等待3秒超时
|
||||
if (group->WaitFor(std::chrono::milliseconds(3000))) {
|
||||
printf("All tasks completed on time\n");
|
||||
} else {
|
||||
printf("Wait timed out\n");
|
||||
}
|
||||
|
||||
TaskSystem::Get().DestroyTaskGroup(group);
|
||||
```
|
||||
@@ -1,46 +1,47 @@
|
||||
# TaskGroup::Wait
|
||||
|
||||
```cpp
|
||||
void Wait()
|
||||
void Wait();
|
||||
```
|
||||
|
||||
**注意：** 此方法当前为**空实现/桩代码**，不执行任何操作。
|
||||
|
||||
阻塞当前线程，等待任务组中所有任务完成。
|
||||
阻塞当前线程，直到任务组中的所有任务完成执行。
|
||||
|
||||
**参数：** 无
|
||||
|
||||
**返回：** 无
|
||||
|
||||
**复杂度：** N/A（空实现）
|
||||
|
||||
**当前状态：** 此方法为空实现，不执行任何操作。由于 `m_pendingCount` 计数器未正确更新，此方法永远无法正常运作。
|
||||
|
||||
**建议：** 使用 `WaitFor()` 代替以避免永久阻塞。
|
||||
**线程安全：** ✅ 线程安全
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
TaskGroup* group = TaskSystem::Get().CreateTaskGroup();
|
||||
#include "XCEngine/Threading/TaskGroup.h"
|
||||
#include "XCEngine/Threading/Task.h"
|
||||
#include <iostream>
|
||||
#include <chrono>
|
||||
|
||||
for (int i = 0; i < 10; ++i) {
|
||||
group->AddTask([i]() {
|
||||
printf("Task %d running\n", i);
|
||||
});
|
||||
using namespace XCEngine::Threading;
|
||||
|
||||
int main() {
|
||||
TaskGroup group;
|
||||
|
||||
for (int i = 0; i < 5; ++i) {
|
||||
group.AddTask([i]() {
|
||||
std::cout << "Task " << i << " started\n";
|
||||
std::this_thread::sleep_for(std::chrono::milliseconds(100));
|
||||
std::cout << "Task " << i << " finished\n";
|
||||
});
|
||||
}
|
||||
|
||||
std::cout << "Waiting for all tasks...\n";
|
||||
group.Wait();
|
||||
std::cout << "All tasks completed!\n";
|
||||
|
||||
return 0;
|
||||
}
|
||||
|
||||
printf("Waiting for all tasks...\n");
|
||||
// 注意：Wait() 为空实现，建议使用 WaitFor()
|
||||
if (group->WaitFor(std::chrono::seconds(5))) {
|
||||
printf("All tasks completed within 5 seconds\n");
|
||||
} else {
|
||||
printf("Timeout! Tasks may not have completed\n");
|
||||
}
|
||||
|
||||
TaskSystem::Get().DestroyTaskGroup(group);
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [TaskGroup 总览](task-group.md) - 返回类总览
|
||||
- [WaitFor](waitfor.md) - 超时等待
|
||||
- [WaitFor](wait-for.md) - 带超时的等待
|
||||
|
||||
@@ -1,39 +0,0 @@
|
||||
# TaskGroup::WaitFor
|
||||
|
||||
```cpp
|
||||
bool WaitFor(std::chrono::milliseconds timeout)
|
||||
```
|
||||
|
||||
等待任务组中所有任务完成，可在超时后返回。
|
||||
|
||||
**参数：**
|
||||
- `timeout` - 最大等待时间
|
||||
|
||||
**返回：** `bool` - 所有任务在超时前完成返回 true，超时返回 false
|
||||
|
||||
**复杂度：** O(n)
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
TaskGroup* group = TaskSystem::Get().CreateTaskGroup();
|
||||
|
||||
for (int i = 0; i < 5; ++i) {
|
||||
group->AddTask([i]() {
|
||||
Thread::Sleep(i * 100);
|
||||
printf("Task %d done\n", i);
|
||||
});
|
||||
}
|
||||
|
||||
if (group->WaitFor(std::chrono::seconds(1))) {
|
||||
printf("All tasks completed within 1 second\n");
|
||||
} else {
|
||||
printf("Timeout! Some tasks still running\n");
|
||||
printf("Progress: %.1f%%\n", group->GetProgress() * 100.0f);
|
||||
}
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [TaskGroup 总览](task-group.md) - 返回类总览
|
||||
- [Wait](wait.md) - 无超时等待
|
||||
Reference in New Issue
Block a user