lua-vm 0.7.1

//! `Trace` implementations for GC-rooted types defined in this crate. Types
//! in `lua-types` (LuaValue, LuaString, UpVal) have their Trace impls in
//! `lua-types/src/trace_impls.rs` because of Rust's orphan rule.
//!
//! Guidance for adding a new impl (Trace impls have subtle invariants, so
//! change one type at a time):
//!   1. Read the type definition; enumerate every field
//!   2. For every `Gc<T>`, `GcRef<T>`, or container (Vec/Option/HashMap)
//!      thereof, call `m.mark(field)` or `field.trace(m)` appropriately
//!   3. Skip non-GC fields (primitives, `String`, `Vec<u8>`)
//!   4. Skip "intentionally not traced" fields (weak refs)
//!   5. Reference `lgc.c`'s `reallymarkobject` for the C original's approach

use crate::state::{FinalizerObject, GlobalState, LuaState};
use lua_gc::{Marker, Trace};

impl Trace for FinalizerObject {

    fn type_name(&self) -> &'static str {
        std::any::type_name::<Self>()
    }

    fn trace(&self, m: &mut Marker) {
        match self {
            FinalizerObject::Table(t) => t.trace(m),
            FinalizerObject::UserData(u) => u.trace(m),
        }
    }
}

impl Trace for LuaState {

    fn type_name(&self) -> &'static str {
        std::any::type_name::<Self>()
    }

    fn trace(&self, m: &mut Marker) {
        // C's traversethread (lgc.c) walks [stack .. top) and relies on two
        // companion invariants this port mirrors via `gc_trace_bound` (the
        // savestate half — widen to ci.top only for a Lua current frame)
        // and `clear_dead_stack_tail` (the atomic-clear half, run before
        // every collect). Every slot below the bound is therefore
        // valid-or-nil; the old frame-bounded range walk and the saved_pc
        // debug-local heuristic (#140 bug B's two faces) are gone.
        let bound = self.gc_trace_bound();
        for slot in &self.stack[..bound] {
            slot.val.trace(m);
        }

        for uv in self.openupval.iter() {
            uv.trace(m);
        }

        // `global` (Rc<RefCell<GlobalState>>) is reached from the heap's root
        // via GlobalState::trace; tracing it from each thread would re-enter
        // the root and is explicitly excluded.
        // `call_info` entries carry pc offsets and stack indices but no direct
        // GcRef fields. The active closure is reached through the stack slot
        // at `ci.func`, already covered by the stack walk.
        // `tbclist` holds StackIdx values only; the to-be-closed objects
        // themselves live on the stack and are traced there.
    }
}

impl Trace for GlobalState {

    fn type_name(&self) -> &'static str {
        std::any::type_name::<Self>()
    }

    fn trace(&self, m: &mut Marker) {
        // per-type metatables, and pending finalizers. We expand the set to
        // include preallocated short strings (memerrmsg, tmname[]) and the
        // open-upvalue thread list, both of which the panic-driven Phase-D
        // mega-loop expects to see at the root.

        self.l_registry.trace(m);

        // Values held by Rust-side embedding handles are rooted outside the
        // Lua registry table so handle Drop can unroot without touching the
        // Lua stack/API. They are still ordinary GC roots during marking.
        for value in self.external_roots.iter_values() {
            value.trace(m);
        }

        // Cross-thread open-upvalue mirrors are live roots while a coroutine
        // resume holds the home thread's stack behind an outer mutable borrow.
        for value in self.cross_thread_upvals.values() {
            value.trace(m);
        }

        // `globals` and `loaded` are kept as direct GlobalState fields rather
        // than inside the registry table (see `init_registry`), so they must
        // be traced explicitly as roots here.
        self.globals.trace(m);
        self.loaded.trace(m);

        // Lua 5.1 per-thread and per-closure environments are GC roots: a
        // coroutine's global table and a no-`_ENV`-upvalue closure's
        // environment are reachable from the live thread / closure but stored
        // off to the side, so they must be traced here to survive collection.
        // Both maps are empty on 5.2–5.5, making these loops no-ops there.
        // Dead-thread / dead-closure keys are pruned after each collection.
        for value in self.thread_globals.values() {
            value.trace(m);
        }
        for value in self.closure_envs.values() {
            value.trace(m);
        }

        if let Some(t) = &self.mainthread {
            t.trace(m);
        }

        self.main_thread_value.trace(m);

        if self.current_thread_id != self.main_thread_id {
            if let Some(entry) = self.threads.get(&self.current_thread_id) {
                entry.value.trace(m);
            }
        }

        // Registered coroutines are not roots by registration alone. The
        // post-mark hook traces stacks only for thread handles that were
        // reached from a real root, matching Lua's collectable coroutine
        // semantics.

        for slot in self.mt.iter() {
            if let Some(t) = slot {
                t.trace(m);
            }
        }

        for s in self.tmname.iter() {
            s.trace(m);
        }

        self.memerrmsg.trace(m);

        for th in self.twups.iter() {
            th.trace(m);
        }

        // `interned_lt` is a weak short-string cache. The collector prunes
        // unmarked entries from the post-mark hook instead of tracing them as
        // roots here.
        for row in self.strcache.iter() {
            for s in row.iter() {
                s.trace(m);
            }
        }

        // Pending finalizers are NOT traced here — that's what lets the mark
        // phase distinguish "still reachable from the user program" from
        // "only kept alive by the finalizer registry". `collect_via_heap`'s
        // post-mark hook checks each entry against the visited set; an
        // unvisited entry is moved to `to_be_finalized` and explicitly
        // marked there so it survives the sweep.
        //
        // `to_be_finalized` IS traced as a strong root: objects in this list
        // are awaiting their `__gc` call but are otherwise dead, and the
        // object (plus its descendants) must survive long enough for the
        // finalizer to run.
        for object in self.finalizers.to_be_finalized().iter() {
            object.trace(m);
        }

        // Trace suspended parent stacks. When a coroutine is running, any
        // parent threads are suspended and their stacks are not reachable from
        // `threads` (which only holds coroutines, not the main thread). Before
        // `aux_resume` resumes a coroutine it pushes a snapshot of the parent's
        // live stack onto `suspended_parent_stacks` so those GC-managed values
        // remain marked during collections triggered from inside the coroutine.
        for stack_snapshot in self.suspended_parent_stacks.iter() {
            for v in stack_snapshot.iter() {
                v.trace(m);
            }
        }
        for upval_snapshot in self.suspended_parent_open_upvals.iter() {
            for uv in upval_snapshot.iter() {
                uv.trace(m);
            }
        }

        // `fixedgc` holds objects pre-marked fixed/black at allocation
        // (`luaC_fix`); the mark phase never re-visits them, and
        // `dyn Collectable` does not implement `Trace` here.
        // `allgc`, `finobj`, `gray`, `grayagain`, `tobefnz`, `weak`,
        // `ephemeron`, `allweak` are GC bookkeeping lists owned by `heap` —
        // they are the universe of allocated objects, not roots.
    }
}