Module vm 

Stack-Based Bytecode Virtual Machine (Runtime)

This module implements a compact, stack-based virtual machine that executes a sequence of bytecode instructions (Instr) produced by the compiler.

High-level model

• Operand stack (stack): holds Values consumed/produced by ops.
• Global env (globals): process-wide, persists across function frames.
• Local env (env): the current function’s locals (top of env_stack).
• Env stack (env_stack): call frames for user-defined functions.
• Return stack (ret_stack): return program counters for calls.
• Block stack (block_stack): exception-handling frames capturing handler location and stack/env depths for unwinding.
• Program counter (pc): index into code (the instruction stream).
• Advance flag (advance_pc): lets control-flow ops manage the PC.

The VM supports:

• Arithmetic/logical/bitwise ops (delegated to ops_arith)
• Structured operations (lists/dicts, indexing, slicing) via ops_struct
• Control flow (jumps, calls, returns, builtins, asserts, exceptions)
• Exception-style unwinding via SetupExcept/PopBlock/Raise

The machine is deterministic and “fails fast”: any instruction error sets error_flag, triggers block unwinding if a handler is present, or terminates with a RuntimeError if unhandled.

Functions

run

Execute bytecode on a stack-based virtual machine.