Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Execution Model

Forge provides three execution tiers, selectable at the command line. All tiers accept the same source files; they differ in feature coverage, performance, and implementation strategy.

Three Tiers

TierFlagImplementationPerformanceFeature Coverage
Bytecode VM(default)Register-based VM~10x faster than interpreterNear-full (~95%)
Interpreter--interpTree-walkingBaselineFull (100%)
JIT Compiler--jitCranelift native code~50-100x faster than interpreterMinimal (~30%)
 
forge run program.fg            # Bytecode VM (default)
forge run program.fg --interp   # Interpreter (full feature coverage)
forge run program.fg --jit      # JIT compiler (maximum speed)

When to Use Each Tier

Bytecode VM (Default)

The VM is the default engine as of v0.7.0. Use it for:

  • All general-purpose development
  • Compute-intensive loops and numerical work
  • Programs using must, ask, freeze, spawn/await, schedule/watch
  • Full standard library access (math, fs, io, crypto, http, etc.)

The VM compiles Forge source to register-based bytecode and executes it in a virtual machine with mark-sweep garbage collection. Programs using decorator-driven HTTP servers (@server, @get, etc.) automatically fall back to the interpreter.

Interpreter (--interp)

Use the interpreter for:

  • HTTP servers (@server, @get, @post)
  • Any features not yet ported to the VM
  • Debugging with the DAP server (forge dap)

The interpreter supports every feature of the language. It is the reference implementation and fallback for VM-incompatible programs.

JIT Compiler (--jit)

Use the JIT for:

  • Maximum performance on hot numerical code
  • Benchmarking (e.g., fib(30) runs 11x faster than Python)
  • Functions that are purely computational

The JIT compiles hot functions to native machine code via Cranelift. It supports the smallest subset of the language – primarily arithmetic, function calls, and basic control flow.

Trade-off Summary

Feature Coverage:  Interpreter > VM > JIT
Performance:       JIT > VM > Interpreter
Startup Time:      Interpreter < VM < JIT

The bytecode VM is the default for a balance of performance and feature coverage. Use --interp for full features (decorator-driven servers), or --jit for maximum speed on numeric workloads.