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.

pub fn trace_obj(&self, m: &mut Marker)

Cycle-aware trace dispatch via Marker::try_visit’s identity short-circuit, rather than the in-header color flag that Trace for GcRef<T> (in trace_impls.rs) uses directly via m.mark(self.0). Nothing in this workspace currently calls trace_obj.

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.

Downgrading a heap-owned box with no active HeapGuard is a latent use-after-free: the resulting handle has no heap identity to check, so it keeps upgrading after sweep frees the target. That case panics unconditionally in every build; detached (process-lifetime) targets keep the legacy always-upgrades behavior.

A GcRef obtained before its heap closed (Heap::drop_all / close) is dangling afterwards, and calling this on it is use-after-free — the same contract as after Heap::drop. (Quarantine mode detects use-after-sweep while the heap is alive; teardown frees even quarantined boxes for real, so post-close dereferences are plain UB with no tripwire.) When the closed heap is the active guard, the closed-heap token refusal makes the resulting weak handle permanently dead; with no guard or a different heap active, the guard-mismatch cases above apply unchanged. A Gc box carries no owner identity of its own to validate against — fixing that is the heap-ownership redesign tracked as the #252 follow-up, not a #260 teardown property.

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).

A guard-less charge on a heap-owned box panics unconditionally in every build: the charge would be silently dropped and the pacer would drift from real memory. Detached (uncollected, process-lifetime) boxes keep the legacy no-op behavior.

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>().