rusty_racer 0.1.4 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 329c875cb612dccca54a8c70302d26ad0a38b8a1821733aa6eac9c4795e77d8b
-  data.tar.gz: 4d2665db69e108f6ef37fa9d4f0ae4bc3224ab1756e911abec76cfad558f8bd4
+  metadata.gz: 6d14d201ab91d7e00d99d448826a92ad13c5b082b3ebe4b9d1f03778f89abf04
+  data.tar.gz: 3dc4d0bb904458984b24e12806dd756f17ae9f541f479df277e218fe8cb70478
 SHA512:
-  metadata.gz: f95ae2f448af2ade88af369bea7c0b41c500e4028aeed04e34574e148c7d5f460ac068804bc49b409ab55ad352d063fcb0269064b27b1cf3a2a0453a8e245e2f
-  data.tar.gz: 4b853defb2dbde4c0455b9eefb5b6ba9d40002e94953f5d1540c4035087e8128c6b6df843463429b0e5cbcb404a0d1a1c625d13a24fee301a300eaf50dc9ad84
+  metadata.gz: 856d5dbbb8c3c70b1a4a574c85711c2bb89b3d343eaf4316d7714249ba5f6c04113187a728155627634a4eedcca0901cd427734e9fe9e89e9051fe0ffdaf4a6b
+  data.tar.gz: 07dd013c094a65e09e2e32ce97a2ac874b2b1dd357e440914a4fdd282612bae3afce4c41bfcc62302457573a7d8681e91117186f0d32cd0aefff27160032bdfa

data/README.md

@@ -154,6 +154,19 @@ Also available:
   isolate's heap. All realms are mutually same-origin (with a host namespace,
   `NS.contextGlobal(id)` reaches another realm's `globalThis`, like a same-origin
   `iframe.contentWindow`), so this is **not** an isolation boundary.
+- **Zero-copy buffer transfer between isolates** — with a host namespace,
+  `NS.transferOut(arrayBufferOrView)` detaches a buffer (its `byteLength` → 0) and
+  returns an integer token; `NS.transferIn(token)` rebuilds an `ArrayBuffer` over
+  the **same** memory in another isolate with no byte copy (the backing store is
+  heap-external and atomic-refcounted, so the token stays importable even after the
+  exporting isolate is disposed). `NS.transferOut` returns `0` for a non-buffer or
+  non-detachable argument — including a `SharedArrayBuffer`, which is *shared*, not
+  transferred — so the caller can fall back to a copy; `NS.transferIn` returns
+  `undefined` for an unknown token; `NS.transferDrop(token)` releases an exported
+  buffer that is never imported. This is the engine primitive for
+  implementing `postMessage` transferables; `RustyRacer.pending_transfer_count`
+  reports exported-but-not-yet-imported buffers so dropped messages don't leak
+  silently.
 - **`Isolate#perform_microtask_checkpoint`** — manual microtask drain. The default
   `microtasks: :auto` also drains at the end of each outermost eval/call/evaluate;
   `microtasks: :explicit` leaves it fully manual. There is no event loop or timers

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.4"
+version = "0.1.6"
 edition = "2021"
 publish = false
 

data/ext/rusty_racer/src/lib.rs

@@ -534,11 +534,6 @@ struct V8State {
     promise_reject_handler: Option<(i32, v8::Global<v8::Function>)>,
 }
 
-// Context embedder-data slot holding the realm id (an Integer), stamped by
-// new_realm so id_of_context is O(1). Slot 0 is the embedder's own first slot
-// (the binding adds INTERNAL_SLOT_COUNT); nothing else here uses embedder data.
-const REALM_ID_SLOT: i32 = 0;
-
 // (STATE/MODULES/SCRIPTS/ACTIVE_REALMS/INSTANTIATING/WATCHDOG_FIRED/
 // AUTO_MICROTASKS/DRAINING moved into IsolateState in the isolate slot, reached
 // via istate!(scope). Their invariants are documented on IsolateState's fields.)
