bytecode

package
v1.13.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 20, 2026 License: MIT Imports: 17 Imported by: 0

Documentation

Index

Constants

View Source
const (
	FlagConstsBase   uint16 = 1 << iota // ConstsBase field is present in consts section
	FlagCapabilities                    // Capability mask follows the header
	FlagLocalVars                       // per-chunk local-variable debug tables follow the NS table (v2+)
	// FlagCompressed: the module body (everything after the header + capability
	// section) is a single compressed stream, prefixed by its declared
	// uncompressed size and a codec byte. The magic, version, flags, and
	// capability payload — including the opcode-set signature — stay plaintext,
	// so a version/opcode mismatch is still rejected before any inflate.
	// Compression is opt-in at compile time
	// (lg -c -z / lg -b -z); a bundle without this bit decodes byte-identically
	// to before.
	FlagCompressed
	// FlagDebugSplit marks an artifact whose source maps and local-variable
	// tables live in an external, digest-bound debug companion.
	FlagDebugSplit
)

Module flags. Bits are positional via iota — never write an explicit shift. Append new flags before flagsEnd; knownFlags is the derived full mask and must not be used as the admitted set for older format versions (see vNFlags below).

View Source
const (
	TagVer0 byte = iota << tagVersionShift
	TagVer1
	TagVer2
	TagVer3
)

Tag versions.

View Source
const (
	TagIDNil        byte = 0x00
	TagIDTrue       byte = 0x01
	TagIDFalse      byte = 0x02
	TagIDInt        byte = 0x03
	TagIDFloat      byte = 0x04
	TagIDString     byte = 0x05
	TagIDKeyword    byte = 0x06
	TagIDSymbol     byte = 0x07
	TagIDChar       byte = 0x08
	TagIDBigInt     byte = 0x09
	TagIDVoid       byte = 0x0A
	TagIDUUID       byte = 0x0B
	TagIDInstant    byte = 0x0C
	TagIDFunc       byte = 0x10
	TagIDVarRef     byte = 0x11
	TagIDEmptyList  byte = 0x20
	TagIDList       byte = 0x21
	TagIDVector     byte = 0x22
	TagIDMap        byte = 0x23
	TagIDSet        byte = 0x24
	TagIDRecordType byte = 0x30
	TagIDRecord     byte = 0x31
	TagIDRegex      byte = 0x32
	TagIDAtom       byte = 0x33
)

Tag IDs (6-bit). These are the semantic tag identifiers.

View Source
const (
	TagNil        byte = TagIDNil | TagVer0
	TagTrue       byte = TagIDTrue | TagVer0
	TagFalse      byte = TagIDFalse | TagVer0
	TagInt        byte = TagIDInt | TagVer0
	TagFloat      byte = TagIDFloat | TagVer0
	TagString     byte = TagIDString | TagVer0
	TagKeyword    byte = TagIDKeyword | TagVer0
	TagSymbol     byte = TagIDSymbol | TagVer0
	TagChar       byte = TagIDChar | TagVer0
	TagBigInt     byte = TagIDBigInt | TagVer0
	TagVoid       byte = TagIDVoid | TagVer0
	TagUUID       byte = TagIDUUID | TagVer0
	TagInstant    byte = TagIDInstant | TagVer0
	TagFunc       byte = TagIDFunc | TagVer0
	TagVarRef     byte = TagIDVarRef | TagVer0
	TagEmptyList  byte = TagIDEmptyList | TagVer0
	TagList       byte = TagIDList | TagVer0
	TagVector     byte = TagIDVector | TagVer0
	TagMap        byte = TagIDMap | TagVer0
	TagSet        byte = TagIDSet | TagVer0
	TagRecordType byte = TagIDRecordType | TagVer0
	TagRecord     byte = TagIDRecord | TagVer0
	TagRegex      byte = TagIDRegex | TagVer0
	TagAtom       byte = TagIDAtom | TagVer0
)

Tag byte values (version 0). These are the actual bytes on the wire for the initial v2 release. They are byte-identical to v1 tags.

View Source
const (
	TagIDReserved0  byte = 0x34
	TagIDReserved1  byte = 0x35
	TagIDReserved2  byte = 0x36
	TagIDReserved3  byte = 0x37
	TagIDReserved4  byte = 0x38
	TagIDReserved5  byte = 0x39
	TagIDReserved6  byte = 0x3A
	TagIDReserved7  byte = 0x3B
	TagIDReserved8  byte = 0x3C
	TagIDReserved9  byte = 0x3D
	TagIDReserved10 byte = 0x3E
	TagIDReserved11 byte = 0x3F
)

