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.

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.

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