Struct GcRef 

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

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: Trace + 'static> GcRef<T>

pub fn new(value: T) -> Self

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: Trace + 'static> GcRef<T>

pub fn ptr_eq(a: &Self, b: &Self) -> 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: Trace + 'static> AsRef<T> for GcRef<T>

fn as_ref(&self) -> &T

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

impl<T: Trace + 'static> Clone for GcRef<T>

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T: Trace + 'static> Copy for GcRef<T>

impl<T: Debug + Trace + 'static> Debug for GcRef<T>

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

Formats the value using the given formatter.

impl<T: Trace + 'static> Deref for GcRef<T>

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &T

Dereferences the value.

impl<T: PartialEq + Trace + 'static> PartialEq for GcRef<T>

fn eq(&self, other: &Self) -> bool

Equality operator ==.

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

Inequality operator !=.

impl<T: Trace + 'static> Trace for GcRef<T>

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