Files
marqdo/lib/subtask.mq.md

6.5 KiB

markup, title, description
markup title description
occlusion lib/subtask Concurrent subtasks — file, function, or foreign code

Concurrent subtasks: file, function, or foreign code.

Run and observe concurrent work with explicit ownership.

Behavior and limits: File batches inherit parent caps and root. Each Result.ok reports completion of the wait protocol; inspect value.code for child exit success. wait_timeout keeps its handle unless cancel is requested. OS tasks can be killed/reaped; function-thread cancellation is logical only.

This single source file is the usage and development manual. Import it directly, or use marqdo call with a function heading below. Parameter tables give types and defaults; required parameters must be supplied. Return tables are progressive contracts; prose describes failure and limits.

Relative IO paths use --fs-root, or the called file directory when omitted. Writes require explicit fs.write grants, subprocesses require process.exec, and pure transforms require no IO grant.

Implementation: src/host/subtask.rs、src/host/task_ops.rs

For development, keep EN/ZH behavior aligned and compose public libraries first. Add host primitives only at OS or algorithm boundaries and declare their effects. Run marqdo check --narrative-ratio on this file and the real workflows in tests/stdlib_tasks.rs after edits.

spawn

参数 类型 默认 说明
path any None Path relative to the granted filesystem root
fn any None Marqdo function target used instead of a file task
args any None Arguments supplied to the selected task
code any None Bound code-fence value; supply lang and source for inline text
lang any None Registered interpreter language identifier, such as python
source any None Source text to run with the selected interpreter
stdin any None Text written to the child process standard input
quiet bool True Whether to suppress child output while retaining its result
返回 类型 说明
result number Start a subtask

Use path=None, fn=None, args=None, code=None, lang=None, source=None, stdin=None, quiet=True as the inputs for this operation.

Effects: process.exec.

Start a subtask. File children are silent by default (quiet=True: piped capture). Set quiet=False to inherit parent stdout/stderr. File wait returns {code, value} plus optional stdout/stderr tails when quiet-captured. value is the child main return (not stdout).

Caller: [subtask.spawn] path="child.mq.md"

Return [Start a subtask](> host_subtask_spawn path=path fn=fn args=args code=code lang=lang source=source stdin=stdin quiet=quiet).

poll

参数 类型 默认 说明
id any required Identifier returned by the corresponding create/spawn operation
返回 类型 说明
result map Non-blocking status for subtask id

Use id as the inputs for this operation.

Effects: process.exec.

Non-blocking status for subtask id.

Return [Non-blocking status for subtask id](> host_subtask_poll id=id).

wait

参数 类型 默认 说明
id any required Identifier returned by the corresponding create/spawn operation
返回 类型 说明
result any Block until subtask id finishes

Use id as the inputs for this operation.

Effects: process.exec.

Block until subtask id finishes.

Return [Block until subtask id finishes](> host_subtask_join id=id).

kill

参数 类型 默认 说明
id any required Identifier returned by the corresponding create/spawn operation
返回 类型 说明
result any Kill subtask id

Use id as the inputs for this operation.

Effects: process.exec.

Kill subtask id.

Return [Kill subtask id](> host_subtask_kill id=id).

wait_all

返回 类型 说明
result list Wait until every spawned subtask finishes

Effects: process.exec.

Wait until every spawned subtask finishes.

Return Wait until every spawned subtask finishes.

wait_timeout

参数 类型 默认 说明
id number required Identifier returned by the corresponding create/spawn operation
timeout_ms number 30000 Timeout in milliseconds; inspect the operation result after waiting
cancel bool False Whether a timeout also cancels the outstanding task
返回 类型 说明
result map Wait as Result; timeout retains the handle unless cancel=True

Use id, timeout_ms=30000, cancel=False as the inputs for this operation.

Effects: process.exec.

Wait as Result; timeout retains the handle unless cancel=True. Cancellation reaps process tasks; function-thread cancellation is logical only.

Return [Wait as Result; timeout retains the handle unless cancel=True](> host_subtask_wait_timeout id=id timeout_ms=timeout_ms cancel=cancel).

cancel_all

返回 类型 说明
result number Cancel all subtasks, reaping process tasks; return count

Effects: process.exec.

Cancel all subtasks, reaping process tasks; return count. Function threads only support logical cancellation.

Return [Cancel all subtasks, reaping process tasks; return count](> host_subtask_cancel_all ).

run_many

参数 类型 默认 说明
tasks list required Ordered file task records containing path and optional args
limit number 4 Maximum simultaneous file tasks, from 1 through 64
timeout_ms number 30000 Timeout in milliseconds; inspect the operation result after waiting
返回 类型 说明
result list Run path/args file tasks with bounded concurrency; return ordered Results

Use tasks, limit=4, timeout_ms=30000 as the inputs for this operation.

Effects: process.exec.

Call this function directly:

marqdo call lib/subtask.mq.md run_many 'tasks=[{"path":"examples/stdlib-handbook/worker.mq.md"}]' limit=2 --effects process.exec --fs-root . --json

Run path/args file tasks with bounded concurrency; return ordered Results. Timed-out children are killed and reaped; at most 10000 tasks, 64 workers; inherit parent caps and filesystem root.

Return [Run path/args file tasks with bounded concurrency; return ordered Results](> host_subtask_run_many tasks=tasks limit=limit timeout_ms=timeout_ms).