rusty_racer 0.1.8 → 0.1.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: af5578c6ac8ba4eb6d367097be2faef786fdc0cb077ac5c76c14f1ec50106d41
-  data.tar.gz: 5cc05af64db35a3202c3fd72d2b0809e621ee7fa59c3db4e913ea537d835c438
+  metadata.gz: 8bae20d8fe811c8b1e9b171fe272d6481934d7fa2b1fbe978846605dd51e76d4
+  data.tar.gz: fa35ae7940c34c6c6ff54af93178b4f94200033c2a3fa4ca37f8e878bed829c3
 SHA512:
-  metadata.gz: ab88c79367db640e4144c0844a2ffcc0168f353de01ad7c225902c756d350f7a48188d9a3c0890ec6da2a61dc83e6a2484e519ccb082bb171d4fa795f89a4e7f
-  data.tar.gz: da6ca243ceb13b6d353ce15c6b59e725d617c0712e146a13017f2bbb2d7715dad0705849c4ce36b1b941b0dcb1a2a1750390d557b80c3e7a196809a66a5d4efa
+  metadata.gz: 8b98d2be3c82bf39d69dc5d3389927a1fd5872f8ace99028da3f9ffd5116464b17d8a2c05f932039f2da0a769599d22b5f870a01ac35b8ade7b8d263ae5f3c80
+  data.tar.gz: 3391fb308a736f925d56d34cfb649a262a2d9c58f8227bd28706f4da8f366aaebad779510203a57f2e7eb1507888100eb578400318addafbbbb9c4a004d69ca9

data/README.md

