Async Execution

RunMat's execution entrypoints are async so a host can await a complete request while the VM and runtime await host interaction, builtin futures, GPU/provider work, and selected host/provider callbacks.

The current session path still returns one ExecutionOutcome for each request. ExecutionOutcome::suspension is reserved in the ABI, but normal execution awaits internally and returns None.

Request Flow

RunMatSession::execute_request is async at the host boundary. It resolves the request source, compiles the request synchronously with respect to that execution, and then awaits the interpreter and any runtime operations reached by the bytecode.

A session allows one active execution at a time. The active execution guard prevents overlapping requests from mutating the same workspace concurrently.

Runtime Await Points

Runtime builtins can be plain synchronous Rust functions or async fn implementations registered through the builtin macro system. The dispatcher keeps the call surface uniform: VM call instructions await the runtime dispatcher, and the dispatcher awaits the selected implementation when needed.

If a host-only builtin receives GPU values and the first implementation fails on GPU input, the dispatcher can gather arguments and retry a compatible implementation. gather_if_needed_async recursively materializes tensors, logical arrays, cells, structs, objects, closures, and output lists.

RunMat Async Language Extensions (Beta)

RunMat accepts async function and await(...) as RunMat extensions to the MATLAB language. MATLAB-compatible mode rejects these forms before execution. See MATLAB Language Extensions for the extension model and how to select a compatibility mode.

Calling an async function returns a future. The function body does not run when the future is created; it runs when the future is awaited.

await(value) is allowed inside async functions and at top level when the host policy enables top-level await. It resolves a future or spawn handle, and passes through ordinary values.

async function y = ask()
  input("ready: ");
  y = 1;
end

f = ask();    % no prompt yet
y = await(f); % prompt happens here

Spawn Handles

spawn(value) is also a RunMat language extension to the MATLAB language. It accepts a future, submits it to the active execution service, and returns a single-use task handle without waiting for the result. Native sessions can run the task in an isolated worker process, while browser sessions schedule it through the browser worker service. A host that installs the lightweight in-process execution service may defer the function body until the task is awaited.

async function y = ask()
  input("ready: ");
  y = 1;
end

f = ask();      % no prompt yet
t = spawn(f);   % schedules the work and returns a task handle
y = await(t);   % waits for the result and consumes the task handle

Spawn handles are retired when they are awaited, replaced, dropped from the stack, or removed from scope. Awaiting the same spawn handle twice is an error.

Host Interaction

Each execution installs the session's async interaction handler as a scoped runtime guard. If the host provides a handler, the runtime awaits it and records the prompt, input kind, echo flag, returned value, or error. If no handler exists, native execution falls back to terminal helpers. WASM execution has no default stdin, so browser or JavaScript hosts provide interaction through the WASM API.

input() expression parsing uses a separate eval hook. When expression mode is needed, the hook compiles the typed expression through the normal parser, HIR, MIR, and bytecode path. Native hosts run that nested interpretation on a dedicated thread with a larger stack and return the result through a one-shot channel. WASM awaits the nested interpreter directly.

Current Limits

ExecutionOutcome::suspension is not active for normal execution. Await points complete inside execute_request; hosts do not receive a resumable execution token today.

The amount of parallelism available to spawn is determined by the active execution service and its pool limits. Code should use await for ordering and must not rely on a task completing before spawn returns.

Native local filesystem, native remote filesystem, and native HTTP code expose async-shaped APIs but can block internally. The remote filesystem path is still designed for throughput: large reads can be split across worker threads and issued in parallel chunks.

Cancellation is cooperative. RunMatSession owns an interrupt flag, resets it for each execution, and installs it into the runtime interrupt hook. Long native calls, provider kernels, filesystem work, or JIT code stop only after control reaches a polling boundary.