lua_types/

gc.rs

//! `GcRef<T>` — the GC-managed reference handle.
//!
//! Phase A/B/C: thin newtype around `Rc<T>`.
//! Phase D-1e (current): newtype around `lua_gc::Gc<T>` — Copy under the hood,
//! tracks allocation in the active `Heap` (via `lua_gc::with_current_heap(...)`).
//!
//! Surface kept stable across the swap: `new`, `ptr_eq`, `identity`,
//! `strong_count`, `weak_count`, `downgrade`. 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.

use lua_gc::{Gc, HeapRef, Marker, Trace};

/// 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.
#[derive(Debug)]
pub struct GcRef<T: Trace + 'static>(pub Gc<T>);

impl<T: Trace + 'static> GcRef<T> {
    /// Allocate a new GC-tracked value. If a `HeapGuard` is active (set by
    /// `state.run()` / `pcall_k`), the new allocation joins that heap's
    /// allgc chain (or its bootstrap list inside a bootstrap window).
    /// Otherwise it allocates detached — never freed for the life of the
    /// process (the issue #249 leak class). The detached arm exists only for
    /// the handful of pre-heap allocations in `new_state`; every other path
    /// must have a guard, and `OMNILUA_GC_STRICT_GUARD=1` turns this arm into
    /// a panic so guard-coverage gaps self-report under the test suites.
    pub fn new(value: T) -> Self {
        let gc = lua_gc::with_current_heap(|heap| match heap {
            Some(heap) => heap.allocate(value),
            None => {
                if lua_gc::strict_guard_mode() {
                    panic!(
                        "OMNILUA_GC_STRICT_GUARD: GcRef::new::<{}> with no active HeapGuard — \
                         this allocation would be detached and never freed (issue #249 class); \
                         push a HeapGuard or bootstrap window on the entry path",
                        std::any::type_name::<T>()
                    );
                }
                Gc::new_uncollected(value)
            }
        });
        GcRef(gc)
    }

    /// The pre-strict fallback semantics, spelled explicitly: allocate on the
    /// active heap if one is present, otherwise detached (never freed for the
    /// life of the process).
    ///
    /// DEBT(fallback): the only sanctioned caller is host-side `LuaError`
    /// message construction (`lua-types/src/error.rs`) — errors are built
    /// with no VM in scope and `LuaError::Runtime` carries a `LuaValue`, so
    /// the message must be a GC string even off-heap. Remove by carrying
    /// owned bytes in `LuaError` until VM entry. Exempt from
    /// `OMNILUA_GC_STRICT_GUARD` because the call is explicit and auditable;
    /// volume still surfaces through [`lua_gc::detached_allocations`], which
    /// the leak canaries assert stays flat.
    pub(crate) fn new_or_detached(value: T) -> Self {
        let gc = lua_gc::with_current_heap(|heap| match heap {
            Some(heap) => heap.allocate(value),
            None => Gc::new_uncollected(value),
        });
        GcRef(gc)
    }

    /// Cycle-aware trace dispatch.
    ///
    /// During D-0/D-1 (before a real Color::Gray flag is reachable from
    /// inside Trace impls), `Marker::try_visit` records the underlying
    /// allocation's identity and short-circuits a second recursion. Once
    /// D-2 ships the in-header color flag, this helper collapses to
    /// `m.mark(self.0)`.
    pub fn trace_obj(&self, m: &mut Marker) {
        if m.try_visit(self.identity()) {
            (**self).trace(m);
        }
    }
}

impl<T: Trace + 'static> GcRef<T> {
    /// Two `GcRef`s are identity-equal iff they point at the same box.
    pub fn ptr_eq(a: &Self, b: &Self) -> bool {
        Gc::ptr_eq(a.0, b.0)
    }

    /// Identity as a usize — used as a HashMap key for "same object" tests.
    pub fn identity(&self) -> usize {
        self.0.identity()
    }

    /// Number of strong references. `GcRef` is not reference-counted, so a live
    /// handle reports one owning GC reachability handle.
    pub fn strong_count(&self) -> usize {
        1
    }

    /// Number of weak references. Weak handles are not counted.
    pub fn weak_count(&self) -> usize {
        0
    }

    /// 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.
    /// `OMNILUA_GC_STRICT_GUARD=1` turns that case into a panic; detached
    /// (process-lifetime) targets keep the legacy always-upgrades behavior.
    pub fn downgrade(&self) -> GcWeak<T> {
        let identity = self.identity();
        let tracked = lua_gc::with_current_heap(|heap| {
            heap.map(|heap| {
                let token = heap.register_allocation_token(identity);
                (HeapRef::from_heap(heap), token)
            })
        });
        if tracked.is_none() && lua_gc::strict_guard_mode() && self.0.is_heap_owned() {
            panic!(
                "OMNILUA_GC_STRICT_GUARD: GcRef::downgrade::<{}> on a heap-owned box with no \
                 active HeapGuard — the weak handle would upgrade forever, including after \
                 sweep frees the target (use-after-free); push a HeapGuard on the entry path",
                std::any::type_name::<T>()
            );
        }
        let (heap, allocation_token) = match tracked {
            Some((heap, token)) => (Some(heap), token),
            None => (None, 0),
        };
        GcWeak {
            target: self.0,
            identity,
            allocation_token,
            heap,
        }
    }

    /// 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`, when no heap is
    /// active, or when the underlying box is uncollected (see
    /// [`lua_gc::Gc::account_buffer`]).
    pub fn account_buffer(&self, delta: isize) {
        if delta == 0 {
            return;
        }
        lua_gc::with_current_heap(|h| match h {
            Some(h) => self.0.account_buffer(h, delta),
            None => {
                if lua_gc::strict_guard_mode() && self.0.is_heap_owned() {
                    panic!(
                        "OMNILUA_GC_STRICT_GUARD: account_buffer({delta}) on a heap-owned \
                         {} with no active HeapGuard — the charge would be silently dropped \
                         and the pacer would drift from real memory; push a HeapGuard on \
                         the entry path",
                        std::any::type_name::<T>()
                    );
                }
            }
        })
    }
}

