Session Engine
runmat-core owns the host-agnostic execution session. A RunMatSession is the long-lived object that a REPL, notebook host, CLI command, or WebAssembly wrapper uses to submit MATLAB source, keep workspace variables alive, preserve user-defined functions, expose inspection data, handle input, and return structured execution results.
The session is not a second compiler or a second VM. It is the orchestration layer around the parser, HIR/MIR pipeline, VM, adaptive native JIT, runtime builtins, GPU provider state, and host-facing ABI.
Execution Spine
What The Session Owns
| Field or subsystem | Purpose |
|---|---|
variable_array | VM slot storage used during the current execution. |
workspace_bindings | Name-to-slot mapping plus stable ABI binding identity. |
workspace_values | Durable variable values retained between requests. |
function_registry | User-defined semantic functions retained across interactive inputs. |
source_pool | Interned source text and names for diagnostics and call stacks. |
interrupt_flag | Cooperative cancellation flag shared with the runtime and VM. |
async_input_handler | Host callback for input, keypress, and pause-like interactions. |
stats, profiling, telemetry | Execution counters and optional host analytics hooks. |
compat_mode, top_level_await_enabled | Per-session defaults that can be overridden by a request. |
RunMatSession rejects concurrent execution on the same session. Hosts that need parallel execution should create separate sessions or serialize requests through one session.
Page Map
| Page | Purpose |
|---|---|
| Execution Requests | The structured request/result ABI around session execution. |
| Workspace State | How variable slots, stable binding keys, deltas, removals, and ans work. |
| Variable Inspection | Workspace entries, previews, materialization, preview tokens, and GPU slices. |
| Workspace Replay | Exporting and restoring live workspace state. |
| Interaction & Streams | Console streams, warnings, async input, cancellation, diagnostics, and effects. |
| Host Integration | CLI, WASM/TypeScript, notebook, editor, and lifecycle responsibilities. |
For the compiler stages inside compile_input, see Compilation Pipeline. For bytecode execution details, see VM Interpreter & Bytecode. For native execution, see JIT Compiler.