Documentation
¶
Index ¶
- Constants
- Variables
- func DescribeCapabilities(mask uint32) string
- func Encode(w io.Writer, m *Module) error
- func EncodeBundle(w io.Writer, consts *vm.Consts, nsChunks map[string]*vm.CodeChunk) error
- func EncodeBundleOrdered(w io.Writer, consts *vm.Consts, nsChunks map[string]*vm.CodeChunk, ...) error
- func EncodeBundleOrderedCompressed(w io.Writer, consts *vm.Consts, nsChunks map[string]*vm.CodeChunk, ...) error
- func EncodeCompilation(w io.Writer, consts *vm.Consts, mainChunk *vm.CodeChunk) error
- func EncodeCompilationCompressed(w io.Writer, consts *vm.Consts, mainChunk *vm.CodeChunk, compress bool) error
- func EncodeModule(w io.Writer, consts *vm.Consts, chunks []*vm.CodeChunk) error
- func FormatVersionReport(tool, versionStr string) string
- func HasSplitDebug(data []byte) bool
- func MinVersionForCapabilities(mask uint32) string
- func NoteDecodeVarRefHit()
- func NoteDecodeVarRefMiss(created bool)
- func ResetDecodeStats()
- func SetDecodeStatsEnabled(enabled bool)
- func SplitDebug(data []byte) (stripped, companion []byte, err error)
- func StripDebug(data []byte) ([]byte, error)
- func UnsupportedCapabilityError(caps uint32) error
- type CapabilityInfo
- type ChunkData
- type DecodeStats
- type ExecUnit
- func DecodeToExecUnit(r io.Reader, resolve VarResolver) (*ExecUnit, error)
- func DecodeToExecUnitBytes(data []byte, resolve VarResolver) (*ExecUnit, error)
- func DecodeToExecUnitBytesWithDebug(data, companion []byte, resolve VarResolver) (*ExecUnit, error)
- func DecodeToExecUnitBytesWithParent(data []byte, resolve VarResolver, parent *vm.Consts) (*ExecUnit, error)
- func DecodeToExecUnitWithParent(r io.Reader, resolve VarResolver, parent *vm.Consts) (*ExecUnit, error)
- type LocalVarEntry
- type Module
- type ModuleBuilder
- type Reader
- func (r *Reader) HasBackingData() bool
- func (r *Reader) Offset() int
- func (r *Reader) ReadByte() (byte, error)
- func (r *Reader) ReadBytes(n int) ([]byte, error)
- func (r *Reader) ReadFloat64() (float64, error)
- func (r *Reader) ReadInt32() (int32, error)
- func (r *Reader) ReadString(n int) (string, error)
- func (r *Reader) ReadSvarint() (int64, error)
- func (r *Reader) ReadUint16() (uint16, error)
- func (r *Reader) ReadUint32() (uint32, error)
- func (r *Reader) ReadUint64() (uint64, error)
- func (r *Reader) ReadVarint() (uint64, error)
- func (r *Reader) Slice(start, end int) []byte
- type SourceEntry
- type VarResolver
- type Writer
- func (w *Writer) Flush() error
- func (w *Writer) WriteByte(b byte) error
- func (w *Writer) WriteBytes(b []byte) error
- func (w *Writer) WriteFloat64(v float64) error
- func (w *Writer) WriteInt32(v int32) error
- func (w *Writer) WriteSvarint(v int64) error
- func (w *Writer) WriteUint16(v uint16) error
- func (w *Writer) WriteUint32(v uint32) error
- func (w *Writer) WriteUint64(v uint64) error
- func (w *Writer) WriteVarint(v uint64) error
Constants ¶
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).
const ( TagVer0 byte = iota << tagVersionShift TagVer1 TagVer2 TagVer3 )
Tag versions.
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.
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.
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).
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).
const DebugCompanionSuffix = ".debug"
DebugCompanionSuffix is appended to a stripped artifact unless the caller chooses an explicit debug-output path.
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.
const SupportedCapabilities = CapOpcodeSet
SupportedCapabilities is the capability mask this runtime accepts. Must match the check in readCapabilities.
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 ¶
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.
var Magic = [4]byte{'L', 'G', 'B', 0x01}
Magic bytes identifying an LGB file.
Functions ¶
func DescribeCapabilities ¶ added in v1.13.0
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 ¶
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 ¶
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 ¶
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 ¶
EncodeModule builds a Module from live VM objects and serializes it.
func FormatVersionReport ¶ added in v1.13.0
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
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
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
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
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
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
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 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) 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 NewReaderBytes ¶ added in v1.12.0
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
HasBackingData reports whether the reader can Slice() raw bytes (built via NewReaderBytes).
func (*Reader) Offset ¶ added in v1.12.0
Offset returns the absolute number of bytes consumed so far.
func (*Reader) ReadFloat64 ¶
ReadFloat64 reads an IEEE 754 little-endian float64.
func (*Reader) ReadString ¶ added in v1.11.1
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 ¶
ReadSvarint reads a signed zigzag-encoded varint.
func (*Reader) ReadUint16 ¶
ReadUint16 reads a little-endian uint16.
func (*Reader) ReadUint32 ¶ added in v1.9.0
ReadUint32 reads a little-endian uint32.
func (*Reader) ReadUint64 ¶ added in v1.12.0
ReadUint64 reads a little-endian uint64.
func (*Reader) ReadVarint ¶
ReadVarint reads an unsigned LEB128-encoded integer.
type SourceEntry ¶
SourceEntry is a source map entry for serialization.
type VarResolver ¶
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 (*Writer) WriteBytes ¶
WriteBytes writes a byte slice.
func (*Writer) WriteFloat64 ¶
WriteFloat64 writes an IEEE 754 little-endian float64.
func (*Writer) WriteInt32 ¶
WriteInt32 writes a little-endian int32.
func (*Writer) WriteSvarint ¶
WriteSvarint writes a signed zigzag-encoded varint.
func (*Writer) WriteUint16 ¶
WriteUint16 writes a little-endian uint16.
func (*Writer) WriteUint32 ¶ added in v1.9.0
WriteUint32 writes a little-endian uint32.
func (*Writer) WriteUint64 ¶ added in v1.12.0
WriteUint64 writes a little-endian uint64.
func (*Writer) WriteVarint ¶
WriteVarint writes an unsigned LEB128-encoded integer.