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 and slice pools — reuses dead Table structs and backing slices 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.
Slice pools index by log2(capacity) so that power-of-2 sized slices are reused across tables of similar sizes.
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) MarkNodeKeyDead(i int)
- func (t *Table) Next(key object.TValue) (nextKey, nextVal object.TValue, ok bool, err error)
- func (t *Table) NodeKeyGCHeader(i int) *object.GCHeader
- func (t *Table) NodeKeyPtr(i int) unsafe.Pointer
- 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").
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) MarkNodeKeyDead ¶ added in v0.5.0
MarkNodeKeyDead marks the key at node index i as dead. Preserves KeyN/KeyPtr for hash chain probing.
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) NodeKeyGCHeader ¶ added in v0.5.0
NodeKeyGCHeader returns the GCHeader for a node key at index i. Precondition: the node's KeyTT has BIT_ISCOLLECTABLE set and KeyPtr is non-nil. For string keys, KeyPtr points directly to the LuaString (GCHeader is first field). For rare collectable types, KeyPtr also points to the object (GCHeader first field).
func (*Table) NodeKeyPtr ¶ added in v0.5.0
NodeKeyPtr returns the raw key pointer for a node at index i. Used by GC to reconstruct GCObject for rare collectable key types.
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