DOCSEARCHbyAlgolia
Submit Docs

LightVM Documentation

website·Indexed 30 days ago

https://lightvm.vercel.app

A high-performance, deterministic virtual machine designed to bridge the gap between high-level logic and low-level execution. LightVM features a stack-based architecture, a dedicated validation and security layer called Krates, a symbol resolver named Torja, and a built-in optimizer called Gazle. It supports Node.js and Rust projects, providing a comprehensive instruction set for mathematics, vector operations, and OOP, alongside a TypeScript-compatible API for VM control and bytecode management.

Tokens
18.8K
Snippets
89
Records
161
Agent score
70%

What's inside LightVM

  1. Overview of LightVM

    LightVM is a high-performance, deterministic virtual machine built with Rust. It is designed for embedded systems, simulation engines, and performance-critical applications, prioritizing resource transparency, safety, and a minimal memory footprint (utilizing SmolStr and Ahash for metadata management).

  2. Overview of the Itme benchmarking utility

    Itme is a high-precision benchmarking utility for LightVM designed to provide reliable and reproducible performance measurements for functions. It uses an adaptive execution strategy to balance precision with duration, ensuring a statistically significant sample size regardless of whether a function is short-running or long-running.

  3. Overview of LightVM Krates security layer

    Krates is the dedicated validation and security layer of LightVM. It serves as a gatekeeper that inspects bytecode before execution to protect the runtime environment from malformed instructions, unauthorized features, and memory access violations. It ensures that only safe and deterministic bytecode is passed to the execution engine.

  4. Overview of Gazle Bytecode Optimizer

    Gazle is a built-in optimizer for LightVM that performs adaptive multi-pass optimizations on bytecode before execution. To prevent excessive overhead, each optimization pass is restricted to a 200 millisecond time budget. Gazle uses a transformation pipeline where passes are dynamically sorted by success-based weights (pass_weights) to prioritize the most effective optimizations.

  5. Understand LightVM feature support levels

    LightVM categorizes features into three support levels to indicate stability and reliability:

    1. Stable Support: Production-ready features with high reliability and long-term support. These are recommended for all production environments and critical applications. Bug reports for this tier are the highest priority.
    2. Preview Support: Functional and generally stable features that may undergo minor API changes. These are ideal for early adopters and development/testing, though edge-case bugs may occur.
    3. Nightly Support: Experimental features under active development. These are subject to breaking changes and variable reliability. They are strictly for experimentation and are not recommended for production use.

  6. Check LightVM platform and architecture compatibility

    LightVM supports a variety of operating systems and architectures across Rust, Node.js, and Web runtimes. Note that support for wasm32 for browsers is currently in an experimental stage.
    OS / RuntimeArchitectureToolchainRustNode.jsWeb
    Windowsx64, ia32MSVC✓✓-
    Linuxx64, ia32, arm64GNU (glibc)✓✓-
    Linux (musl)x64, ia32, arm64musl✓✓-
    macOS (Darwin)x64Apple Clang✓✓-
    Androidarm64, armNDK✓✓-
    FreeBSDx64Clang✓✓-
    Web / Browserwasm32wasm-pack / wasm-bindgen--✓

  7. Resolve symbolic references using Torja in LightVM

    Torja is the core Symbol Resolver of LightVM. It acts as a bridge between high-level bytecode (using human-readable names) and the execution engine (using numerical indices). Before execution, Torja performs a pass to resolve all symbolic references into fixed-position indices to minimize runtime lookups and reduce CPU overhead.

    Key operations include:

    • Symbol Mapping: Pre-loads imports and maps unique variable names to stable integer indices.
    • Dynamic Resolution: Uses get_or_insert_idx logic to assign a new index via an incrementing counter (next_idx) when a new variable is encountered.
    • Instruction Specialization: Transforms name-based instructions into index-based counterparts:
      • get becomes get_idx
      • set becomes set_idx
      • inc becomes inc_idx
      • dec becomes dec_idx
    • Scope Tracking: Registers function parameter names from Func instructions into the symbol table to support the VM's stack-based architecture.

  8. Understand LightVM's core design philosophy

    LightVM operates on three fundamental pillars:

    • Zero Magic (Deterministic): Execution is linear and predictable with no hidden state transitions.
    • Resource Conscious: Engineered for minimal memory usage to operate under tight resource constraints.
    • Explicit Security: Uses a strict Capability system where all permissions and operations must be explicitly defined by the host environment.

  9. Manage the LightVM data stack

    LightVM uses a stack-based architecture for data storage and retrieval. The following opcodes are used to manipulate the stack:

    • push [value]: Inserts a specific value onto the stack.
    • dup: Duplicates the top value currently on the stack.
    • swap: Swaps the top value of the stack with the value immediately below it.

  10. Understand Zero Magic instruction execution in LightVM

    LightVM employs a 'Zero Magic' approach to instruction execution, meaning that execution is linear, completely predictable, and explicit. The VM executes instructions exactly as they are defined without hidden behaviors or implicit side effects.

  11. Listen to LightVM lifecycle events using the on method

    The on method in LightVM is used to register callbacks that trigger when specific VM lifecycle events occur. This is used for logging, monitoring state changes, or executing external logic in real-time. No specific capability is required to use this method. Supported events include Tick, Halt, Panic, Start, and Finish.

  12. Retrieve persisted panic records using the paniclog method

    The paniclog method returns persisted panic records as a structured array, containing bounded diagnostic context and VM state.

    Requirements & Constraints:

    • Capability Required: The VM must be configured with the Debug capability.
    • Wasm Limitation: The .paniclog() method is unavailable in WebAssembly builds.
    • Security Note: Avoid placing sensitive values in the diagnostic context as they will be included in these records.