Struct GcRef 

pub struct GcRef<T>(pub Gc<T>)
where
    T: Trace + 'static;

A GC-managed pointer to a Lua collectable object. Newtype over lua_gc::Gc<T> so callers preserve gc.0-shape access while the backend swaps under them.

Tuple Fields

0: Gc<T>

Implementations

impl<T> GcRef<T>

where T: Trace + 'static,

pub fn new(value: T) -> GcRef<T>

Allocate a new GC-tracked value on the active heap: joins the allgc chain under a HeapGuard (set by state.run() / pcall_k / with_state), or the heap’s bootstrap list inside a bootstrap window.

Panics if no heap is active. There is no fallback: the old detached arm allocated a box no heap ever freed (issue #249’s leak class), and since #253 moved host-side LuaError messages to owned bytes, no legitimate guard-less allocation path remains — a panic here is always a missing guard on the entry path, and the message says so.

impl<T> GcRef<T>

where T: Trace + 'static,

pub fn ptr_eq(a: &GcRef<T>, b: &GcRef<T>) -> bool

Two GcRefs are identity-equal iff they point at the same box.

pub fn identity(&self) -> usize

Identity as a usize — used as a HashMap key for “same object” tests.

pub fn strong_count(&self) -> usize

Number of strong references. GcRef is not reference-counted, so a live handle reports one owning GC reachability handle.

pub fn weak_count(&self) -> usize

Number of weak references. Weak handles are not counted.

pub fn downgrade(&self) -> GcWeak<T>

Get a weak handle. If this allocation belongs to the currently-active heap, the weak handle will stop upgrading once sweep removes that exact heap allocation.

No-guard path is deref-free (issue #267 F1)

With no active HeapGuard there is no heap to validate against, and the handle must not read the box to decide — if its owning heap has been dropped, the box is freed and that read is itself the use-after-free (the old is_heap_owned() check was exactly this UAF-in-the-safety-check). So this panics unconditionally, reading nothing, consistent with GcRef::new’s guard-less panic and the always-on guard policy. The legacy detached-box “always upgrades on a guard-less downgrade” path is dropped with it.

Guarded path and residuals (issue #267)

The guarded path mints a token against the active heap without dereferencing the box — so a same-heap downgrade is validated by the allocation token, and when the active guard is a closed heap the closed-heap token refusal makes the resulting weak handle permanently dead. The stale corners this cannot fix in release — a foreign-heap downgrade (the box’s owner is a different heap), a same-heap re-downgrade of a box already swept while unrooted, and an already-issued &T outliving a later drop_all(&self) — are not closed here: validating them would require reading the (possibly freed) box, which is the use-after-free. They are documented residuals that only slot-indexed handles / an API-shape change (spec option B) close; see the spec and the stale_handle_kit.

pub fn account_buffer(&self, delta: isize)

Charge (delta > 0) or refund (delta < 0) bytes of this object’s owned heap buffers against the active heap’s pacer, so collections fire at honest memory pressure. No-op on delta == 0 or when the underlying box is uncollected (see lua_gc::Gc::account_buffer).

No-guard path is deref-free (issue #267 F3)

With no active HeapGuard this panics unconditionally, reading nothing: the charge would otherwise be silently dropped (pacer drift), and — as with downgrade — reading the box to decide would be a use-after-free if the heap has been dropped (the old is_heap_owned() check was that UAF). The legacy detached no-op path is dropped with it.

The guarded charge intrinsically reads the box (it mutates header.size), so — unlike the no-guard path — it cannot be made deref-free: a charge against a stale box under an active guard reads that box, which is the same option-B residual as downgrade. Under quarantine a same-heap swept target is caught by the HDR_FREED debug_assert in as_box; in release it is a documented residual (see the spec).

Trait Implementations

impl<T> AsRef<T> for GcRef<T>

where T: Trace + 'static,

fn as_ref(&self) -> &T

Converts this type into a shared reference of the (usually inferred) input type.

impl<T> Clone for GcRef<T>

where T: Trace + 'static,

fn clone(&self) -> GcRef<T>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T> Copy for GcRef<T>

where T: Trace + 'static,

impl<T> Debug for GcRef<T>

where T: Debug + Trace + 'static,

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<T> Deref for GcRef<T>

where T: Trace + 'static,

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &T

Dereferences the value.

impl LuaLClosureRefExt for GcRef<LuaLClosure>

fn proto(&self) -> &GcRef<LuaProto>

fn nupvalues(&self) -> usize

impl LuaStringRefExt for GcRef<LuaString>

fn is_white(&self) -> bool

fn hash(&self) -> u32

fn as_gc_ref(&self) -> GcRef<LuaString>

impl LuaTableRefExt for GcRef<LuaTable>

fn raw_set( &self, state: &mut LuaState, k: LuaValue, v: LuaValue, ) -> Result<(), LuaError>

Forwards to LuaTable::try_raw_set, which performs the nil/NaN key validation internally as part of its integer-fast-path match.

A collectable KEY stored into the table needs its own backward barrier, mirroring C-Lua’s luaC_barrierback(L, obj2gco(t), key) inside luaH_newkey (ltable.c:717). Without it a young key inserted into an old table is invisible to the generational collector and is freed while still referenced — the 2026-06-09 table livelock.

fn raw_set_short_str( &self, state: &mut LuaState, k: GcRef<LuaString>, v: LuaValue, ) -> Result<(), LuaError>

The miss arm inserts a NEW short-string key, so the key itself is barriered (C-Lua does this inside luaH_newkey, ltable.c:717); the hit arm only overwrites a value whose key is already traced.

fn metatable(&self) -> Option<GcRef<LuaTable>>

fn has_metatable(&self) -> bool

fn as_ptr(&self) -> *const ()

fn get(&self, k: &LuaValue) -> LuaValue

fn get_int(&self, k: i64) -> LuaValue

fn get_short_str(&self, k: &GcRef<LuaString>) -> LuaValue

fn raw_set_int( &self, _state: &mut LuaState, k: i64, v: LuaValue, ) -> Result<(), LuaError>

fn invalidate_tm_cache(&self)

fn resize( &self, _state: &mut LuaState, na: usize, nh: usize, ) -> Result<(), LuaError>

fn next(&self, k: LuaValue) -> Result<Option<(LuaValue, LuaValue)>, LuaError>

impl LuaUserDataRefExt for GcRef<LuaUserData>

fn metatable(&self) -> Option<GcRef<LuaTable>>

fn set_metatable(&self, mt: Option<GcRef<LuaTable>>)

fn as_ptr(&self) -> *const ()

fn len(&self) -> usize

impl<T> PartialEq for GcRef<T>

where T: PartialEq + Trace + 'static,

fn eq(&self, other: &GcRef<T>) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl<T> Trace for GcRef<T>

where T: Trace + 'static,

Forwarder for GcRef<T>. Since GcRef wraps a real lua_gc::Gc<T>, tracing must enqueue the box onto the gray queue via Marker::mark — that is what flips its header color from White to Gray and ultimately to Black during gray-queue drainage. An earlier try_visit short-circuit — left over from when GcRef was Rc-backed, with no header and no color — produced a silent bug once GcRef became a real Gc<T>: every GC-tracked allocation stayed White and was freed in the sweep on the first collectgarbage(). Cycles are now handled natively by the heap’s gray-queue (the Color::Gray check in mark makes re-visits idempotent).

fn trace(&self, m: &mut Marker)

fn type_name(&self) -> &'static str

Concrete Rust type name for diagnostic/testC telemetry (Heap::type_name_count). Collector behavior must not branch on this. The default covers container blanket impls, which are never GC-boxed directly; concrete runtime types override it with std::any::type_name::<Self>().