Async Execution

Asynchronous Execution

Background Jobs

For code that takes more than ~30 seconds, submit it as a background job:

execute_{server}_code(
    code="result = long_running_computation(...)",
    description="Running expensive simulation",
    background=True,
    timeout=3600
)
# Returns immediately with a job_id

Then poll for completion:

{server}_check_job(job_id="...")
# Returns status: "running", "completed", or "failed"
# When completed, includes stdout, stderr, success, and error (if any)

Rules for background jobs

• The job runs in the same session kernel — variables are accessible after completion.
• Use {server}_inspect_session to check both job status and namespace state.
• Set an appropriate timeout — background jobs still have a maximum execution time.
• Do not submit trivial code as background — only use for genuinely long-running tasks.

Parallel Execution

Run the same code template across multiple independent inputs concurrently:

{server}_parallel_execute(
    code="result = process_item(input_id=input_id, params=params)",
    inputs=[{"input_id": "item_1", "params": {...}}, {"input_id": "item_2", "params": {...}}, ...],
    result_variable="result"
)
# Returns batch_id

Managing batches

{server}_check_batch(batch_id="...")
# Returns aggregate status and available results

{server}_cancel_batch(batch_id="...")
# Stops all running jobs and cleans up child sessions

How parallel execution works

• Each input gets its own child session/kernel.
• The code template receives each input dict's keys as local variables.
• The variable named by result_variable is collected from each child session.
• Individual items can fail without blocking others.

When to use parallel execution

• Processing a list of independent inputs with the same logic.
• Tasks where individual items are independent and order does not matter.
• Workloads that benefit from concurrent kernel execution.

When NOT to use parallel execution

• Tasks that depend on shared state across iterations.
• Small loops (< 5 items) — sequential execution in one execute_{server}_code call is simpler and has less overhead.
• Tasks where items must be processed in order.