/// A weak handle to a `GcRef<T>`.
#[derive(Debug)]
pub struct GcWeak<T: Trace + 'static> {
    target: Gc<T>,
    identity: usize,
    allocation_token: usize,
    heap: Option<HeapRef>,
}

impl<T: Trace + 'static> GcWeak<T> {
    /// Try to promote to a strong reference.
    pub fn upgrade(&self) -> Option<GcRef<T>> {
        if let Some(heap) = self.heap {
            if !heap.contains_allocation(self.identity, self.allocation_token) {
                return None;
            }
        }
        Some(GcRef(self.target))
    }

    /// Strong reference count of the target from this weak handle's point of
    /// view: one while it can still upgrade, zero after sweep.
    pub fn strong_count(&self) -> usize {
        usize::from(self.upgrade().is_some())
    }

    pub fn identity(&self) -> usize {
        self.identity
    }
}

impl<T: Trace + 'static> Clone for GcWeak<T> {
    fn clone(&self) -> Self {
        GcWeak {
            target: self.target,
            identity: self.identity,
            allocation_token: self.allocation_token,
            heap: self.heap,
        }
    }
}

impl<T: Trace + 'static> Clone for GcRef<T> {
    fn clone(&self) -> Self {
        GcRef(self.0)
    }
}

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

impl<T: Trace + 'static> std::ops::Deref for GcRef<T> {
    type Target = T;
    fn deref(&self) -> &T {
        &*self.0
    }
}

impl<T: Trace + 'static> AsRef<T> for GcRef<T> {
    fn as_ref(&self) -> &T {
        &*self.0
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    struct NoRoots;

    impl Trace for NoRoots {
        fn trace(&self, _m: &mut Marker) {}
    }

    #[derive(Debug)]
    struct Cell0;

    impl Trace for Cell0 {
        fn trace(&self, _m: &mut Marker) {}
    }

    #[test]
    fn heap_tracked_weak_refs_stop_upgrading_after_sweep() {
        let heap = lua_gc::Heap::new();
        heap.unpause();
        let _guard = lua_gc::HeapGuard::push(&heap);

        let strong = GcRef::new(Cell0);
        let weak = strong.downgrade();
        assert!(weak.upgrade().is_some());
        assert_eq!(weak.strong_count(), 1);

        heap.full_collect(&NoRoots);
        assert!(weak.upgrade().is_none());
        assert_eq!(weak.strong_count(), 0);
    }

    /// Exercises the sanctioned guard-less path on purpose, which is exactly
    /// what `OMNILUA_GC_STRICT_GUARD=1` exists to forbid — skipped under
    /// strict mode rather than deleted so the legacy detached semantics stay
    /// covered in normal runs.
    #[test]
    fn uncollected_weak_refs_keep_process_lifetime_behavior() {
        if lua_gc::strict_guard_mode() {
            return;
        }
        let strong = GcRef::new(Cell0);
        let weak = strong.downgrade();

        assert!(weak.upgrade().is_some());
        assert_eq!(weak.strong_count(), 1);
    }
}

impl<T: PartialEq + Trace + 'static> PartialEq for GcRef<T> {
    fn eq(&self, other: &Self) -> bool {
        Gc::ptr_eq(self.0, other.0) || **self == **other
    }
}

// ──────────────────────────────────────────────────────────────────────────────
// PORT STATUS
//   source:        n/a (GcRef public wrapper around lua-gc::Gc<T>)
//   target_crate:  lua-types
//   confidence:    high
//   todos:         0
//   port_notes:    0
//   unsafe_blocks: 0
//   notes:         Thin wrapper type so consumers across crates don't depend on lua-gc's
//                  raw Gc<T>. Clone/Deref/PartialEq forwarded; no unsafe surface.
// ──────────────────────────────────────────────────────────────────────────────