Reserved tag IDs for future standard tags (0x34–0x3F).

View Source
const (
	// CapOpcodeSet: the capability mask is followed by the producer's opcode-set
	// signature (varint opcode count + uint64 FNV-64a hash of the mnemonics in
	// enum order). The decoder rejects the bundle when the signature differs
	// from the running VM's, so an opcode-enum change between the tree that
	// compiled a bundle and the tree running it fails with a clear message
	// instead of decoding shifted opcodes into undefined behavior.
	CapOpcodeSet uint32 = 1 << 0
)

Capability bits (valid when FlagCapabilities is set).

View Source
const DebugCompanionSuffix = ".debug"

DebugCompanionSuffix is appended to a stripped artifact unless the caller chooses an explicit debug-output path.

View Source
const FormatVersion uint16 = 3

FormatVersion is the newest serialization format version. Version 3 adds the compressed-body framing. Plain bundles continue to use version 2 so compression remains opt-in and their encoding stays byte-identical.

View Source
const SupportedCapabilities = CapOpcodeSet

SupportedCapabilities is the capability mask this runtime accepts. Must match the check in readCapabilities.

View Source
const (
	// TagDefMetaPairs stores alternating metadata keys and values using the map
	// payload shape without eagerly constructing a PersistentMap at decode.
	// Older v2 readers reject the non-zero tag version instead of silently
	// treating the compact representation as ordinary metadata.
	TagDefMetaPairs byte = TagIDMap | TagVer1
)

Versioned tag variants.

Variables

View Source
var KnownCapabilities = []CapabilityInfo{
	{Bit: CapOpcodeSet, Name: "CapOpcodeSet", Since: "1.12.0"},
}

KnownCapabilities lists every capability bit this tree knows about, in bit order. SupportedCapabilities is the subset this runtime accepts.

View Source
var Magic = [4]byte{'L', 'G', 'B', 0x01}

Magic bytes identifying an LGB file.

Functions

func DescribeCapabilities added in v1.13.0

func DescribeCapabilities(mask uint32) string

DescribeCapabilities formats a capability mask for humans: named bits as CapName (0x…, since vX.Y.Z), unknown bits as "unknown bit N (0x…)".

func Encode

func Encode(w io.Writer, m *Module) error

Encode serializes a Module to binary format. When m.Flags has FlagCompressed set, the header (magic, version, flags, capabilities) is written in plaintext and the body is emitted as a single DEFLATE stream after its declared uncompressed size and a one-byte codec tag. Otherwise the whole module is written uncompressed, byte-identically to before.

func EncodeBundle

func EncodeBundle(w io.Writer, consts *vm.Consts, nsChunks map[string]*vm.CodeChunk) error

EncodeBundle serializes a multi-namespace compilation bundle. Namespaces are registered in sorted name order so output is deterministic across runs; callers that need a specific load order should use EncodeBundleOrdered instead.

func EncodeBundleOrdered added in v1.3.5

func EncodeBundleOrdered(w io.Writer, consts *vm.Consts, nsChunks map[string]*vm.CodeChunk, nsOrder []string) error

EncodeBundleOrdered serializes a multi-namespace bundle with explicit ordering. nsOrder determines the chunk index assignment (lower index = earlier dependency).

func EncodeBundleOrderedCompressed added in v1.13.0

func EncodeBundleOrderedCompressed(w io.Writer, consts *vm.Consts, nsChunks map[string]*vm.CodeChunk, nsOrder []string, compress bool) error

EncodeBundleOrderedCompressed is EncodeBundleOrdered with an opt-in DEFLATE body (see FlagCompressed). compress=false is byte-identical to EncodeBundleOrdered.

func EncodeCompilation

func EncodeCompilation(w io.Writer, consts *vm.Consts, mainChunk *vm.CodeChunk) error

EncodeCompilation serializes a compilation result (main chunk + const pool). The main chunk is always chunk index 0. All CodeChunks referenced by Funcs in the const pool are collected automatically. If consts is a child pool, only the child's entries are serialized with the base offset stored so the decoder can reconstruct the layering.

func EncodeCompilationCompressed added in v1.13.0

func EncodeCompilationCompressed(w io.Writer, consts *vm.Consts, mainChunk *vm.CodeChunk, compress bool) error