@@ -652,6 +647,44 @@ static NEXT_ISOLATE_ID: std::sync::atomic::AtomicU32 = std::sync::atomic::Atomic
 // dispose isolates explicitly on their owner thread before that thread exits.
 static LEAKED_ISOLATES: std::sync::atomic::AtomicUsize = std::sync::atomic::AtomicUsize::new(0);
 
+// ── zero-copy ArrayBuffer transfer registry ────────────────────────────────
+//
+// A SharedRef<BackingStore> parked here so a large ArrayBuffer can cross from one
+// isolate to another with NO byte copy. A backing store is V8's own heap-external,
+// atomic-refcounted allocation, designed to be co-owned by live ArrayBuffers "even
+// across isolates" (rusty_v8 ArrayBuffer docs). The embedder (capybara-simulated's
+// cross-isolate postMessage transport) exports a buffer from the source realm via
+// NS.transferOut, ships the returned integer token through its normal message
+// plumbing, and rebuilds an ArrayBuffer over the SAME memory in the destination
+// realm via NS.transferIn — replacing the prior copy-out/copy-in of the bytes.
+//
+// SharedRef<BackingStore> is NOT auto-Send (BackingStore is Send but not Sync, so
+// SharedPtrBase's `T: Sync` Send-bound is unmet). It rides in this newtype with a
+// manual Send for the same reason as SendIso/IsoPtr: the registry only ever MOVES
+// the handle between owner threads (insert on the exporter's thread, remove on the
+// importer's) under the Mutex, never sharing &handle concurrently — and shared_ptr's
+// refcount is atomic, so dropping it on either thread is sound. No Sync impl: the
+// handle is never aliased across threads.
+struct SendBackingStore(v8::SharedRef<v8::BackingStore>);
+unsafe impl Send for SendBackingStore {}
+
+// Exported-but-not-yet-imported backing stores, keyed by token. A GLOBAL (not
+// per-isolate): the whole point is to bridge two isolates, and tokens are unique
+// process-wide. An exported buffer that is never imported (a dropped message)
+// pins its memory here until NS.transferDrop releases it — RustyRacer
+// .pending_transfer_count makes that observable.
+static TRANSFER_REGISTRY: std::sync::OnceLock<Mutex<HashMap<u64, SendBackingStore>>> =
+    std::sync::OnceLock::new();
+
+fn transfer_registry() -> &'static Mutex<HashMap<u64, SendBackingStore>> {
+    TRANSFER_REGISTRY.get_or_init(|| Mutex::new(HashMap::new()))
+}
+
+// Monotonic token source. Starts at 1 so 0 is free as the JS-side "not
+// transferable — fall back to a copy" sentinel. A token is f64-exact for ~2^53
+// transfers, which a process will never reach.
+static NEXT_TRANSFER_TOKEN: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(1);
+
 // Run a microtask checkpoint with DRAINING set (nesting-safe via save/restore),
 // so a nested Reset/DisposeContext issued by a drained microtask is refused.
 fn checkpoint_draining(scope: &mut v8::PinScope<'_, '_>) {
@@ -1015,17 +1048,35 @@ fn finish_dynamic_import(
     }
 }
 
