Expand description
GcRef<T> — the GC-managed reference handle.
Newtype around lua_gc::Gc<T> — Copy under the hood, tracks allocation
in the active Heap (via lua_gc::with_current_heap(...)). An earlier
revision was a thin Rc<T> newtype instead; the surface stayed stable
across the swap (new, ptr_eq, identity, strong_count,
weak_count, downgrade), and existing code touching gc.0 continues
to work — .0 is now Gc<T> instead of Rc<T>.
§Weak refs
Heap-tracked GcWeak<T> handles remember the heap active when they were
created plus the target’s heap allocation token. They upgrade only while
that identity/token pair remains live. Handles to legacy uncollected boxes
still upgrade forever, matching their process-lifetime allocation model.
§Internal GC capability, not the embedding surface (issue #267)
GcRef is a raw, Copy, guard-scoped GC capability: it carries no owner
identity of its own, and its operations assume an active HeapGuard for the
heap that owns the box. Holding a GcRef (or an issued &T from its
Deref) across the owning heap’s drop_all/close, or operating it under a
different heap, is a use-after-free that safe code must not do. The
guard-scoped operations here fail loudly on the one shape that is closable
without reading the box — downgrade/account_buffer panic deref-free
with no active guard (issue #267 F1/F3). The stale-after-sweep and
foreign-heap shapes are not closed: validating them would mean reading a
possibly-freed box, which is the use-after-free, so the raw type cannot
make arbitrary handle lifetimes safe in release without slot-indexed handles
/ an API-shape change (spec option B).
GcRef is therefore an implementation-crate (lua-types/lua-gc)
capability, not omniLua’s public embedding surface. Embedders never name
it: the omnilua facade exposes only rooted handles (its Value /
RootedValue, which own a Lua, root through a slab key, and return a
stale-handle error on cross-state or post-teardown use) and deliberately does
not re-export raw Gc/GcRef/Heap. Keep it that way — routing embedders
through the rooted handle is what makes the “a handle must not outlive its
heap” invariant real.