Module tvix_eval::vm

source ·
Expand description

This module implements the abstract/virtual machine that runs Tvix bytecode.

The operation of the VM is facilitated by the Frame type, which controls the current execution state of the VM and is processed within the VM’s operating loop.

A VM is used by instantiating it with an initial Frame, then triggering its execution and waiting for the VM to return or yield an error.


  • This module implements generator logic for the VM. Generators are functions used during evaluation which can suspend their execution during their control flow, and request that the VM do something.
  • macros 🔒



  • Frame 🔒
    A frame represents an execution state of the VM. The VM has a stack of frames representing the nesting of execution inside of the VM, and operates on the frame at the top.


  • GetSpan 🔒
    Internal helper trait for taking a span from a variety of types, to make use of WithSpan (defined below) more ergonomic at call sites.
  • WithSpan 🔒
    Internal helper trait for ergonomically converting from a Result<T, ErrorKind> to a Result<T, Error> using the current span of a call frame, and chaining the VM’s frame stack around it for printing a cause chain.


  • add_values 🔒
  • Generator that retrieves the final value from the stack, and deep-forces it before returning.
  • Resolve a dynamically bound identifier (through with) by looking for matching values in the with-stacks carried at runtime.