EncodeCompilationCompressed is EncodeCompilation with an opt-in DEFLATE body (see FlagCompressed). compress=false is byte-identical to EncodeCompilation.

func EncodeModule

func EncodeModule(w io.Writer, consts *vm.Consts, chunks []*vm.CodeChunk) error

EncodeModule builds a Module from live VM objects and serializes it.

func FormatVersionReport added in v1.13.0

func FormatVersionReport(tool, versionStr string) string

FormatVersionReport returns the multi-line -v/--version body for tool (e.g. "lg" or "lg-runtime") at the given version string.

The lgb line reports both the default write version (plain bundles stay on uncompressedFormatVersion) and FormatVersion (the newest this tree reads and writes when a newer-only flag such as FlagCompressed is set).

func HasSplitDebug added in v1.13.0

func HasSplitDebug(data []byte) bool

HasSplitDebug reports whether data has an LGB header marked for an external debug companion. It is intentionally a cheap header probe: full format and capability validation remains the decoder's responsibility.

func MinVersionForCapabilities added in v1.13.0

func MinVersionForCapabilities(mask uint32) string

MinVersionForCapabilities returns the highest Since among named bits in mask, or "" when mask has no named capabilities (unknown bits alone).

func NoteDecodeVarRefHit added in v1.11.1

func NoteDecodeVarRefHit()

func NoteDecodeVarRefMiss added in v1.11.1

func NoteDecodeVarRefMiss(created bool)

func ResetDecodeStats added in v1.11.1

func ResetDecodeStats()

func SetDecodeStatsEnabled added in v1.11.1

func SetDecodeStatsEnabled(enabled bool)

func SplitDebug added in v1.13.0

func SplitDebug(data []byte) (stripped, companion []byte, err error)

SplitDebug removes source maps and local-variable tables from an LGB and returns both the smaller runtime artifact and a digest-bound companion that can restore its debug information. Chunk code and ordering are checked after the strip so the companion can never be emitted against a structurally different program.

func StripDebug added in v1.13.0

func StripDebug(data []byte) ([]byte, error)

StripDebug re-encodes an .lgb without its debug sections: per-chunk source maps and local-variable tables. Execution is unaffected — the VM consults both only for error reporting and debugging — so a stripped bundle trades source-located errors for size (about 20% on the core bundle). Existing encoding flags such as FlagCompressed are preserved, and FlagDebugSplit is added so a companion produced by SplitDebug can safely restore the tables.

func UnsupportedCapabilityError added in v1.13.0

func UnsupportedCapabilityError(caps uint32) error

UnsupportedCapabilityError builds the user-facing reject for a capability mask that asks for bits this runtime does not support.

Types

type CapabilityInfo added in v1.13.0

type CapabilityInfo struct {
	Bit   uint32
	Name  string
	Since string // semver without leading "v", e.g. "1.12.0"
}

CapabilityInfo names a known capability bit and the lg release that first accepted it. Keep this in sync when adding bits to the Capability constants in tags.go — the reject path and `lg -v` both read from here.

type ChunkData

type ChunkData struct {
	MaxStack  int
	Code      []int32
	SourceMap []SourceEntry
	// LocalVars is the chunk's local-variable debug table (slot -> name),
	// serialized in an optional section under FlagLocalVars.
	LocalVars []LocalVarEntry
}

ChunkData holds the data for a single code chunk.

type DecodeStats added in v1.11.1

type DecodeStats struct {
	Tags          [64]uint64
	StringEntries uint64
	StringBytes   uint64
	VarRefHits    uint64
	VarRefMisses  uint64
	VarRefCreates uint64
}

func SnapshotDecodeStats added in v1.11.1

func SnapshotDecodeStats() DecodeStats

func (DecodeStats) Summary added in v1.11.1

func (s DecodeStats) Summary() string

type ExecUnit

type ExecUnit struct {
	Consts    *vm.Consts
	MainChunk *vm.CodeChunk
	// NSChunks maps namespace names to their main chunks (for bundles).
	NSChunks map[string]*vm.CodeChunk
	// NSOrder lists namespace names in chunk index order (load/dependency order).
	NSOrder []string
}

ExecUnit is a decoded compilation unit ready for execution.

func DecodeToExecUnit

func DecodeToExecUnit(r io.Reader, resolve VarResolver) (*ExecUnit, error)