-// The id of |context|, read O(1) from the realm-id stamped in by new_realm.
-// None when the context is not a LIVE realm of this isolate — a context reset
-// away still carries its old stamp, so confirm the id currently maps back to
-// this very context before trusting it.
+// The id of |context| among this isolate's LIVE realms, or None when it isn't
+// one (e.g. a context that was reset or disposed away). Scans the realm table:
+// realm counts are small (a handful of frames) and this only runs off the hot
+// path (promise rejection, dynamic import, contextOf), so the scan is cheap.
+//
+// We deliberately do NOT stamp the id into the context's embedder data. Using a
+// context slot makes V8 attach a ContextAnnex carrying a guaranteed-finalizer
+// weak handle to every realm, and that finalizer has crashed the process at
+// isolate teardown (a first-pass weak callback re-fired during disposal,
+// panicking on an already-taken handle). Keeping realms free of context slots
+// keeps teardown clear of that hazard.
 fn id_of_context(scope: &mut v8::PinScope<'_, '_>, context: v8::Local<v8::Context>) -> Option<i32> {
-    let id = context
-        .get_embedder_data(scope, REALM_ID_SLOT)
-        .and_then(|v| v.int32_value(scope))?;
-    let current = context_for(istate!(scope), id);
-    let live = current.is_some_and(|g| v8::Local::new(scope, &g) == context);
-    live.then_some(id)
+    // The main realm (id 0) is overwhelmingly the common case — check it first,
+    // without cloning the whole table.
+    let main = istate!(scope).realms.main_context.clone();
+    if main.is_some_and(|g| v8::Local::new(scope, &g) == context) {
+        return Some(0);
+    }
+    // Extra realms: snapshot the (cloned) Globals so no IsolateState borrow is
+    // held while we mint Locals from `scope`.
+    let extras: Vec<(i32, v8::Global<v8::Context>)> = istate!(scope)
+        .realms
+        .contexts
+        .iter()
+        .map(|(id, g)| (*id, g.clone()))
+        .collect();
+    extras
+        .into_iter()
+        .find_map(|(id, g)| (v8::Local::new(scope, &g) == context).then_some(id))
 }
 
 // Pick the Global context for a realm id: 0 = main, N = an extra realm (None
@@ -1304,6 +1355,105 @@ fn set_promise_reject_handler(
     }
 }
 
