- CHANGELOG.md:v2.8.0 条目(中英双语); - README.md:版本行 2.7.1→2.8.0 + 愿景第 6 条(知识可证明); - doc/releases/v2.8.0.md:双语发版说明(亮点/用法/已知限制); - skills/marqdo-dev/index.mq.md:新增 prove 任务(路径/目录模式/ require_lean/json;参数用 + 行声明升参,check 与 narrative-ratio 通过); - 设计文档 §12.5 标记已合入;发版链接统一指向 doc/releases/v2.8.0.md。
6.4 KiB
Executable File
markup, title, description
| markup | title | description |
|---|---|---|
| occlusion | lib/子任务 | 并发子任务 — 文件、函数或外联代码 |
并发子任务:文件、函数或外联代码。
以明确所有权管理并发任务。
能力与边界:文件批处理继承父权限与根目录。每项 Result.ok 表示等待协议完成,子进程业务成败还须检查 value.code。限时等待默认保留句柄,取消需要明确选择。进程可以终止并回收;函数线程只能逻辑取消。
本文件就是调用和开发手册:直接导入此文件,或用 marqdo call 按下面的函数标题调用。参数表说明类型和默认值;未填默认值的参数必须提供。返回表是渐进契约,后文说明失败与边界。
相对文件路径以 --fs-root 为准,省略时以被调用文件所在目录为准。写入需要显式 fs.write 授权,子进程需要 process.exec;纯计算无需 IO 权限。
实现入口:src/host/subtask.rs、src/host/task_ops.rs
开发时保持中英文语义一致,先组合公开库;仅在 OS 或算法边界添加宿主原语并声明效应。修改后运行 marqdo check --narrative-ratio 本文件,并执行 tests/stdlib_tasks.rs 的真实任务。
启动
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 路径 | any | None | 授权根目录内的文件路径 |
| 函数 | any | None | 调用方提供的函数 |
| 参数 | any | None | 调用方提供的参数 |
| 代码 | any | None | 调用方提供的代码 |
| 语言 | any | None | 调用方提供的语言 |
| 源码 | any | None | 本次检查或试跑的源码文本 |
| 输入 | any | None | 调用方提供的输入 |
| 静默 | any | True | 调用方提供的静默 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | number | 启动子任务 |
这里使用路径=None、函数=None、参数=None、代码=None、语言=None、源码=None、输入=None、静默=True。
调用效应:process.exec。
启动子任务。文件子任务默认静默(静默=真:管道捕获)。静默=假 时继承父终端。文件等待返回 {code, value},静默捕获时另含截断的 stdout/stderr;value 为子 main 返回值。
调用例:[子任务.启动] 路径="child.mq.md"
完成后返回*[启动子任务](> host_subtask_spawn path=路径 fn=函数 args=参数 code=代码 lang=语言 source=源码 stdin=输入 quiet=静默)*。
探测
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| id | any | 必填 | 对应创建或启动操作返回的标识 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | 非阻塞查看子任务 id 状态 |
这里使用id。
调用效应:process.exec。
非阻塞查看子任务 id 状态。
完成后返回*[非阻塞查看子任务 id 状态](> host_subtask_poll id=id)*。
等待
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| id | any | 必填 | 对应创建或启动操作返回的标识 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | 阻塞直到子任务 id 结束 |
这里使用id。
调用效应:process.exec。
阻塞直到子任务 id 结束。
完成后返回*[阻塞直到子任务 id 结束](> host_subtask_join id=id)*。
终止
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| id | any | 必填 | 对应创建或启动操作返回的标识 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | 终止子任务 id |
这里使用id。
调用效应:process.exec。
终止子任务 id。
完成后返回*[终止子任务 id](> host_subtask_kill id=id)*。
等待全部
| 返回 | 类型 | 说明 |
|---|---|---|
| result | list | 等待全部已启动子任务结束 |
调用效应:process.exec。
等待全部已启动子任务结束。
完成后返回*等待全部已启动子任务结束*。
限时等待
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 编号 | number | 必填 | 对应创建或启动操作返回的标识 |
| 超时毫秒 | number | 30000 | 超时毫秒数;等待后检查操作结果 |
| 取消 | bool | False | 超时后是否同时取消尚未结束的任务 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | 限时等待并返回结果记录;默认超时保留句柄。cancel=True 会终止并回收进程;函数线程只进行逻辑取消。 |
这里使用编号、超时毫秒=30000、取消=False。
调用效应:process.exec。
限时等待并返回结果记录;默认超时保留句柄。cancel=True 会终止并回收进程;函数线程只进行逻辑取消。
完成后返回*[限时等待并返回结果记录;默认超时保留句柄](> host_subtask_wait_timeout id=编号 timeout_ms=超时毫秒 cancel=取消)*。
全部取消
| 返回 | 类型 | 说明 |
|---|---|---|
| result | number | 取消所有子任务并回收子进程,返回数量;函数线程只能逻辑取消。 |
调用效应:process.exec。
取消所有子任务并回收子进程,返回数量;函数线程只能逻辑取消。
完成后返回*[取消所有子任务并回收子进程,返回数量;函数线程只能逻辑取消](> host_subtask_cancel_all )*。
批量执行
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 任务 | list | 必填 | 有序文件任务记录,包含 path 及可选 args |
| 并发上限 | number | 4 | 同时运行的文件任务上限,范围 1 到 64 |
| 超时毫秒 | number | 30000 | 超时毫秒数;等待后检查操作结果 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | list | 按并发上限执行 path/args 文件任务,结果按输入排序,每项是结果记录。超时终止回收对应进程;最多一万任务、六十四并发,继承父权限和文件根目录。 |
这里使用任务、并发上限=4、超时毫秒=30000。
调用效应:process.exec。
直接调用此函数:
marqdo call lib/子任务.mq.md 批量执行 '任务=[{"path":"examples/stdlib-handbook/worker.mq.md"}]' '并发上限=2' --effects process.exec --fs-root . --json
按并发上限执行 path/args 文件任务,结果按输入排序,每项是结果记录。超时终止回收对应进程;最多一万任务、六十四并发,继承父权限和文件根目录。
完成后返回*[按并发上限执行 path/args 文件任务,结果按输入排序,每项是结果记录](> host_subtask_run_many tasks=任务 limit=并发上限 timeout_ms=超时毫秒)*。