Documentation
¶
Overview ¶
Package api implements Lua's hybrid array+hash table.
A Lua table has two parts:
- Array part: integer keys 1..N stored in a Go slice (O(1) access)
- Hash part: all other keys stored in an open-addressing hash table using Brent's variation for collision resolution
The # (length) operator finds a "boundary" — an index i where t[i] ~= nil and t[i+1] == nil. This is NOT the same as Go's len().
Reference: .analysis/07-runtime-infrastructure.md §3
Hash part internals for Lua tables.
Implements open-addressing hash table with Brent's variation for collision resolution. Reference: lua-master/ltable.c
Table object pool — reuses dead Table structs to reduce allocation pressure.
Tables are the most frequently allocated GC objects in Lua programs (~96% of allocations in GC benchmarks). Using sync.Pool lets us reuse the struct memory for short-lived tables instead of going through Go's mallocgc each time.
Core Table operations for Lua tables.
Implements Get, Set, RawLen, Next, and constructor. Reference: lua-master/ltable.c
Index ¶
- Constants
- Variables
- func PutTable(t *Table)
- type Table
- func (t *Table) ArrayLen() int
- func (t *Table) EstimateBytes() int64
- func (t *Table) GC() *object.GCHeader
- func (t *Table) Get(key object.TValue) (object.TValue, bool)
- func (t *Table) GetInt(key int64) (object.TValue, bool)
- func (t *Table) GetMetatable() *Table
- func (t *Table) GetStr(key *object.LuaString) (object.TValue, bool)
- func (t *Table) HasTagMethod(tm byte) bool
- func (t *Table) HasWeakKeys() bool
- func (t *Table) HasWeakValues() bool
- func (t *Table) HashLen() int
- func (t *Table) InvalidateFlags()
- func (t *Table) Next(key object.TValue) (nextKey, nextVal object.TValue, ok bool, err error)
- func (t *Table) RawLen() int64
- func (t *Table) ResizeArray(newSize int)
- func (t *Table) Set(key, value object.TValue)
- func (t *Table) SetIfExists(key, value object.TValue) bool
- func (t *Table) SetInt(key int64, value object.TValue)
- func (t *Table) SetMetatable(mt *Table)
- func (t *Table) SetNoTagMethod(tm byte)
- func (t *Table) SetStr(key *object.LuaString, value object.TValue)
Constants ¶
const ( WeakKey byte = 1 // bit 0: weak keys WeakValue byte = 2 // bit 1: weak values )
Weak table mode constants.
Variables ¶
var ErrInvalidKey = errors.New("invalid key to 'next'")
ErrInvalidKey is returned by Next when the given key is not in the table.
Functions ¶
Types ¶
type Table ¶
type Table struct {
object.GCHeader // GC metadata
Array []object.TValue // array part: indices 0..len-1 map to Lua keys 1..len
Nodes []node // hash part: open-addressing with Brent's variation
LsizeNode uint8 // log2(len(nodes)), 0 if nodes == nil
LastFree int // index for free-slot backward scan
Flags byte // metamethod absence cache (bit p = TM p absent)
Metatable *Table // metatable or nil
// Weak table support (__mode metafield)
WeakMode byte // bit 0 = weak keys, bit 1 = weak values
// SizeDelta accumulates the net change in ObjSize from table resizes.
// The VM/API layer checks this after table mutations and calls
// TrackAllocation to update GCDebt. Reset to 0 after consumption.
SizeDelta int64
}
Table is a Lua table with hybrid array + hash storage.
func New ¶
New creates an empty Lua table. arraySize and hashSize are hints for pre-allocation. hashSize will be rounded up to the next power of 2.
func (*Table) EstimateBytes ¶
EstimateBytes returns an approximate byte size for this table, mirroring C Lua's allocation tracking for collectgarbage("count"). sizeof(Table)=80, sizeof(TValue)=24, sizeof(Node)=56 on 64-bit Go.
func (*Table) Get ¶
Get retrieves the value for the given key. Returns (value, found). If the key is not present, returns (object.Nil, false). For integer keys in the array range, accesses the array part directly.
func (*Table) GetInt ¶
GetInt retrieves the value for an integer key. Checks the array part first, then the hash part.
func (*Table) GetMetatable ¶
GetMetatable returns the table's metatable (may be nil).
func (*Table) GetStr ¶
GetStr retrieves the value for a short string key. Uses pointer equality for interned short strings (O(1) amortized).
func (*Table) HasTagMethod ¶
HasTagMethod returns true if the metamethod at index tm might be present. false = definitely absent (cached). true = might be present (check metatable). tm is a TMS enum value (0 = TM_INDEX, ..., 5 = TM_EQ are fast-cached).
func (*Table) HasWeakKeys ¶
HasWeakKeys returns true if this table has weak keys (__mode contains "k").
func (*Table) HasWeakValues ¶
HasWeakValues returns true if this table has weak values (__mode contains "v").
func (*Table) InvalidateFlags ¶
func (t *Table) InvalidateFlags()
InvalidateFlags clears the metamethod absence cache. Must be called when the metatable changes.
func (*Table) Next ¶
Next advances the iterator past the given key and returns the next (key, value) pair. To start iteration, pass object.Nil as key. Returns (key, value, true) for the next entry, or (Nil, Nil, false) when done. Iteration order: array part first (keys 1..N), then hash part.
func (*Table) RawLen ¶
RawLen returns the "raw" length of the table (the # operator result). This finds a boundary: an index i where t[i] ~= nil and t[i+1] == nil.
func (*Table) ResizeArray ¶
ResizeArray grows or shrinks the array part to exactly newSize. Matches C Lua's luaH_resizearray: keeps the hash part unchanged, migrates elements between array and hash as needed. Used by OP_SETLIST to pre-allocate the exact array size.
func (*Table) Set ¶
Set sets the value for the given key. Panics if key is nil or NaN. If the key is new and the hash part is full, triggers a rehash.
func (*Table) SetIfExists ¶
SetIfExists overwrites the value for an existing key and returns true. If the key is not found, returns false without modifying the table. This is the "fast set" path — no insertion, no rehash, single hash lookup.
func (*Table) SetMetatable ¶
SetMetatable sets the table's metatable.
func (*Table) SetNoTagMethod ¶
SetNoTagMethod marks the given tag method as absent in the cache.
Source Files