oh-my-pi 原生 Rust 任务调度与取消机制从timeoutMs/AbortSignal到 Rust 执行的完整链路【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi导读在 oh-my-pi⌥ Coding agent with the IDE wired in中grep、glob、astGrep、Shell 命令执行、PTY 会话等重活都由crates/pi-natives以原生 Rust 实现并通过 N-API 暴露给 JS。本文基于 docs/natives-rust-task-cancellation.md完整剖析该 crate 的任务调度模型task::blocking与task::future双通道以及取消如何从 JS 侧的timeoutMs与AbortSignal一路传导进 Rust 执行你会掌握CancelToken/AbortToken的核心语义、两类任务各自的取消生命周期、心跳heartbeat节奏的实战要求、错误传播模型以及新增可取消导出时的完整检查清单。实现文件概览取消机制横跨多个原生模块核心入口与实现文件集中在crates/pi-natives/src/task.rs —— 调度原语与取消令牌本文的主角grep.rs、glob.rs、fd.rs —— 文件扫描类阻塞任务ast.rs、workspace.rs —— ast-grep 与工作区遍历shell.rs、pty.rs —— 进程与终端类异步任务html.rs、sixel.rs、clipboard.rs、text.rs、ps.rs —— 各自承载一个或一组导出。其中 shell 的底层取消令牌实现位于 crates/pi-shell/src/cancel.rspi-natives的CancelToken是对它的封装与增强。核心原语task.rstask.rs 定义了三大类原语。task::blocking(tag, cancel_token, work)包装 napi 的AsyncTask/Tasktraitcompute()运行在libuv worker 线程池上task.rs 实现Task::compute对导出的函数返回 JSPromiseT通过profile_region(tag)记录一条性能剖析样本。task::future(env, tag, work)包装env.spawn_future(...)异步工作在Tokio 运行时上执行task.rs返回PromiseRawenv, T同样通过profile_region(tag)记录剖析样本。CancelToken/AbortToken/AbortReasonCancelToken::new(timeout_ms, signal)包装共享的pi_shell::cancel::CancelToken见 crates/pi-shell/src/cancel.rs并增加可选的 JSAbortSignal桥接调用signal.on_abort(...)把信号回调接到AbortToken::abort(AbortReason::Signal)task.rsheartbeat()是协作式取消的同步检查点返回Result()超时/信号触发时返回Err(Aborted: ...)wait()异步等待信号或超时返回AbortReasonabort_token()在共享 flag 已存在时返回由其支撑的 abort 句柄若尚无 flag 则该句柄是惰性的inert。emplace_abort_token()会惰性安装flag 并返回真实句柄CancelToken::new正是用后者把 JSAbortSignal桥接到AbortReason::Signalaborted()提供非阻塞的信号/截止时间检查into_core()把令牌转移给pi-shell例如 shell.rs 中的cancel_token.into_core()AbortToken::abort(reason)允许外部代码主动请求取消原因取值Unknown、Timeout、Signal、User。在底层 crates/pi-shell/src/cancel.rs 中共享 flag 是一个AtomicU8保存 reason加一个tokio::sync::Notify唤醒等待者abort()用SeqCst原子交换写入 reason仅在首次写入时notify_waiters()heartbeat()依次检查 flag 原因与 deadlinewait()则用tokio::select!竞争 flag 唤醒与 deadline 睡眠两条路径。blockingvsfuture执行模型与选择依据何时用task::blocking工作属于CPU 密集或本质同步/阻塞时使用正则/文件扫描grep、glob、fuzzyFindast-grep 搜索/编辑的 worker 工作HTML 转换剪贴板图像读取。行为要点工作闭包收到一个克隆的CancelToken取消只有在代码执行到ct.heartbeat()?时才被观察到闭包返回Err(...)会 reject JS promise。何时用task::future工作必须await异步操作时使用Shell 会话编排Shell.run、executeShellPTY 外层 promisePtySession.start在进入spawn_blocking之前需要桥接完成与取消的异步任务编排。行为要点future 代码可以并发竞速「正常完成」与ct.wait()走取消路径时异步实现通常先取消下属机制并在宽限超时后强制中止。JS API ↔ Rust 导出映射任务/取消相关下表汇总了任务/取消相关的 JS 面 API、对应 Rust 导出、调度器与取消接线方式JS 面 APIRust 导出调度器取消接线grep(options, onMatch?)greptask::blocking(grep, ct, ...)CancelToken::new(options.timeoutMs, options.signal) 心跳检查glob(options, onMatch?)globtask::blocking(glob, ct, ...)CancelToken::new(...) 心跳检查fuzzyFind(options)fuzzy_findtask::blocking(fuzzy_find, ct, ...)CancelToken::new(...) 心跳检查astGrep(options)/astMatch(options)/astEdit(options)ast 系列导出blocking worker 路径options 接收 timeout/signal 字段并在 worker 循环中协作式检查listWorkspace(options)list_workspacetask::blocking(listWorkspace, ct, ...)CancelToken::new(options.timeoutMs, options.signal) 心跳检查Shell#run(options, onChunk?)Shell::runtask::future(env, shell.run, ...)JSCancelToken转为pi_shell::cancel::CancelTokenshell 以它竞速命令完成与后代进程清理executeShell(options, onChunk?)execute_shelltask::future(env, shell.execute, ...)同样的取消竞速 2 秒宽限窗口Process#terminate(options?)Process::terminatetask::future(env, process.terminate, ...)可选 signal 取消终止等待宽限与硬杀超时属于进程策略而非CancelToken截止时间Process#waitForExit(options?)Process::wait_for_exittask::future(env, process.wait_for_exit, ...)可选 signal 经CancelToken桥接timeoutMs作为等待操作的类型化超时PtySession#start(...)/startArgv(...)PTY 方法task::future(env, pty.start, ...) 内部spawn_blocking同步 PTY 循环通过heartbeat()检查CancelTokenhtmlToMarkdown(html, options?)html_to_markdowntask::blocking(html_to_markdown, (), ...)无()令牌encodeSixel(...)encode_sixel同步原生函数无readImageFromClipboard()read_image_from_clipboardtask::blocking(clipboard.read_image, (), ...)无()令牌注意text.rs、tokens.rs、keys.rs、大部分同步的 ps.rs 函数、SIXEL 编码以及同步工具导出不使用task::blocking/task::future取消异步的Process.terminate()与Process.waitForExit()方法则使用。取消生命周期与状态迁移CancelToken生命周期Created ├─ no signal no timeout - passive token ├─ signal registered - AbortSignal callback can set AbortReason::Signal └─ deadline set - timeout check becomes active Running ├─ heartbeat()/wait() sees signal - AbortReason::Signal ├─ heartbeat()/wait() sees deadline - AbortReason::Timeout └─ no abort - continue Aborted └─ shared flag wakes waiters; a later abort call can replace the stored reason, while a deadline is evaluated independently启动前 vs 执行中取消启动前 / 第一次取消检查之前task::future的用户一旦进入select!就能通过ct.wait()竞速解析取消task::blocking的用户只有在闭包代码执行到heartbeat()时才观察到取消。执行中blocking下一次heartbeat()返回Err(Aborted: ...)futurect.wait()分支在select!中胜出随后代码取消下属异步机制shell取消触发 Tokio 取消令牌发送后代进程终止波termination waves等待命令任务最多 2 秒必要时再强制中止任务PTY心跳失败或kill()终止 PTY 子进程/目标进程并短暂排空输出。在 pty.rs 中run_pty_sync每个循环节拍都调用ct.heartbeat()实测代码在每 tick 以最大 16ms 的等待节奏检查PTY 测试还刻意用CancelToken::new(Some(1), None)验证启动前心跳即失败的分支pty.rs。长循环的心跳heartbeat节奏要求heartbeat()必须在无界或大工作集循环中以可预期的节奏运行。仓库中的实际模式glob与fuzzyFind把心跳回调传入pi-walker遍历如 glob.rs 的collect_with_heartbeat(|| ct.heartbeat())并在结果处理循环中再次检查grep在昂贵搜索前后检查并把令牌透传给其扫描/搜索 workerrun_pty_sync每个循环 tick 检查最大等待节奏 16mslistWorkspace在遍历期间检查workspace.rs。实用规则任何遍历外部规模输入的循环都不应在没有一次heartbeat()的情况下超过一个短的固定时间间隔。失败行为与向 JS 的错误传播阻塞任务blocking tasks错误路径闭包返回Err(napi::Error)包括heartbeat()中止Task::compute()返回ErrAsyncTaskreject JS promise。典型错误字符串Aborted: TimeoutAborted: Signal领域错误Failed to decode image: ...、Conversion error: ...等。另外task.rs 中Blocking::compute用catch_unwind包裹闭包并配合crash_handler::blocking_task_panic_scope防止 panic 穿越 napi 的extern CFFI 边界导致宿主进程强制中止RFC 2945 C-unwind 规则dispose_panic_payload甚至能在 payload 的析构函数自身 panicDropBomb 场景时兜底测试见 task.rs。blocking_mapped则提供带 reject 钩子的变体可在 JS 线程用Env构造富错误对象。异步任务future tasks错误路径异步体返回Err(napi::Error)或 join 失败被映射... task failed: {err}task::future派生的 promise rejectShell 与 PTY 命令 API 在取消路径胜出时把取消建模为结构化结果而非 rejectionexitCode省略、cancelled或timedOut置位。取消上报的两种模型中止即错误使用heartbeat()?的阻塞导出中止即类型化结果把取消建模在结果结构体中的 shell/PTY 命令 API。每个 API 应二选一并明确记录在文档中。常见陷阱阻塞循环中缺少心跳症状超时/信号看起来被忽略直到循环结束修复在循环顶部及昂贵的逐项步骤前加ct.heartbeat()?。过长的不可取消区间症状单个大调用解码、排序、压缩、解析器等期间取消延迟飙升修复把工作切分成带心跳边界的块若做不到则明确记录延迟。阻塞异步执行器症状同步密集代码直接跑在 future 里时异步 API 卡顿修复把 CPU/同步块移到task::blocking或tokio::task::spawn_blocking。取消语义不一致症状一个 API 取消时 reject另一个以标志位 resolve令调用方困惑修复按领域统一语义并保持文档同步。嵌套异步任务中遗忘取消桥接症状外层令牌已取消内层 reader/子进程任务仍在运行修复把取消桥接到内层令牌/信号并强制宽限超时 强制中止兜底。新增可取消导出的检查清单正确分类工作CPU 密集或同步阻塞 →task::blocking异步 I/O /await编排 →task::future。按需暴露取消输入在#[napi(object)]options 中包含timeoutMs与signal创建let ct task::CancelToken::new(timeout_ms, signal);。打通所有层的取消阻塞循环按稳定间隔调用ct.heartbeat()?异步编排与ct.wait()竞速并取消子任务/令牌。确定取消契约用中止错误 reject promise或resolve 类型化{ cancelled, timedOut, ... }并在该 API 族内保持一致。带上下文传播失败用Error::from_reason(format!(...: {err}))映射错误包含阶段前缀spawn、decode、wait等。处理启动前与飞行中取消取消检查/等待必须在昂贵主体之前发生并在长时间执行期间持续发生。验证执行器未误用异步 future 内部不得直接运行长同步工作除非经过spawn_blocking/blocking 任务包装。参考实现速查调度原语与取消令牌封装crates/pi-natives/src/task.rs底层取消令牌flag deadline Notifycrates/pi-shell/src/cancel.rsShell 会话的未来型编排crates/pi-natives/src/shell.rsPTY 同步循环的心跳节奏crates/pi-natives/src/pty.rs阻塞遍历的心跳透传crates/pi-natives/src/glob.rs、crates/pi-natives/src/workspace.rsast-grep worker 循环的协作式取消crates/pi-natives/src/ast.rs【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考