Documentation
¶
Overview ¶
Package api defines Lua closures, C closures, and upvalue types.
LClosure wraps a Proto (compiled function) with captured upvalues. CClosure wraps a Go function with associated upvalues. UpVal implements the open/closed duality for captured variables.
Reference: .analysis/07-runtime-infrastructure.md §2
Upvalue management: find, close, and lifecycle operations.
Reference: lua-master/lfunc.c
Closure and UpVal object pools — reuses dead structs to reduce allocation pressure.
LClosures and UpVals are the second and third most frequently allocated GC objects (after tables). Using sync.Pool lets us reuse the struct memory for short-lived closures/upvals instead of going through Go's mallocgc each time.
Index ¶
Constants ¶
const MaxUpVal = 255
MaxUpVal is the maximum number of upvalues per closure.
Variables ¶
This section is empty.
Functions ¶
func CloseUpvals ¶
CloseUpvals closes all open upvalues at or above the given stack level.
func InitUpvals ¶
func InitUpvals(cl *LClosure)
InitUpvals fills all nil upvalue slots in the closure with new closed upvalues. The caller is responsible for linking upvalues into allgc after this returns.
func PutLClosure ¶
func PutLClosure(cl *LClosure)
PutLClosure returns an LClosure to the pool for reuse. Called by the GC sweep phase when a dead closure is unlinked. Clears all reference fields before pooling to help Go's GC.
Types ¶
type CClosure ¶
type CClosure struct {
object.GCHeader // GC metadata
Fn state.CFunction // the Go function
UpVals []object.TValue // upvalues stored inline
}
--------------------------------------------------------------------------- CClosure is a Go function closure with associated upvalues. Upvalues are stored inline as TValues (no sharing between closures).
I13 FIX: Fn uses state.CFunction (canonical type, not func(any)int). ---------------------------------------------------------------------------
func NewCClosure ¶
NewCClosure creates a C closure with n upvalue slots (initially nil).
type LClosure ¶
type LClosure struct {
object.GCHeader // GC metadata
Proto *object.Proto // compiled function prototype
UpVals []*UpVal // captured upvalues (len == Proto.Upvalues)
}
--------------------------------------------------------------------------- LClosure is a Lua function closure. It wraps a Proto with captured upvalues. ---------------------------------------------------------------------------
func NewLClosure ¶
NewLClosure creates a Lua closure with n upvalue slots (initially nil).
type UpVal ¶
type UpVal struct {
object.GCHeader // GC metadata
StackIdx int // stack index when open, -1 when closed
Own object.TValue // storage for closed value
Next *UpVal // next in open list (lower stack level)
Stack *[]object.StackValue // pointer to owning thread's stack (for cross-thread access)
}
--------------------------------------------------------------------------- UpVal represents a captured variable (upvalue).
C4 FIX: Index-based approach to avoid dangling pointers on stack reallocation.
Open state: StackIdx >= 0, value lives at L.Stack[StackIdx].Val Closed state: StackIdx == -1, value lives in Own
The open upvalue list is sorted by stack level in descending order. ---------------------------------------------------------------------------
func (*UpVal) Close ¶
Close captures the current value from the stack and marks as closed. The caller must pass the current stack value at uv.StackIdx.
func (*UpVal) Get ¶
func (uv *UpVal) Get(stack []object.StackValue) object.TValue
Get returns the current value of the upvalue. For closed upvalues (common case), returns Own directly. For open upvalues, reads from the owning thread's stack.
Source Files