203 lines
7.6 KiB
Markdown
203 lines
7.6 KiB
Markdown
# AsyncExecutor 协作式取消设计
|
||
|
||
## 背景
|
||
|
||
`lsp.scheduler.async_executor` 当前通过 Taskflow 执行后台任务，但任务句柄只
|
||
弱引用执行状态，快速任务完成后句柄立即失效；句柄取消按任务 ID 回查，可能
|
||
误取消同 ID 的替代任务；排队任务即使已取消仍会执行。任务注册表同时承担
|
||
“当前 ID”与“全部活跃任务”两种职责，导致等待、统计和重复 ID 语义不稳定。
|
||
|
||
本设计不保留现有 API 兼容层，直接建立明确的任务生命周期、结果和协作式
|
||
取消契约。
|
||
|
||
## 目标
|
||
|
||
- 任务句柄在任务完成后仍可等待并读取最终结果。
|
||
- 句柄取消只影响该句柄对应的任务实例。
|
||
- 按 ID 取消只影响该 ID 当前注册的任务实例。
|
||
- 已取消的排队任务不执行任务体。
|
||
- 运行中的长任务通过 `std::stop_token` 协作退出。
|
||
- 重复 ID 的全部活跃任务被准确等待和计数。
|
||
- 任务成功、取消和失败使用单一结果模型表达。
|
||
- 隐藏执行状态、同步原语和句柄构造细节。
|
||
- API namespace 与 Module 名保持一致。
|
||
|
||
## 非目标
|
||
|
||
- 不强制终止正在运行的线程。
|
||
- 不为旧的 `TaskClosure`、callback 或 `WaitForTask` 提供兼容重载。
|
||
- 不在本任务中启用 LSP `$/cancelRequest` 的请求级异步分发；本设计只保证
|
||
scheduler 及其后台索引任务具备正确取消能力。
|
||
- 不修改 Taskflow 本身。
|
||
|
||
## 公共 API
|
||
|
||
Module 名保持：
|
||
|
||
```cpp
|
||
export module lsp.scheduler.async_executor;
|
||
```
|
||
|
||
公共 API 迁移到：
|
||
|
||
```cpp
|
||
namespace lsp::scheduler::async_executor
|
||
```
|
||
|
||
任务结果统一为：
|
||
|
||
```cpp
|
||
enum class TaskStatus
|
||
{
|
||
kCompleted,
|
||
kCancelled,
|
||
kFailed,
|
||
};
|
||
|
||
struct TaskResult
|
||
{
|
||
TaskStatus status;
|
||
std::optional<std::string> value;
|
||
std::exception_ptr error;
|
||
};
|
||
```
|
||
|
||
任务 closure 只产生业务值，最终状态由 executor 根据停止请求和异常统一
|
||
生成，避免任务体自行构造相互矛盾的状态：
|
||
|
||
```cpp
|
||
using TaskClosure =
|
||
std::function<std::optional<std::string>(std::stop_token)>;
|
||
using TaskCallback = std::function<void(const TaskResult&)>;
|
||
```
|
||
|
||
`TaskHandle` 对外提供：
|
||
|
||
```cpp
|
||
bool Valid() const;
|
||
bool Cancel() const;
|
||
std::optional<TaskResult> Wait() const;
|
||
std::optional<TaskResult> TryGetResult() const;
|
||
```
|
||
|
||
- 默认构造句柄无效，`Wait` 与 `TryGetResult` 返回 `std::nullopt`。
|
||
- 有效句柄完成后仍保持有效。
|
||
- `Cancel` 仅在首次成功请求取消且任务尚未完成时返回 `true`。
|
||
- `Wait` 等待任务体和 callback 都结束，并返回最终任务结果。
|
||
- `TryGetResult` 不阻塞；尚未完成时返回 `std::nullopt`。
|
||
- 构造函数为私有，仅 `AsyncExecutor` 可以创建有效句柄。
|
||
|
||
删除 `AsyncExecutor::WaitForTask`。调用方必须保存 `TaskHandle` 来等待特定
|
||
任务；按字符串 ID 只用于取消当前实例，不承担历史结果查询。
|
||
|
||
## 内部状态与所有权
|
||
|
||
`TaskHandle` 通过 `std::shared_ptr` 强持有私有嵌套状态。状态至少包含：
|
||
|
||
- `std::stop_source`：生成 stop token 并接受取消请求。
|
||
- `TaskPhase`：`kPending`、`kRunning`、`kCompleted`。
|
||
- `std::optional<TaskResult>`：最终结果。
|
||
- mutex、condition variable 和 callback 完成标记。
|
||
- task ID 与开始时间。
|
||
|
||
状态定义不导出，外部不能构造或修改同步字段。
|
||
|
||
`AsyncExecutor` 使用两份索引：
|
||
|
||
- `current_tasks_`：`task_id -> state`，只表示该 ID 当前实例，供
|
||
`Cancel(id)` 使用。
|
||
- `active_tasks_`：以任务实例唯一标识保存全部未完成状态，供
|
||
`WaitAll`、`GetRunningTaskCount` 与统计使用。
|
||
|
||
提交同 ID 新任务时，请求旧实例停止，然后替换 `current_tasks_`；旧实例仍
|
||
留在 `active_tasks_`，直到任务体和 callback 都完成。
|
||
|
||
## 取消与执行流程
|
||
|
||
### 排队取消
|
||
|
||
worker 获取任务状态后，在持锁状态下检查 stop token：
|
||
|
||
- 已请求停止：不调用 closure，直接产生 `kCancelled`。
|
||
- 未请求停止：状态从 `kPending` 转为 `kRunning`，随后调用 closure。
|
||
|
||
因此取消和开始执行之间只有一个明确的同步竞态点；取消先获得状态锁时，
|
||
任务体保证不会执行。
|
||
|
||
### 运行中取消
|
||
|
||
任务开始后，`Cancel` 调用 `stop_source.request_stop()`。executor 不强制停止
|
||
线程；closure 接收 `std::stop_token`，在文件枚举、索引和符号加载循环的
|
||
安全边界调用 `stop_requested()` 并尽快返回。
|
||
|
||
如果运行中收到停止请求，即使 closure 已产生普通值，executor 仍将最终
|
||
状态归类为 `kCancelled`，避免向 callback 报告成功。
|
||
|
||
### 完成与 callback
|
||
|
||
executor 捕获任务异常并生成 `kFailed`，保留原始 `exception_ptr`。任务结果
|
||
先写入状态，再调用 callback；callback 异常被捕获并记录，但不改写已经确定
|
||
的任务结果。只有 callback 返回或异常被处理后，状态才标记为完全完成、从
|
||
两个注册表注销并唤醒等待者。
|
||
|
||
callback 不得从自身调用 `Wait` 或 `WaitAll`；该约束写入接口注释和测试命名，
|
||
避免自等待死锁。
|
||
|
||
## 并发数与生命周期
|
||
|
||
传入并发数 0 或 `std::thread::hardware_concurrency()` 返回 0 时，实际 worker
|
||
数收敛到 1，再构造 `tf::Executor`。
|
||
|
||
`AsyncExecutor` 析构时调用 `WaitAll`。`WaitAll` 等待所有活跃状态完成，并再
|
||
调用 Taskflow `wait_for_all()`，确保 callback 中提交的后续任务也已退出。
|
||
析构期间不允许其他线程继续调用 `Submit`；这是对象生命周期的基本前置条件。
|
||
|
||
## 调用方迁移
|
||
|
||
所有 `scheduler::AsyncExecutor`、`scheduler::TaskHandle` 等引用迁移到
|
||
`scheduler::async_executor::*`。所有 `Submit` closure 增加
|
||
`std::stop_token` 参数，callback 改为接收 `const TaskResult&`。
|
||
|
||
工作区加载、系统库加载、文件索引和 workspace folder 变更任务将 stop token
|
||
传入长循环；循环在每个文件或目录边界检查停止请求。只执行一次且不可拆分的
|
||
第三方调用在调用前后检查 token，不尝试中断其内部线程。
|
||
|
||
## 清理
|
||
|
||
- 删除公开的 `detail::ExecutionState` 与 `detail::ActiveEntry`。
|
||
- 将 `ExecutorMetrics` 作为明确公共结果类型保留在
|
||
`lsp::scheduler::async_executor`。
|
||
- 删除未使用的 `ActiveEntry::callback`、`ActiveEntry::start_time` 和
|
||
`kStatusLogInterval`。
|
||
- 测试 Module 的入口同步放入自身命名空间，不再导出全局 `Run`。
|
||
|
||
## 测试设计
|
||
|
||
测试遵循 TDD，先在旧实现上观察失败，再实现新语义：
|
||
|
||
- 无延迟任务完成后，handle 仍有效且可读取结果。
|
||
- `Wait` 返回任务体与 callback 完成后的最终结果。
|
||
- 同 ID 替换后，旧 handle 取消不影响新任务。
|
||
- 排队任务被取消后，任务体从未执行。
|
||
- 运行中任务观察 stop token 并协作退出。
|
||
- 同 ID 两个活跃实例被计数为 2，`WaitAll` 等待两者。
|
||
- 并发数 0 可以正常执行任务。
|
||
- task 异常生成 `kFailed` 并保留异常。
|
||
- callback 异常不会导致等待死锁，也不会改写任务结果。
|
||
- 成功、取消、失败统计与最终状态一致。
|
||
|
||
迁移完成后运行 scheduler 测试、provider 测试和生产服务器构建；LSP 传输
|
||
冒烟测试确认后台初始化和 workspace 操作没有回归。
|
||
|
||
## 完成条件
|
||
|
||
- 快速完成任务的 handle 不失效。
|
||
- 任一 handle 只能取消自己的状态。
|
||
- 已取消的排队 closure 不执行。
|
||
- 长任务可以通过 stop token 提前退出。
|
||
- `GetRunningTaskCount` 和 `WaitAll` 覆盖重复 ID 的所有实例。
|
||
- 不存在 `WaitForTask`、公开执行状态或未使用调度字段。
|
||
- 并发数始终至少为 1。
|
||
- namespace、调用方和测试全部迁移完成。
|
||
- 约定范围内构建与测试通过。
|