+// NS.transferOut(arrayBufferOrView) -> a positive integer token, or 0 when the
+// argument can't be zero-copy transferred so the caller falls back to a copy.
+// Grabs the buffer's backing store, DETACHES the source (transfer semantics: its
+// byteLength -> 0, like a structured-clone transfer list), and parks the store
+// under the returned token. The bytes are untouched — only the source realm
+// loses access. A view transfers its whole underlying ArrayBuffer.
+//
+// Returns 0 (copy fallback) for: a non-buffer argument; a non-detachable buffer
+// (WebAssembly/asm.js memory); and a SharedArrayBuffer or SAB-backed view — a
+// SAB is *shared*, not transferred (detaching it would be a category error), so
+// it has no place in this transfer primitive; sharing it zero-copy across
+// isolates would be a separate feature.
+fn transfer_out(
+    scope: &mut v8::PinScope<'_, '_>,
+    args: v8::FunctionCallbackArguments<'_>,
+    mut rv: v8::ReturnValue<'_, v8::Value>,
+) {
+    let value = args.get(0);
+    let ab = if value.is_array_buffer() {
+        v8::Local::<v8::ArrayBuffer>::try_from(value).ok()
+    } else if value.is_array_buffer_view() {
+        v8::Local::<v8::ArrayBufferView>::try_from(value)
+            .ok()
+            .and_then(|view| view.buffer(scope))
+    } else {
+        None
+    };
+    // Only transfer what we can neuter: zero-copy sharing a buffer the source
+    // realm keeps live would alias mutable memory across isolates. Caller copies.
+    let Some(ab) = ab.filter(|ab| ab.is_detachable()) else {
+        rv.set(v8::Number::new(scope, 0.0).into());
+        return;
+    };
+    // Grab the store BEFORE detaching — detach severs the buffer from it; the
+    // SharedRef then keeps the memory alive on its own via the atomic refcount.
+    let store = ab.get_backing_store();
+    // is_detachable() does NOT guarantee detach succeeds: a buffer carrying an
+    // [[ArrayBufferDetachKey]] returns None here and stays live. Register only
+    // once the source is genuinely neutered, else both realms would alias one
+    // backing store. (rusty_racer sets no detach keys today, so this is belt-and-
+    // braces against the safety invariant ever silently breaking.)
+    if ab.detach(None) != Some(true) {
+        rv.set(v8::Number::new(scope, 0.0).into());
+        return;
+    }
+    let token = NEXT_TRANSFER_TOKEN.fetch_add(1, Ordering::Relaxed);
+    transfer_registry()
+        .lock()
+        .unwrap()
+        .insert(token, SendBackingStore(store));
+    rv.set(v8::Number::new(scope, token as f64).into());
+}
+
+// Parse a transfer-token argument: a finite, integral JS number >= 1 (0 is the
+// "not transferable" sentinel transferOut never issues, and tokens are f64-exact
+// only up to 2^53). Rejects NaN / Infinity / fractional / negative / out-of-range
+// values — which a bare `as u64` would truncate or saturate into a COLLISION with
+// a live token, stealing an unrelated transfer — so a malformed token instead
+// reads as "unknown" (transferIn -> undefined, transferDrop -> no-op). Must run
+// before locking the registry: number_value can invoke a user valueOf/
+// Symbol.toPrimitive, i.e. re-enter these callbacks.
+fn transfer_token(scope: &mut v8::PinScope<'_, '_>, value: v8::Local<v8::Value>) -> Option<u64> {
+    let n = value.number_value(scope)?;
+    (n.is_finite() && n.fract() == 0.0 && (1.0..=9_007_199_254_740_992.0).contains(&n))
+        .then_some(n as u64)
+}
+
+// NS.transferIn(token) -> a fresh ArrayBuffer over the transferred backing store
+// (no byte copy), or undefined for an unknown token (already imported, or the
+// message was dropped). Consumes the token: the new buffer co-owns the store, so
+// the registry's reference is released.
+fn transfer_in(
+    scope: &mut v8::PinScope<'_, '_>,
+    args: v8::FunctionCallbackArguments<'_>,
+    mut rv: v8::ReturnValue<'_, v8::Value>,
+) {
+    let Some(token) = transfer_token(scope, args.get(0)) else {
+        return;
+    };
+    let entry = transfer_registry().lock().unwrap().remove(&token);
+    if let Some(SendBackingStore(store)) = entry {
+        rv.set(v8::ArrayBuffer::with_backing_store(scope, &store).into());
+    }
+}
+
+// NS.transferDrop(token): release a transferred backing store WITHOUT importing
+// it — for when the embedder discards a message whose buffer was exported.
+// A no-op for an unknown token. Without this, an exported-but-never-imported
+// buffer would pin its memory until process exit.
+fn transfer_drop(
+    scope: &mut v8::PinScope<'_, '_>,
+    args: v8::FunctionCallbackArguments<'_>,
+    _rv: v8::ReturnValue<'_, v8::Value>,
+) {
+    if let Some(token) = transfer_token(scope, args.get(0)) {
+        transfer_registry().lock().unwrap().remove(&token);
+    }
+}
+
 // V8 calls this synchronously on promise rejections with no handler (and the
 // later revocations when a handler IS added). Forwards
 // (event, contextId, promise, reason) to the registered JS recorder — the
