docs: rebuild Threading API content

docs/api/XCEngine/Threading/TaskSystem/ParallelFor.md

@@ -1,33 +1,54 @@
 # TaskSystem::ParallelFor
 
-公开方法，详见头文件声明。
+把一个整数区间拆分成多个任务并提交执行。
 
 ```cpp
-template<typename Func> void ParallelFor(int32_t start, int32_t end, Func&& func);
+template<typename Func>
+void ParallelFor(int32_t start, int32_t end, Func&& func);
 ```
 
-该方法声明于 `XCEngine/Threading/TaskSystem.h`，当前页面用于固定 `TaskSystem` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：**
-- `start` - 参数语义详见头文件声明。
-- `end` - 参数语义详见头文件声明。
-- `func` - 参数语义详见头文件声明。
+当前模板实现会：
 
-**返回：** `template<typename Func> void` - 返回值语义详见头文件声明。
+1. 计算区间长度 `count = end - start`。
+2. 若 `count <= 0`，直接返回。
+3. 用 `std::thread::hardware_concurrency()` 决定分片数量；若返回 `0`，回退到 `2`。
+4. 按 `(count + numThreads - 1) / numThreads` 计算块大小。
+5. 为每个分片构造一个高优先级 lambda 任务。
+6. 逐个调用 [Submit](Submit.md) 提交这些任务。
 
-**示例：**
+## 参数
 
-```cpp
-#include <XCEngine/Threading/TaskSystem.h>
+- `start` - 起始索引，包含。
+- `end` - 结束索引，不包含。
+- `func` - 对区间内每个索引执行的可调用对象。
 
-void Example() {
-    XCEngine::Threading::TaskSystem object;
-    // 根据上下文补齐参数后调用 TaskSystem::ParallelFor(...)。
-    (void)object;
-}
-```
+## 返回值
+
+- 无。
+
+## 当前实现限制
+
+- 当前函数提交完任务后立即返回，不会等待所有分片完成。
+- 当前按硬件并发数分片，而不是按 [Initialize](Initialize.md) 配置的工作线程数分片。
+- 当前头文件里模板使用了 `LambdaTask` 和 `std::min`，但 `TaskSystem.h` 自身没有包含 `LambdaTask.h` 和 `<algorithm>`；如果只包含这个头，模板实例化可能失败。
+- 当前底层仍然依赖 [Submit](Submit.md)，因此会继承任务生命周期悬空指针问题。
+- 当 `numThreads > count` 时，会提交一些空分片任务。
+
+## 设计说明
+
+商业级 `ParallelFor` 通常至少还需要：
+
+- 同步栅栏或等待句柄。
+- 更合理的分块策略。
+- 工作窃取或局部队列。
+- 对小任务的过度拆分抑制。
+
+当前版本更接近“把并行循环 API 形状先搭出来”。
 
 ## 相关文档
 
-- [返回类总览](TaskSystem.md)
-- [返回模块目录](../Threading.md)
+- [返回类型总览](TaskSystem.md)
+- [Submit](Submit.md)
+- [Synchronization And Task System Limits](../../../_guides/Threading/Synchronization-And-TaskSystem-Limits.md)