DecodeToExecUnit decodes an LGB module and returns a ready-to-execute unit. The main chunk is chunk index 0. All decoded consts are populated into a shared Consts pool that all chunks reference.

func DecodeToExecUnitBytes added in v1.12.0

func DecodeToExecUnitBytes(data []byte, resolve VarResolver) (*ExecUnit, error)

DecodeToExecUnitBytes is like DecodeToExecUnit but decodes from an in-memory buffer. The buffer stays resident, so per-chunk source maps are captured zero-copy and decoded lazily (on first error/stack-trace lookup) instead of eagerly at load — removing the dominant startup heap churn. Prefer this for the embedded core bundle, which is already a []byte.

func DecodeToExecUnitBytesWithDebug added in v1.13.0

func DecodeToExecUnitBytesWithDebug(data, companion []byte, resolve VarResolver) (*ExecUnit, error)

DecodeToExecUnitBytesWithDebug decodes an LGB and, when it is marked as split-debug, verifies and attaches the supplied companion before execution. A companion beside an ordinary unstripped LGB is ignored, which makes stale sidecars harmless after recompiling without -strip.

func DecodeToExecUnitBytesWithParent added in v1.12.0

func DecodeToExecUnitBytesWithParent(data []byte, resolve VarResolver, parent *vm.Consts) (*ExecUnit, error)

DecodeToExecUnitBytesWithParent is DecodeToExecUnitBytes with an optional parent const pool (see DecodeToExecUnitWithParent).

func DecodeToExecUnitWithParent

func DecodeToExecUnitWithParent(r io.Reader, resolve VarResolver, parent *vm.Consts) (*ExecUnit, error)

DecodeToExecUnitWithParent decodes an LGB module with an optional parent const pool. If parent is non-nil and the module has a ConstsBase, the decoded consts are layered on top of the parent pool — indices < base resolve from the parent.

type LocalVarEntry added in v1.10.0

type LocalVarEntry struct {
	Slot int
	Name string
}

LocalVarEntry is a local-variable debug entry for serialization.

type Module

type Module struct {
	Version uint16
	Flags   uint16
	// Capabilities is an optional feature mask. If FlagCapabilities is set in Flags,
	// a uint32 capability mask follows the header. Bits indicate optional features
	// the decoder must support; see KnownCapabilities / CapOpcodeSet.
	Capabilities uint32
	Strings      []string
	Chunks       []*ChunkData
	Consts       []vm.Value
	// ConstsBase is the starting global index for the consts in this module.
	// For layered pools, indices 0..ConstsBase-1 are in a parent pool.
	ConstsBase int
	// NSTable maps namespace names to their main chunk indices (for bundles).
	NSTable map[string]int
}

Module is the serializable unit — a complete compilation result.

func Decode

func Decode(r io.Reader) (*Module, error)

Decode reads a binary module from r.

func DecodeWithResolver

func DecodeWithResolver(r io.Reader, resolve VarResolver) (*Module, error)

DecodeWithResolver reads a binary module, resolving var references with the given function.

type ModuleBuilder

type ModuleBuilder struct {
	// contains filtered or unexported fields
}

ModuleBuilder collects strings, chunks, and consts for serialization.

func NewModuleBuilder

func NewModuleBuilder() *ModuleBuilder

NewModuleBuilder creates a new builder.

func (*ModuleBuilder) AddChunk

func (b *ModuleBuilder) AddChunk(c *vm.CodeChunk) int

AddChunk registers a CodeChunk and interns its strings.

func (*ModuleBuilder) AddConst

func (b *ModuleBuilder) AddConst(v vm.Value)

AddConst registers a const value and interns related strings/chunks.

func (*ModuleBuilder) Build

func (b *ModuleBuilder) Build() *Module

Build creates the Module.

func (*ModuleBuilder) ChunkIndex

func (b *ModuleBuilder) ChunkIndex(c *vm.CodeChunk) (int, bool)

ChunkIndex returns the index for a given CodeChunk pointer.

func (*ModuleBuilder) SetNSEntry

func (b *ModuleBuilder) SetNSEntry(name string, chunk *vm.CodeChunk)

SetNSEntry records a namespace name → main chunk mapping for bundle modules.

type Reader

type Reader struct {
	// contains filtered or unexported fields
}

Reader wraps a buffered reader with binary decoding helpers.

func NewReader

func NewReader(r io.Reader) *Reader

NewReader creates a Reader wrapping r.