@@ -1363,18 +1513,11 @@ 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<'_, '_, ()>, id: i32) -> v8::Global<v8::Context> {
+fn new_realm(scope: &mut v8::PinScope<'_, '_, ()>) -> v8::Global<v8::Context> {
     let fresh = {
         let context = v8::Context::new(scope, Default::default());
         v8::Global::new(scope, context)
     };
-    // Stamp the realm id into the context so id_of_context is O(1) (it would
-    // otherwise scan every realm on every promise rejection / contextOf call).
-    {
-        let context = v8::Local::new(scope, &fresh);
-        let id_val: v8::Local<v8::Value> = v8::Integer::new(scope, id).into();
-        context.set_embedder_data(REALM_ID_SLOT, id_val);
-    }
     // DESIGN DECISION: every realm of an isolate shares ONE security token, so
     // they are all mutually same-origin — the model is "a group of same-origin
     // frames sharing one heap", and NS.contextGlobal gives full cross-realm
@@ -1427,7 +1570,7 @@ fn install_host_namespace(
     let context = v8::Local::new(scope, ctx);
     let scope = &mut v8::ContextScope::new(scope, context);
     let ns = v8::Object::new(scope);
-    let members: [(&str, Option<v8::Local<v8::Function>>); 4] = [
+    let members: [(&str, Option<v8::Local<v8::Function>>); 7] = [
         ("drainMicrotasks", v8::Function::new(scope, drain_microtasks)),
         ("contextGlobal", v8::Function::new(scope, context_global)),
         ("contextOf", v8::Function::new(scope, context_of)),
@@ -1435,6 +1578,9 @@ fn install_host_namespace(
             "setPromiseRejectHandler",
             v8::Function::new(scope, set_promise_reject_handler),
         ),
+        ("transferOut", v8::Function::new(scope, transfer_out)),
+        ("transferIn", v8::Function::new(scope, transfer_in)),
+        ("transferDrop", v8::Function::new(scope, transfer_drop)),
     ];
     for (member, function) in members {
         if let (Some(f), Some(k)) = (function, v8::String::new(scope, member)) {
@@ -1620,7 +1766,7 @@ impl Isolate {
         // namespace from the slot (seeded above).
         {
             v8::scope!(let scope, &mut isolate);
-            let main_context = new_realm(scope, 0);
+            let main_context = new_realm(scope);
             istate!(scope).realms.main_context = Some(main_context);
         }
         // Box the OwnedIsolate so it has a STABLE address, then capture a raw ptr
@@ -2278,6 +2424,17 @@ fn leaked_isolate_count() -> usize {
     LEAKED_ISOLATES.load(Ordering::Relaxed)
 }
 
+// RustyRacer.pending_transfer_count -> Integer: backing stores exported via
+// NS.transferOut but not yet imported (NS.transferIn) or released
+// (NS.transferDrop). PROCESS-WIDE (the registry bridges isolates, so the count
+// aggregates every isolate's outstanding transfers — compare deltas, not the
+// absolute value, when isolates run concurrently). A transport that always pairs
+// an export with one of those keeps its own contribution at 0; a rising count
+// means dropped messages are leaking transferred memory.
+fn pending_transfer_count() -> usize {
+    transfer_registry().lock().unwrap().len()
+}
+
 // Thin magnus-method wrappers.
 // Isolate = the VM and its isolate-level operations; it hands out Contexts.
 impl Isolate {
@@ -2812,5 +2969,6 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
     // Observability for the thread-confined lifecycle (see Drop for Core).
     module.define_singleton_method("live_isolate_count", function!(live_isolate_count, 0))?;
     module.define_singleton_method("leaked_isolate_count", function!(leaked_isolate_count, 0))?;
+    module.define_singleton_method("pending_transfer_count", function!(pending_transfer_count, 0))?;
     Ok(())
 }

data/ext/rusty_racer/src/ops.rs

@@ -574,7 +574,7 @@ fn op_reset(scope: &mut v8::PinScope<'_, '_, ()>, context_id: i32) -> VmReply {
                 .into(),
         )))
     } else {
-        let fresh = new_realm(scope, context_id);
+        let fresh = new_realm(scope);
         {
             let realms = &mut istate!(scope).realms;
             if context_id == 0 {
@@ -596,7 +596,7 @@ fn op_create_context(scope: &mut v8::PinScope<'_, '_, ()>) -> VmReply {
         realms.next_context_id += 1;
         id
     };
-    let fresh = new_realm(scope, id);
+    let fresh = new_realm(scope);
     istate!(scope).realms.contexts.insert(id, fresh);
     VmReply::Done(Ok(JsVal::Int(id as i64)))
 }

data/lib/rusty_racer/version.rb

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

metadata

@@ -1,11 +1,11 @@
 --- !ruby/object:Gem::Specification
 name: rusty_racer
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.1.6
 platform: ruby
 authors:
 - Keita Urashima
-autorequire:
+autorequire: 
 bindir: bin
 cert_chain: []
 date: 2026-06-14 00:00:00.000000000 Z
@@ -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: []