Documentation
¶
Overview ¶
Package gc implements Lua's incremental mark-and-sweep garbage collector.
The GC runs as a state machine with the following phases:
GCSpause → GCSpropagate → GCSenteratomic → GCSatomic → GCSswpallgc → GCSswpfinobj → GCSswptobefnz → GCSswpend → GCScallfin → GCSpause
Each call to SingleStep does bounded work and advances one step. FullGC runs the state machine to completion for stop-the-world collection.
Key difference from C Lua: sweep only unlinks objects from the allgc chain. Go's tracing GC handles actual memory deallocation once objects are no longer referenced from Go roots.
Reference: lua-master/lgc.c
gen.go — Generational GC (minor/major collections). Mirrors C Lua's lgc.c generational mode (lgc.c:1131-1480).
Index ¶
- Constants
- func Barrier(g *state.GlobalState, parent, child object.GCObject)
- func BarrierBack(g *state.GlobalState, parent object.GCObject)
- func BarrierValue(g *state.GlobalState, parent object.GCObject, val object.TValue)
- func ChangeMode(g *state.GlobalState, L *state.LuaState, newmode byte)
- func CheckFinalizer(g *state.GlobalState, obj object.GCObject)
- func CloseUpvals(g *state.GlobalState, L *state.LuaState, level int)
- func EnterGen(g *state.GlobalState, L *state.LuaState)
- func FullGC(g *state.GlobalState, L *state.LuaState)
- func FullGen(g *state.GlobalState, L *state.LuaState)
- func GCStep(g *state.GlobalState, L *state.LuaState)
- func SetPause(g *state.GlobalState)
- func SingleStep(g *state.GlobalState, L *state.LuaState) int64
- func Udata2Finalize(g *state.GlobalState) object.GCObject
- func YoungCollection(g *state.GlobalState, L *state.LuaState)
Constants ¶
const ( // SWEEPMAX is the maximum number of objects to sweep per incremental step. SWEEPMAX = 20 // GCFINALIZECOST is the work units charged for calling one finalizer. GCFINALIZECOST int64 = 50 )
Variables ¶
This section is empty.
Functions ¶
func Barrier ¶
func Barrier(g *state.GlobalState, parent, child object.GCObject)
Barrier is the forward write barrier. Called when a black parent object gets a reference to a potentially white child. During propagate phase: marks the child (pushes it forward to gray/black). This is a no-op if parent is not black or child is not white.
Mirrors C Lua's luaC_barrier_ (lgc.c:246).
func BarrierBack ¶
func BarrierBack(g *state.GlobalState, parent object.GCObject)
BarrierBack is the backward write barrier for container objects (tables). Called when a black container is mutated. Sets the container back to gray and adds it to the grayagain list for re-traversal in the atomic phase. This is a no-op if the parent is not black.
Mirrors C Lua's luaC_barrierback_ (lgc.c:272).
func BarrierValue ¶
BarrierValue calls Barrier if val contains a GC-collectable object. Convenience wrapper for TValue children.
func ChangeMode ¶
func ChangeMode(g *state.GlobalState, L *state.LuaState, newmode byte)
func CheckFinalizer ¶
func CheckFinalizer(g *state.GlobalState, obj object.GCObject)
CheckFinalizer moves an object from the allgc list to the finobj list if it has a finalizer (__gc metamethod). Called from SetMetatable when __gc is detected. Mirrors C Lua's luaC_checkfinalizer.
The hasFinalizer parameter indicates whether the object has __gc; the caller (API layer) is responsible for checking the metatable.
func CloseUpvals ¶
func CloseUpvals(g *state.GlobalState, L *state.LuaState, level int)
CloseUpvals closes all open upvalues at or above level, applying a forward barrier on each closed upvalue. This wraps closure.CloseUpvals logic with per-upvalue barriers that closure.go can't call (import cycle: gc→closure). Mirrors C Lua's luaF_closeupval + luaC_barrier per upvalue.
func FullGC ¶
func FullGC(g *state.GlobalState, L *state.LuaState)
FullGC performs a complete garbage collection cycle by running the state machine to completion. This is the Go equivalent of C Lua's fullinc (luaC_fullgc).
If a cycle is already in progress (state > GCSpause and <= GCSpropagate), it completes the current cycle first, then runs a fresh one.
func GCStep ¶
func GCStep(g *state.GlobalState, L *state.LuaState)
GCStep performs bounded incremental GC work triggered by the debt-based pacer. Matches C Lua's incstep() (lgc.c:1710-1728):
stepsize = applygcparam(STEPSIZE, 100) work2do = applygcparam(STEPMUL, stepsize / sizeof(void*)) fast = (work2do == 0) // stepsize=0 → full collection per step loop SingleStep until work >= work2do or cycle completes (or fast) if completed: SetPause resets debt based on live data if partial: debt = stepsize (allocation credit until next step)
func SetPause ¶
func SetPause(g *state.GlobalState)
SetPause calculates the GC debt (allocation credit) after a collection. The debt determines how many bytes can be allocated before the next GC cycle triggers. Based on C Lua's setpause():
threshold = estimate * pause / 100 debt = threshold - current_total_bytes
With default pause=200, GC triggers when memory reaches 2x live data.
func SingleStep ¶
func SingleStep(g *state.GlobalState, L *state.LuaState) int64
SingleStep performs one incremental step of the GC state machine. Returns approximate work units done in this step. Mirrors C Lua's singlestep() in lgc.c.
func Udata2Finalize ¶
func Udata2Finalize(g *state.GlobalState) object.GCObject
Udata2Finalize removes the first object from the tobefnz list and links it back into allgc. Clears the FinalizedBit so the object is "normal" again (can be re-finalized if it gets a new __gc). Returns nil if tobefnz is empty. Mirrors C Lua's udata2finalize.
func YoungCollection ¶
func YoungCollection(g *state.GlobalState, L *state.LuaState)
Types ¶
This section is empty.
Source Files