@@ -38,12 +38,12 @@ Embed [V8](https://v8.dev/) in Ruby, built on [rusty_v8](https://crates.io/crate
 incumbent — if you want a battle-tested binding or **Windows** support, reach for
 it. rusty_racer differs where it counts for some workloads: native **ES modules +
 dynamic import** (mini_racer is eval/classic-script oriented); **richer
-marshalling** (the types above round-trip natively instead of through a
-JSON-shaped projection); and **in-thread execution** with no per-op thread hop,
+marshalling** (`BigInt`/`Date`/`Map`/`Set` and shared/cyclic graphs cross as
+distinct Ruby types, where mini_racer does a narrower value conversion); and
+**in-thread execution** with no per-op thread hop,
 which is faster for overhead-dominated workloads (lots of tiny `eval`/`call`) and
-at parity once the per-op JS work dominates. Both axes of resource limiting are
-covered — a `timeout_ms` (time) and a `memory_limit` (space), each catchable. It
-is also younger and **experimental** — fewer miles, no Windows yet. Parity with
+at parity once the per-op JS work dominates. It is also younger and
+**experimental** — fewer miles, no Windows yet. Parity with
 mini_racer is not a goal; the overlap is convergent evolution, not a port.
 
 ## What it can do

data/ext/rusty_racer/Cargo.toml

@@ -4,7 +4,7 @@
 # libv8-rusty needed under the cibuildgem native-per-platform model).
 [package]
 name = "rusty_racer"
-version = "0.1.8"
+version = "0.1.9"
 edition = "2021"
 publish = false
 

data/ext/rusty_racer/src/lib.rs

@@ -54,7 +54,7 @@ use marshal::{js_to_jsval, jsval_to_js, jsval_to_ruby, ruby_to_jsval, JsVal};
 mod ops;
 use ops::{run_source, service_request, Compiled, Request, VmReply};
 mod stack;
-use stack::{discover_scan_start_field, set_v8_stack_limit, STACK_DEBUG};
+use stack::{current_real_isolate, discover_scan_start_field, set_v8_stack_limit, STACK_DEBUG};
 mod watchdog;
 use watchdog::{
     arm_watchdog, disarm_watchdog, run_js_bracketed, watchdog_loop, WatchdogShared, WATCHDOG_DEBUG,
@@ -242,6 +242,8 @@ fn relabel_oom(reply: VmReply) -> VmReply {
         VmReply::ModuleCompiled(r) => VmReply::ModuleCompiled(fix(r)),
         VmReply::ScriptCompiled(r) => VmReply::ScriptCompiled(fix(r)),
         VmReply::CodeCache(r) => VmReply::CodeCache(fix(r)),
+        // Carries no Result and can't OOM (no JS allocation) — pass through.
+        VmReply::Heap(s) => VmReply::Heap(s),
     }
 }
 
@@ -519,6 +521,48 @@ struct ScriptReg {
 struct V8State {
     main_context: Option<v8::Global<v8::Context>>,
     contexts: HashMap<i32, v8::Global<v8::Context>>,
+    // Each realm gets its OWN v8::MicrotaskQueue (created in new_realm, owned
+    // here, keyed like the contexts: main_queue for id 0, queues for the rest).
+    // Why per-realm rather than the isolate-wide default: reset/dispose can then
+    // DISCARD a torn-down realm's pending microtasks by simply dropping its queue
+    // — without that, a queued promise reaction (it captures its creation realm)
+    // sits in the shared queue forever and pins the old v8::Context, so a warm
+    // isolate that Context#resets per visit leaks one whole realm per reset (V8
+    // counts it as a live native context; even a full GC can't reclaim it). The
+    // queue must outlive its context: dropping the UniqueRef DESTRUCTs the queue,
+    // which removes it from V8's per-isolate ring (so V8 won't scan it) and frees
+    // its microtasks. reset/dispose don't drop it directly — they move the old
+    // (context, queue) into `retiring` so flush_retiring can repoint then free it
+    // safely (see those fields).
+    main_queue: Option<v8::UniqueRef<v8::MicrotaskQueue>>,
+    queues: HashMap<i32, v8::UniqueRef<v8::MicrotaskQueue>>,
+    // A long-lived, never-drained queue a retired realm's context is repointed to
+    // before its own queue is freed. V8 enqueues a promise reaction into the
+    // HANDLER's context's queue, and rusty's realms are mutually accessible (one
+    // shared security token + NS.contextGlobal), so a LIVE realm can still hold —
+    // and later resolve — a promise whose handler lives in a realm we tore down;
+    // if that realm's queue were already freed the enqueue would be a
+    // use-after-free. Repointing to the graveyard makes any such late enqueue land
+    // in valid memory (the microtask simply never runs). Created once per isolate,
+    // dropped only at isolate teardown.
+    //
+    // TRADEOFF: the graveyard is never drained, so a microtask landed there lives
+    // until isolate teardown — a small, bounded-per-occurrence leak on the narrow
+    // "resolve a promise into an already-disposed realm" path. Vastly smaller than
+    // the whole-realm-per-reset leak this design fixes, and empty in normal use
+    // (you don't resolve a disposed realm's promises), so it is an accepted cost of
+    // keeping that late enqueue memory-safe.
+    graveyard_queue: Option<v8::UniqueRef<v8::MicrotaskQueue>>,
+    // Realms retired by reset/dispose, awaiting teardown. We can't free a realm's
+    // queue at reset/dispose time: (1) Context::SetMicrotaskQueue (the graveyard
+    // repoint) requires NO context entered, which fails for a NESTED reset (an
+    // outer eval's context is on the stack); (2) freeing before repointing risks
+    // the cross-realm use-after-free above. So we stash (old context, old queue)
+    // here — both stay alive, so no dangling pointer and no unbounded leak — and
+    // flush_retiring drains this list at the end of the outermost request, when
+    // no context is entered: it repoints each context to the graveyard, then drops
+    // the queues (discarding their pending microtasks — the actual leak fix).
+    retiring: Vec<(v8::Global<v8::Context>, v8::UniqueRef<v8::MicrotaskQueue>)>,
     next_context_id: i32,
     host_namespace: Option<String>,
     // One security token shared by every realm of this isolate: the
@@ -695,12 +739,44 @@ fn transfer_registry() -> &'static Mutex<HashMap<u64, SendBackingStore>> {
 // transfers, which a process will never reach.
 static NEXT_TRANSFER_TOKEN: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(1);
 
+// Drain EVERY realm's microtask queue once. Each realm has its own queue (see
+// V8State::queues), so a single scope.perform_microtask_checkpoint() — which only
+// touches the isolate's default queue — would run NOTHING (every realm's promises
+// land in the realm's own queue). This restores the old isolate-wide "drain
+// everything" semantics: a microtask queued in ANY realm runs, regardless of
+// which realm the checkpoint was requested from. V8 drains each queue until empty
+// and enters each microtask's own realm, so same-realm cascades fully resolve in
+// one pass; a cross-realm cascade (a microtask in realm A enqueueing into realm B
+// that was already drained this pass) resolves on the next checkpoint — callers
+// that need full quiescence loop (csim does).
+fn drain_all_realms(scope: &mut v8::PinScope<'_, '_>) {
+    // Snapshot the queue pointers, then drain without holding the IsolateState
+    // borrow (a microtask re-enters host fns that borrow it). The queue OBJECTS
+    // are address-stable (owned via UniqueRef, heap-allocated by V8), so the
+    // snapshot survives a queues-HashMap realloc (e.g. a microtask creating a
+    // realm); and reset/dispose — the only things that free a queue — are refused
+    // while draining (checkpoint_draining set the flag), so no pointer dangles.
+    let queues: Vec<*const v8::MicrotaskQueue> = {
+        let st = istate!(scope);
+        st.realms
+            .main_queue
+            .iter()
+            .chain(st.realms.queues.values())
+            .map(|q| &**q as *const v8::MicrotaskQueue)
+            .collect()
+    };
+    for q in queues {
+        unsafe { (*q).perform_checkpoint(&mut ***scope) };
+    }
+}
+
 // Run a microtask checkpoint with DRAINING set (nesting-safe via save/restore),
-// so a nested Reset/DisposeContext issued by a drained microtask is refused.
+// so a nested Reset/DisposeContext issued by a drained microtask is refused —
+// which also keeps drain_all_realms's queue snapshot from dangling.
 fn checkpoint_draining(scope: &mut v8::PinScope<'_, '_>) {
     let prev = istate!(scope).draining;
     istate!(scope).draining = true;
-    scope.perform_microtask_checkpoint();
+    drain_all_realms(scope);
     istate!(scope).draining = prev;
 }
 
@@ -1297,7 +1373,9 @@ fn drain_microtasks(
     _args: v8::FunctionCallbackArguments<'_>,
     _rv: v8::ReturnValue<'_, v8::Value>,
 ) {
-    scope.perform_microtask_checkpoint();
+    // Drain every realm's queue (isolate-wide semantics), under the draining
+    // guard so a microtask can't reset/dispose a realm mid-drain.
+    checkpoint_draining(scope);
 }
 
 // NS.contextGlobal(id) -> the globalThis of context |id|. Cross-context
@@ -1572,10 +1650,20 @@ unsafe extern "C" fn promise_reject_cb(message: v8::PromiseRejectMessage) {
 
 // Build a fresh v8::Context and install the host namespace (from STATE) into
 // it — the single definition of "a realm of this isolate", shared by boot,
-// reset and create_context so realms can't drift apart.
-fn new_realm(scope: &mut v8::PinScope<'_, '_, ()>) -> v8::Global<v8::Context> {
+// reset and create_context so realms can't drift apart. Returns the context
+// Global AND its dedicated microtask queue; the caller owns the queue in
+// V8State alongside the context (see V8State::queues for why per-realm).
+fn new_realm(
+    scope: &mut v8::PinScope<'_, '_, ()>,
+) -> (v8::Global<v8::Context>, v8::UniqueRef<v8::MicrotaskQueue>) {
+    // Explicit policy like the isolate's: rusty drives every drain by hand
+    // (auto_drain / NS.drainMicrotasks), so V8 must never auto-run this queue.
+    let mut queue = v8::MicrotaskQueue::new(&mut **scope, v8::MicrotasksPolicy::Explicit);
     let fresh = {
-        let context = v8::Context::new(scope, Default::default());
+        let context = v8::Context::new(scope, v8::ContextOptions {
+            microtask_queue: Some(&mut *queue as *mut _),
+            ..Default::default()
+        });
         v8::Global::new(scope, context)
     };
     // DESIGN DECISION: every realm of an isolate shares ONE security token, so
@@ -1615,7 +1703,44 @@ fn new_realm(scope: &mut v8::PinScope<'_, '_, ()>) -> v8::Global<v8::Context> {
     if let Some(name) = host_namespace {
         install_host_namespace(scope, &fresh, &name);
     }
-    fresh
+    (fresh, queue)
+}
+
+// Tear down every realm parked in `retiring` (by reset/dispose): repoint each old
+// context at the graveyard queue, then free the old queues (discarding their
+// pending microtasks — the leak fix). MUST run with NO context entered, because
+// Context::SetMicrotaskQueue requires it — so the only caller is the OUTERMOST
+// service_request, after its op (and all nested ones) have unwound their
+// ContextScopes. A no-op when nothing is retired.
+fn flush_retiring(scope: &mut v8::PinScope<'_, '_, ()>) {
+    if istate!(scope).realms.retiring.is_empty() {
+        return;
+    }
+    let graveyard: *const v8::MicrotaskQueue = match istate!(scope).realms.graveyard_queue.as_ref() {
+        Some(q) => &**q as *const _,
+        // The graveyard is created at boot and never cleared, so with entries
+        // waiting this is unreachable; assert so a future refactor that defers its
+        // creation fails loudly instead of silently stranding `retiring` (which
+        // would quietly resurrect the whole-realm leak). Bail without taking the
+        // list, so nothing is lost if it somehow happens in release.
+        None => {
+            debug_assert!(false, "graveyard queue missing while realms are retiring");
+            return;
+        }
+    };
+    let retiring = std::mem::take(&mut istate!(scope).realms.retiring);
+    for (ctx, _queue) in &retiring {
+        let local = v8::Local::new(scope, ctx);
+        // SAFETY: the graveyard queue is owned by V8State for the isolate's whole
+        // life, so the pointer is valid for this set_microtask_queue call. Repoint
+        // BEFORE the queues drop below, so a cross-realm reference that keeps `ctx`
+        // alive can't be left holding a freed queue.
+        local.set_microtask_queue(unsafe { &*graveyard });
+    }
+    // Dropping `retiring` here frees each old queue (and its now-discarded pending
+    // microtasks) and each old context Global. Every context was just repointed to
+    // the graveyard, so no live context holds a freed queue pointer.
+    drop(retiring);
 }
 
 // Inject globalThis.<name> = { drainMicrotasks } into a context. Re-run on
@@ -1828,8 +1953,12 @@ impl Isolate {
         // namespace from the slot (seeded above).
         {
             v8::scope!(let scope, &mut isolate);
-            let main_context = new_realm(scope);
+            let (main_context, main_queue) = new_realm(scope);
             istate!(scope).realms.main_context = Some(main_context);
+            istate!(scope).realms.main_queue = Some(main_queue);
+            // The shared graveyard for retired realms' contexts (see V8State).
+            let graveyard = v8::MicrotaskQueue::new(&mut **scope, v8::MicrotasksPolicy::Explicit);
+            istate!(scope).realms.graveyard_queue = Some(graveyard);
         }
         // Box the OwnedIsolate so it has a STABLE address, then capture a raw ptr
         // INTO the box (a `&mut Isolate` is `&mut NonNull<RealIsolate>`, pointing
@@ -1998,22 +2127,57 @@ impl Core {
                 unsafe { (*iso).exit() };
                 reply
             } else {
-                // Re-entrant (a host callback, having reacquired the GVL to run a
-                // proc that issued this op, is on the V8 stack): the isolate is
-                // already entered by the depth-0 op on THIS native thread, so
-                // bootstrap onto the ambient HandleScope rather than re-enter.
+                // Re-entrant (a host callback or module resolver, having
+                // reacquired the GVL to run a proc that issued this op, is on the
+                // V8 stack). USUALLY the JS on the stack belongs to THIS isolate
+                // (same-isolate reentry) — which is therefore already entered on
+                // THIS native thread — so we bootstrap onto the ambient
+                // HandleScope without re-entering.
+                //
+                // But an embedder driving MANY isolates (e.g. capybara-simulated's
+                // windows) can interleave them: a host callback on isolate A runs
+                // Ruby that evals isolate B, whose own callback re-enters A. Now A
+                // is on the V8 stack (depth > 0) yet B — not A — is the isolate
+                // CURRENTLY entered on this thread, so bootstrapping a scope on A
+                // and opening a ContextScope would trip V8's "scope and Context do
+                // not belong to the same Isolate" panic (it checks the scope's
+                // isolate against Isolate::GetCurrent()). Detect that case and
+                // properly enter A on top of B, restoring B on exit. Entering an
+                // already-current isolate is also harmless (V8's entered-isolate
+                // stack nests), so this is correct for same-isolate reentry too —
+                // we only pay the enter/exit when a FOREIGN isolate is on top.
+                //
                 // The stack limit + scan-start set at depth 0 are NOT re-pointed
                 // here: reentry runs in DEEPER frames of the SAME stack, so the
-                // depth-0 values still bound it correctly. The one exception is a
+                // depth-0 values still bound it correctly (whichever isolate is
+                // current — each tracks its own limit). The one exception is a
                 // host callback that SWITCHES stacks — e.g. resumes a Ruby Fiber
                 // that itself evals — where the depth-0 (native) settings are
                 // stale for the fiber; that nested-fiber-under-callback case is an
                 // unsupported edge (the realistic fiber path is a depth-0 eval).
-                std::panic::catch_unwind(AssertUnwindSafe(|| {
-                    v8::callback_scope!(unsafe scope, unsafe { &mut *iso });
-                    service_request(scope, request, false)
+                let foreign = unsafe { *(iso as *const *mut c_void) } != current_real_isolate();
+                if foreign {
+                    unsafe { (*iso).enter() };
+                }
+                let reply = std::panic::catch_unwind(AssertUnwindSafe(|| {
+                    if foreign {
+                        // A had no ambient scope under B's entry — open a fresh
+                        // HandleScope on A, exactly as the depth-0 path does.
+                        v8::scope!(let scope, unsafe { &mut *iso });
+                        service_request(scope, request, false)
+                    } else {
+                        v8::callback_scope!(unsafe scope, unsafe { &mut *iso });
+                        service_request(scope, request, false)
+                    }
                 }))
-                .ok()
+                .ok();
+                // Pop A back off (restoring B as current). Safe even after a
+                // panic unwind: the scope's Drop ran but left A entered, and
+                // exit() asserts A == GetCurrent(), which holds here.
+                if foreign {
+                    unsafe { (*iso).exit() };
+                }
+                reply
             }
         });
         self.depth.fetch_sub(1, Ordering::SeqCst);
@@ -2114,6 +2278,35 @@ impl Core {
         Self::reply_value(ruby, reply)
     }
 
+    // Isolate#heap_statistics -> a Symbol-keyed Hash of v8::HeapStatistics
+    // (bytes; the two *_contexts entries are counts). See Request::HeapStatistics.
+    fn heap_statistics(&self, ruby: &Ruby) -> Result<Value, Error> {
+        let reply = self.run(ruby, Request::HeapStatistics)?;
+        let VmReply::Heap(s) = reply else {
+            return Err(Error::new(
+                ruby.exception_runtime_error(),
+                "internal: unexpected heap reply",
+            ));
+        };
+        let h = ruby.hash_new();
+        h.aset(ruby.to_symbol("used_heap_size"), s.used_heap_size)?;
+        h.aset(ruby.to_symbol("total_heap_size"), s.total_heap_size)?;
+        h.aset(ruby.to_symbol("heap_size_limit"), s.heap_size_limit)?;
+        h.aset(ruby.to_symbol("malloced_memory"), s.malloced_memory)?;
+        h.aset(ruby.to_symbol("peak_malloced_memory"), s.peak_malloced_memory)?;
+        h.aset(ruby.to_symbol("external_memory"), s.external_memory)?;
+        h.aset(ruby.to_symbol("number_of_native_contexts"), s.number_of_native_contexts)?;
+        h.aset(ruby.to_symbol("number_of_detached_contexts"), s.number_of_detached_contexts)?;
+        Ok(h.as_value())
+    }
+
+    // Isolate#low_memory_notification: ask V8 to run a full GC now.
+    fn low_memory_notification(&self, ruby: &Ruby) -> Result<(), Error> {
+        let reply = self.run(ruby, Request::LowMemoryNotification)?;
+        Self::reply_value(ruby, reply)?;
+        Ok(())
+    }
+
     fn eval_t(
         &self,
         ruby: &Ruby,
@@ -2524,6 +2717,17 @@ impl Isolate {
     fn perform_microtask_checkpoint(ruby: &Ruby, rb_self: &Self) -> Result<Value, Error> {
         rb_self.core.drain_microtasks(ruby)
     }
+    // Isolate#heap_statistics -> Hash. A diagnostic window into the V8 heap;
+    // watch number_of_native_contexts / number_of_detached_contexts to spot a
+    // realm leak across Context#reset.
+    fn heap_statistics(ruby: &Ruby, rb_self: &Self) -> Result<Value, Error> {
+        rb_self.core.heap_statistics(ruby)
+    }
+    // Isolate#low_memory_notification: full GC now. Reclaims dead realms between
+    // visits, and distinguishes reclaimable garbage from a genuine leak.
+    fn low_memory_notification(ruby: &Ruby, rb_self: &Self) -> Result<(), Error> {
+        rb_self.core.low_memory_notification(ruby)
+    }
     // dynamic_import_resolver = ->(specifier, referrer_url) { module } for import().
     fn set_dynamic_import_resolver(rb_self: &Self, proc: Proc) {
         rb_self.core.set_dynamic_import_resolver(proc);
@@ -2971,6 +3175,11 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
         "_set_dynamic_import_resolver",
         method!(Isolate::set_dynamic_import_resolver, 1),
     )?;
+    isolate.define_method("heap_statistics", method!(Isolate::heap_statistics, 0))?;
+    isolate.define_method(
+        "low_memory_notification",
+        method!(Isolate::low_memory_notification, 0),
+    )?;
     isolate.define_method("dispose", method!(Isolate::dispose, 0))?;
     isolate.define_method("disposed?", method!(Isolate::disposed, 0))?;
 

data/ext/rusty_racer/src/ops.rs

@@ -137,6 +137,18 @@ pub(crate) enum Request {
     ModuleCodeCache {
         module_id: i32,
     },
+    // Isolate-level memory introspection / hint (realm-independent). Read
+    // v8::HeapStatistics — used/total/limit, malloced + external bytes, and the
+    // live (number_of_native_contexts) and detached (number_of_detached_contexts)
+    // native-context counts. The two context counts are the lever for diagnosing
+    // a realm leak across Context#reset: a healthy warm isolate's live+detached
+    // count plateaus, a leak makes it climb.
+    HeapStatistics,
+    // Ask V8 to run a full GC now (Isolate::LowMemoryNotification) — lets the
+    // embedder reclaim dead realms between visits without waiting for the
+    // near-heap-limit callback, and tells reclaimable garbage apart from a real
+    // leak (memory that survives this is genuinely retained).
+    LowMemoryNotification,
 }
 
 // compile_module result: the module's id plus any produced bytecode cache and
@@ -147,6 +159,20 @@ pub(crate) struct Compiled {
     pub(crate) cache_rejected: bool,
 }
 
+// A snapshot of v8::HeapStatistics, in bytes (counts for the context fields).
+// Plain copyable numbers so it crosses out of the V8 op into a Ruby Hash without
+// any handle. See Request::HeapStatistics for what the context counts tell you.
+pub(crate) struct HeapStats {
+    pub(crate) used_heap_size: u64,
+    pub(crate) total_heap_size: u64,
+    pub(crate) heap_size_limit: u64,
+    pub(crate) malloced_memory: u64,
+    pub(crate) peak_malloced_memory: u64,
+    pub(crate) external_memory: u64,
+    pub(crate) number_of_native_contexts: u64,
+    pub(crate) number_of_detached_contexts: u64,
+}
+
 // The terminal reply of an op: service_request returns it straight up to
 // Core::run (no channel). Host callbacks and module resolvers don't round-trip
 // through here — they run inline (with_gvl).
@@ -158,6 +184,8 @@ pub(crate) enum VmReply {
     // Script#/Module#create_code_cache: the serialized bytes, or None when V8
     // can't produce a cache (or the handle's realm is gone).
     CodeCache(Result<Option<Vec<u8>>, VmError>),
+    // Isolate#heap_statistics: a snapshot of v8::HeapStatistics.
+    Heap(HeapStats),
 }
 
 pub(crate) fn run_source(scope: &mut v8::PinScope<'_, '_>, source: &str, filename: &str) -> Result<JsVal, VmError> {
@@ -315,6 +343,12 @@ pub(crate) fn service_request(scope: &mut v8::PinScope<'_, '_, ()>, request: Req
         istate!(scope).watchdog_fired = false;
         scope.cancel_terminate_execution();
     }
+    // Free realms retired by this request (or a nested reset/dispose) now that the
+    // stack has fully unwound and NO context is entered — Context::SetMicrotaskQueue
+    // (the graveyard repoint inside) requires that.
+    if outermost {
+        flush_retiring(scope);
+    }
     reply
 }
 
@@ -342,7 +376,9 @@ fn request_realm(state: &IsolateState, request: &Request) -> Option<i32> {
         | Request::DisposeModule { .. }
         | Request::DisposeScript { .. }
         | Request::ScriptCodeCache { .. }
-        | Request::ModuleCodeCache { .. } => None,
+        | Request::ModuleCodeCache { .. }
+        | Request::HeapStatistics
+        | Request::LowMemoryNotification => None,
     }
 }
 
@@ -417,9 +453,35 @@ fn dispatch_one(scope: &mut v8::PinScope<'_, '_, ()>, request: Request, outermos
         // It needs the module's context entered (unlike UnboundScript), so
         // a gone realm yields nil.
         Request::ModuleCodeCache { module_id } => op_module_code_cache(scope, module_id),
+        Request::HeapStatistics => op_heap_statistics(scope),
+        Request::LowMemoryNotification => op_low_memory_notification(scope),
     }
 }
 
+// Snapshot v8::HeapStatistics. No handles, no JS — a PinScope<()> derefs to the
+// Isolate, so the stats read straight off it.
+fn op_heap_statistics(scope: &mut v8::PinScope<'_, '_, ()>) -> VmReply {
+    let s = scope.get_heap_statistics();
+    VmReply::Heap(HeapStats {
+        used_heap_size: s.used_heap_size() as u64,
+        total_heap_size: s.total_heap_size() as u64,
+        heap_size_limit: s.heap_size_limit() as u64,
+        malloced_memory: s.malloced_memory() as u64,
+        peak_malloced_memory: s.peak_malloced_memory() as u64,
+        external_memory: s.external_memory() as u64,
+        number_of_native_contexts: s.number_of_native_contexts() as u64,
+        number_of_detached_contexts: s.number_of_detached_contexts() as u64,
+    })
+}
+
+// Hint V8 to free as much as it can right now (a full GC). Runs entered, under
+// the GVL-released op, on the owner thread — the same place the OOM recovery
+// already calls it.
+fn op_low_memory_notification(scope: &mut v8::PinScope<'_, '_, ()>) -> VmReply {
+    scope.low_memory_notification();
+    VmReply::Done(Ok(JsVal::Undefined))
+}
+
 fn op_eval(scope: &mut v8::PinScope<'_, '_, ()>, context_id: i32, source: String, filename: String, timeout_ms: u64, outermost: bool) -> VmReply {
     let outcome = run_js_bracketed(scope, outermost, timeout_ms, "eval", |scope, outermost| {
         let realm = context_for(istate!(scope), context_id);
@@ -574,13 +636,22 @@ fn op_reset(scope: &mut v8::PinScope<'_, '_, ()>, context_id: i32) -> VmReply {
                 .into(),
         )))
     } else {
-        let fresh = new_realm(scope);
+        let (fresh, fresh_queue) = new_realm(scope);
         {
             let realms = &mut istate!(scope).realms;
-            if context_id == 0 {
-                realms.main_context = Some(fresh);
+            // Swap in the fresh realm and PARK the old context + queue in
+            // `retiring` (don't drop the queue here): freeing it now could strand a
+            // freed pointer in the old context if a cross-realm reference outlives
+            // this reset, and the graveyard repoint can't run while a context is
+            // entered (nested reset). flush_retiring frees them safely at the next
+            // outermost request boundary.
+            let (old_ctx, old_queue) = if context_id == 0 {
+                (realms.main_context.replace(fresh), realms.main_queue.replace(fresh_queue))
             } else {
-                realms.contexts.insert(context_id, fresh);
+                (realms.contexts.insert(context_id, fresh), realms.queues.insert(context_id, fresh_queue))
+            };
+            if let (Some(c), Some(q)) = (old_ctx, old_queue) {
+                realms.retiring.push((c, q));
             }
         }
         // Drop modules bound to this context — their realm just changed.
@@ -596,8 +667,9 @@ fn op_create_context(scope: &mut v8::PinScope<'_, '_, ()>) -> VmReply {
         realms.next_context_id += 1;
         id
     };
-    let fresh = new_realm(scope);
+    let (fresh, fresh_queue) = new_realm(scope);
     istate!(scope).realms.contexts.insert(id, fresh);
+    istate!(scope).realms.queues.insert(id, fresh_queue);
     VmReply::Done(Ok(JsVal::Int(id as i64)))
 }
 
@@ -614,9 +686,17 @@ fn op_dispose_context(scope: &mut v8::PinScope<'_, '_, ()>, context_id: i32) ->
                 .into(),
         )))
     } else {
-        // Dropping the Global lets V8 collect the context. id 0 is the
-        // default context and never disposed independently.
-        istate!(scope).realms.contexts.remove(&context_id);
+        // Park the context + queue in `retiring` rather than dropping them here:
+        // freeing the queue could strand a freed pointer in a cross-realm-reachable
+        // context, and the graveyard repoint needs no context entered.
+        // flush_retiring frees them at the next outermost request boundary, which
+        // is what finally lets V8 collect the context. id 0 is the default context
+        // and never disposed independently.
+        let old_ctx = istate!(scope).realms.contexts.remove(&context_id);
+        let old_queue = istate!(scope).realms.queues.remove(&context_id);
+        if let (Some(c), Some(q)) = (old_ctx, old_queue) {
+            istate!(scope).realms.retiring.push((c, q));
+        }
         // Reclaim the modules compiled in it (else they leak until
         // isolate teardown).
         drop_context_artifacts(istate!(scope), context_id);

data/ext/rusty_racer/src/stack.rs

@@ -1,9 +1,13 @@
 // V8 stack limit + conservative-GC-scan retargeting (in-thread: V8 runs on the
 // calling Ruby thread's stack — a native pthread stack, or a Ruby Fiber's
-// separate mmap'd stack). Self-contained: only raw pointers, std, libc, and the
-// exported V8 symbols below — no IsolateState/JsVal/marshalling. The crate uses
-// discover_scan_start_field (once per isolate), set_v8_stack_limit (per op), and
-// STACK_DEBUG (set at init); everything else is private to this module.
+// separate mmap'd stack), plus the current-isolate query the reentry path needs.
+// Self-contained: only raw pointers, std, libc, and the exported V8 symbols below
+// — no IsolateState/JsVal/marshalling. It also hosts current_real_isolate() (the
+// entered-isolate query) since that too is just one of the exported V8 symbols
+// below, kept here so the FFI block stays in one place. The crate uses
+// discover_scan_start_field (once per isolate), set_v8_stack_limit (per op),
+// current_real_isolate (per reentrant op), and STACK_DEBUG (set at init);
+// everything else is private to this module.
 
 use std::ffi::c_void;
 // Only native_stack_bounds (linux) needs it; gated so non-linux builds (macOS)
@@ -32,6 +36,19 @@ unsafe extern "C" {
     fn v8__internal__Heap__SetStackStart(heap: *mut c_void);
     #[link_name = "_ZN2v84base5Stack13GetStackStartEv"]
     fn v8__base__Stack__GetStackStart() -> usize;
+    // rusty_v8's C binding for v8::Isolate::GetCurrent() — the thread-local
+    // "currently entered" isolate. No #[link_name]: the exported symbol is
+    // literally this name (rusty_v8's binding glue), same as the crate's own
+    // private declaration. Lets a re-entrant op tell whether ITS isolate is the
+    // one currently entered, or a foreign isolate was entered on top of it (the
+    // cross-isolate reentry case — see Core::run).
+    fn v8__Isolate__GetCurrent() -> *mut c_void;
+}
+
+// The raw v8::Isolate* currently entered on this native thread (null if none).
+// Compared by identity against an isolate's own raw pointer.
+pub(crate) fn current_real_isolate() -> *mut c_void {
+    unsafe { v8__Isolate__GetCurrent() }
 }
 
 // Locate V8's conservative-GC-scan stack_start field

data/lib/rusty_racer/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RustyRacer
-  VERSION = "0.1.8"
+  VERSION = "0.1.9"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rusty_racer
 version: !ruby/object:Gem::Version
-  version: 0.1.8
+  version: 0.1.9
 platform: ruby
 authors:
 - Keita Urashima
-autorequire:
+autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-06-15 00:00:00.000000000 Z
+date: 2026-06-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rb_sys
@@ -54,7 +54,7 @@ metadata:
   source_code_uri: https://github.com/ursm/rusty_racer
   bug_tracker_uri: https://github.com/ursm/rusty_racer/issues
   rubygems_mfa_required: 'true'
-post_install_message:
+post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -70,7 +70,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubygems_version: 3.5.22
-signing_key:
+signing_key: 
 specification_version: 4
 summary: Embed V8 in Ruby via rusty_v8 + Magnus (rb-sys)
 test_files: []