func NewReaderBytes added in v1.12.0

func NewReaderBytes(data []byte) *Reader

NewReaderBytes creates a Reader over an in-memory buffer. Reads still stream through bufio, but the reader retains `data` so the decoder can Slice() a section's raw bytes zero-copy (the buffer stays resident) and defer decoding.

func (*Reader) HasBackingData added in v1.12.0

func (r *Reader) HasBackingData() bool

HasBackingData reports whether the reader can Slice() raw bytes (built via NewReaderBytes).

func (*Reader) Offset added in v1.12.0

func (r *Reader) Offset() int

Offset returns the absolute number of bytes consumed so far.

func (*Reader) ReadByte

func (r *Reader) ReadByte() (byte, error)

ReadByte reads a single byte.

func (*Reader) ReadBytes

func (r *Reader) ReadBytes(n int) ([]byte, error)

ReadBytes reads exactly n bytes.

func (*Reader) ReadFloat64

func (r *Reader) ReadFloat64() (float64, error)

ReadFloat64 reads an IEEE 754 little-endian float64.

func (*Reader) ReadInt32

func (r *Reader) ReadInt32() (int32, error)

ReadInt32 reads a little-endian int32.

func (*Reader) ReadString added in v1.11.1

func (r *Reader) ReadString(n int) (string, error)

ReadString reads exactly n bytes and returns them as a string with a single backing allocation. The returned string owns its storage and is safe to retain after the reader advances.

func (*Reader) ReadSvarint

func (r *Reader) ReadSvarint() (int64, error)

ReadSvarint reads a signed zigzag-encoded varint.

func (*Reader) ReadUint16

func (r *Reader) ReadUint16() (uint16, error)

ReadUint16 reads a little-endian uint16.

func (*Reader) ReadUint32 added in v1.9.0

func (r *Reader) ReadUint32() (uint32, error)

ReadUint32 reads a little-endian uint32.

func (*Reader) ReadUint64 added in v1.12.0

func (r *Reader) ReadUint64() (uint64, error)

ReadUint64 reads a little-endian uint64.

func (*Reader) ReadVarint

func (r *Reader) ReadVarint() (uint64, error)

ReadVarint reads an unsigned LEB128-encoded integer.

func (*Reader) Slice added in v1.12.0

func (r *Reader) Slice(start, end int) []byte

Slice returns data[start:end] of the backing buffer (zero-copy). Only valid when HasBackingData() is true and [start,end] is within already-consumed input.

type SourceEntry

type SourceEntry struct {
	StartIP                          int
	File                             string
	Line, Column, EndLine, EndColumn int
}

SourceEntry is a source map entry for serialization.

type VarResolver

type VarResolver func(ns, name string) *vm.Var

VarResolver resolves a var reference by namespace and name.

type Writer

type Writer struct {
	// contains filtered or unexported fields
}

Writer wraps a buffered writer with binary encoding helpers.

func NewWriter

func NewWriter(w io.Writer) *Writer

NewWriter creates a Writer wrapping w.

func (*Writer) Flush

func (w *Writer) Flush() error

Flush flushes the underlying buffer.

func (*Writer) WriteByte

func (w *Writer) WriteByte(b byte) error

WriteByte writes a single byte.

func (*Writer) WriteBytes

func (w *Writer) WriteBytes(b []byte) error

WriteBytes writes a byte slice.

func (*Writer) WriteFloat64

func (w *Writer) WriteFloat64(v float64) error

WriteFloat64 writes an IEEE 754 little-endian float64.

func (*Writer) WriteInt32

func (w *Writer) WriteInt32(v int32) error

WriteInt32 writes a little-endian int32.

func (*Writer) WriteSvarint

func (w *Writer) WriteSvarint(v int64) error

WriteSvarint writes a signed zigzag-encoded varint.

func (*Writer) WriteUint16

func (w *Writer) WriteUint16(v uint16) error

WriteUint16 writes a little-endian uint16.

func (*Writer) WriteUint32 added in v1.9.0

func (w *Writer) WriteUint32(v uint32) error

WriteUint32 writes a little-endian uint32.

func (*Writer) WriteUint64 added in v1.12.0

func (w *Writer) WriteUint64(v uint64) error

WriteUint64 writes a little-endian uint64.

func (*Writer) WriteVarint

func (w *Writer) WriteVarint(v uint64) error

WriteVarint writes an unsigned LEB128-encoded integer.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL