Documentation
¶
Overview ¶
Package vm implements the AILANG bytecode register virtual machine.
The VM is intentionally isolated from the rest of the compiler. Per the M-BYTECODE-VM design doc §11, this package imports only internal/bytecode. It does NOT import internal/eval, internal/gen/stmt, internal/lower, or internal/core. The VM ↔ evaluator boundary (Phase 2E) will be added via a narrow interface, not a direct dependency.
Phase 2B scope: register frames, dispatch loop, all non-effectful opcodes. BUILTIN_TRAP and EFFECT_TRAP return clear "not implemented" errors.
Index ¶
Constants ¶
const DefaultMaxStack = 1000
DefaultMaxStack is the default frame depth limit. Matches the evaluator's recursion limit so divergence behavior is consistent (§3.6).
Variables ¶
var BuiltinTable = []BuiltinFunc{
builtinShow,
builtinLen,
builtinListGet,
builtinListTail,
builtinConcatString,
builtinRecordGet,
builtinNotBool,
builtinIntToFloat,
builtinListLength,
builtinConcatList,
builtinStrLen,
builtinStrCompare,
builtinStrEq,
builtinStrFind,
builtinStrSlice,
builtinStrTrim,
builtinStrUpper,
builtinStrLower,
builtinStrSplit,
builtinStrChars,
builtinStrStartsWith,
builtinStrEndsWith,
builtinStrJoin,
builtinStrWords,
builtinStrSplitAny,
builtinStrReplace,
builtinStrReplaceMany,
builtinStrStartsWithIC,
builtinStrCharAt,
builtinStrCharCode,
builtinStrDecodeQP,
builtinEscapeXml,
builtinStringIntToStr,
builtinStringFloatToStr,
builtinStringToInt,
builtinStringToFloat,
builtinMathSin,
builtinMathCos,
builtinMathTan,
builtinMathAsin,
builtinMathAcos,
builtinMathAtan,
builtinMathAtan2,
builtinMathSqrt,
builtinMathPow,
builtinMathExp,
builtinMathLog,
builtinMathLog10,
builtinMathFloor,
builtinMathCeil,
builtinMathRound,
builtinMathAbsFloat,
builtinMathAbsInt,
builtinMathPI,
builtinMathE,
builtinFloatToInt,
builtinModInt,
builtinFloatToInt2,
builtinIntToFloat2,
builtinListNth,
builtinListMember,
builtinListDedup,
builtinListDifference,
builtinListIntersect,
builtinListUnion,
builtinJsonEncode,
builtinJsonDecode,
builtinJsonRepair,
builtinXmlElement,
builtinXmlText,
builtinXmlComment,
builtinXmlGetText,
builtinXmlGetTag,
builtinXmlSerialize,
builtinXmlSerializeWithDecl,
builtinXmlParse,
builtinXmlParseElements,
builtinXmlParseWithLimit,
builtinXmlFindAll,
builtinXmlFindFirst,
builtinXmlGetAttr,
builtinXmlGetChildren,
builtinXmlFindAllTexts,
builtinXmlFindAllAttrs,
}
BuiltinTable is the VM-side dispatch table for OpBuiltinCall. The order MUST match compiler.BuiltinTable — both lists are validated at startup by validateBuiltinTables (called from the VM constructor in tests).
Phase 2C scope: only the pure builtins reachable from the golden corpus (`tests/golden/codegen/`). All other builtins lower to OpBuiltinTrap and will be wired through the evaluator in Phase 2E.
var ErrStackOverflow = errors.New("vm: stack overflow")
ErrStackOverflow is returned when the call stack exceeds MaxStack frames.
var HOFBuiltinTable = []HOFBuiltinFunc{
hofBuiltinListMap,
hofBuiltinListFilter,
hofBuiltinListFoldl,
hofBuiltinStrFoldChars,
hofBuiltinStrFoldSlices,
hofBuiltinStrMapSlicesJoin,
hofBuiltinXmlParseFold,
}
HOFBuiltinTable is the VM-side dispatch table for OpBuiltinCallHOF. The order MUST match compiler.HOFBuiltinTable — both lists are validated at startup by validateBuiltinTables.
Functions ¶
This section is empty.
Types ¶
type BuiltinFunc ¶
BuiltinFunc is a pure-builtin handler. It receives the argument slice (read directly from the caller's register window) and returns a result value or an error.
type ClosureCaller ¶
type ClosureCaller interface {
CallClosure(closure bytecode.Value, args []bytecode.Value) (bytecode.Value, error)
}
ClosureCaller is the minimal interface a HOF builtin needs to invoke closure arguments. Implemented by *VM. Keeps HOF builtins decoupled from VM internals.
type EvalInterop ¶
type EvalInterop interface {
CallEvalFunc(name string, args []bytecode.Value) (bytecode.Value, error)
}
EvalInterop is the VM-side view of the evaluator. The VM uses it to dispatch function calls whose target prototype is marked EvalOnly: the function exists in the program but the bytecode compiler couldn't compile it (e.g. it uses effects, dynamic dispatch, or unsupported builtins). At call time the VM hands the bridged arguments to the implementation, which is responsible for running the named function in the evaluator and returning a bridged result.
Per M-BYTECODE-VM §11, the VM package does NOT import internal/eval. The implementation lives in cmd/ailang (or any caller that wires the VM) and performs bytecode.Value ↔ eval.Value conversion internally.
CallEvalFunc is the only entry point. It takes a function name (matching bytecode.FuncPrototype.Name) and the already-evaluated VM arguments, and returns the function's result as a VM value or a non-nil error.
Errors returned from CallEvalFunc are wrapped into VMError by the VM with the call site's source location, so the implementation does not need to add file/line info itself.
type Frame ¶
type Frame struct {
// Proto is the function being executed.
Proto *bytecode.FuncPrototype
// IP is the index of the next instruction to execute in Proto.Instructions.
IP int
// Regs is this frame's register slab. Sized to Proto.NumRegs at creation.
Regs []bytecode.Value
// ReturnReg is the register in the *caller's* frame where this frame's
// return value should be written when this frame returns. Ignored for
// the entry frame.
ReturnReg uint8
// Caller links to the parent frame, or nil for the entry frame.
Caller *Frame
}
Frame is a single call activation. Frames are allocated on each CALL and reused on TAIL_CALL (the register slab is resized in place if the callee has a different register count).
type HOFBuiltinFunc ¶
HOFBuiltinFunc is a higher-order builtin that can call VM closures. Used by OpBuiltinCallHOF dispatch.
type VM ¶
type VM struct {
Image *bytecode.BytecodeImage
MaxStack int
// Stack tracks the active frames for overflow detection. The currently
// executing frame is the top; entries below it are paused callers.
Stack []*Frame
// Interop is the optional bridge to the tree-walking evaluator. Set by
// the CLI when running a mixed-mode program: when OpCall/OpTailCall hits
// a callee whose prototype is marked EvalOnly, the VM hands the call to
// Interop instead of pushing a new frame. If Interop is nil, the VM
// returns an explicit error instead of silently mis-running the function.
Interop EvalInterop
}
VM is the bytecode virtual machine state.
func NewVM ¶
func NewVM(img *bytecode.BytecodeImage) *VM
NewVM constructs a VM bound to an image. The image is not validated here; the caller should call img.Validate() upfront for hand-assembled images.
func (*VM) CallClosure ¶
CallClosure invokes a closure value with the given arguments and returns the result. Used by HOF builtins to call their function arguments. This pushes a new frame onto the VM stack, runs it, and returns.
Source Files