rusty_racer 0.1.5 → 0.1.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 23ab2fe2f98436d0c48cc380809611878f1a7fc0b367d8b4d677a822e718efd4
-  data.tar.gz: c23f8e67fb71a192331d63030d66d138dd9b1cdd136b264107b75456f762516b
+  metadata.gz: f6e242a3632078fa63367b6e4d81ee7d720b6cfaef8355067137444b6fd48441
+  data.tar.gz: 1996ff995ae82ca4dba4de4e17c2e577d820b606bed710813e27e32d7c7a178e
 SHA512:
-  metadata.gz: 9f1144b81ef5f02bac43efe2790974f50e4cfcbbca924bea182602c2615419178f5f76376c14daee424e6c7dbbaee93152cf8969275ee61c5bf8891d1a8124b0
-  data.tar.gz: cea6a7fbf475ad7ae58cce4556ed1834d3a7aabb3bdf832fc82060b4e386e9ff0e9572dd32a4b759c51e66eedcb3478ed085e49c841958aa2fc20595ce9d55d2
+  metadata.gz: 7bca218e9cb0384d7c4e61b8bb5d1c748eb38393163b5d104803698c8f51fe6fae9b4600d4a815be5b98b70a3dbce7ea60b2219d596a652e2f3b9c8144f50a55
+  data.tar.gz: 05b6aa55215bb555000fb9b99b698ac974f74d73a4c9687d04f6fa84039d4890d92be58e7edf68a78befb98919e329e34d8c95e938cd886cf05d469219d2039a

data/README.md

@@ -154,6 +154,24 @@ 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/share between isolates** — with a host namespace, the
+  `NS` object exposes the engine primitive for implementing `postMessage`
+  transferables and `SharedArrayBuffer` sharing, both with no byte copy:
+  - **Transfer** (the transfer list): `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.
+  - **Share** (a `SharedArrayBuffer`): `NS.shareOut(sharedArrayBuffer)` returns a
+    token *without* detaching — the source stays live; `NS.shareIn(token)` rebuilds
+    a `SharedArrayBuffer` over the same memory, so both isolates see each other's
+    writes and `Atomics` work across them (including across threads).
+
+  The backing store is heap-external and atomic-refcounted, so a token stays
+  importable even after the exporting isolate is disposed. `transferOut`/`shareOut`
+  return `0` for an unsuitable argument (so the caller can fall back to a copy);
+  `transferIn`/`shareIn` return `undefined` for an unknown or wrong-kind token;
+  `NS.transferDrop(token)` releases an exported buffer that is never imported.
+  `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.5"
+version = "0.1.7"
 edition = "2021"
 publish = false
 

data/ext/rusty_racer/src/lib.rs

@@ -647,6 +647,54 @@ 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 buffer 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,
+// ships the returned integer token through its normal message plumbing, and
+// rebuilds a buffer over the SAME memory in the destination realm — replacing the
+// prior copy-out/copy-in of the bytes. Two flavours share this registry:
+//   - TRANSFER (NS.transferOut/transferIn): an ArrayBuffer; the source is detached
+//     (moved). The recipient gets an ArrayBuffer.
+//   - SHARE (NS.shareOut/shareIn): a SharedArrayBuffer; the source stays live and
+//     both realms see each other's writes (Atomics work across them). The
+//     recipient gets a SharedArrayBuffer.
+// `shared` records which, so the matching import rebuilds the right type and a
+// crossed import (transferIn of a share token, or vice versa) is refused.
+//
+// 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 struct 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 {
+    store: v8::SharedRef<v8::BackingStore>,
+    shared: bool,
+}
+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<'_, '_>) {
@@ -1317,6 +1365,155 @@ 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
+// belongs to NS.shareOut, not here.
+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, shared: false });
+    rv.set(v8::Number::new(scope, token as f64).into());
+}
+
+// NS.shareOut(sharedArrayBuffer) -> a positive integer token, or 0 for a
+// non-SharedArrayBuffer argument (so the caller falls back to a copy). Unlike
+// transferOut this does NOT detach: a SAB is *shared*, so the source realm keeps
+// its live SAB and the recipient's shareIn'd SAB sees the same memory (Atomics
+// work across them). Takes a bare SAB; for a SAB-backed view the caller passes
+// view.buffer.
+fn share_out(
+    scope: &mut v8::PinScope<'_, '_>,
+    args: v8::FunctionCallbackArguments<'_>,
+    mut rv: v8::ReturnValue<'_, v8::Value>,
+) {
+    let Ok(sab) = v8::Local::<v8::SharedArrayBuffer>::try_from(args.get(0)) else {
+        rv.set(v8::Number::new(scope, 0.0).into());
+        return;
+    };
+    let store = sab.get_backing_store();
+    let token = NEXT_TRANSFER_TOKEN.fetch_add(1, Ordering::Relaxed);
+    transfer_registry()
+        .lock()
+        .unwrap()
+        .insert(token, SendBackingStore { store, shared: true });
+    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 the *Out fns never issue, 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)
+}
+
+// Consume a token whose kind matches |want_shared| (a transfer token for
+// transferIn, a share token for shareIn). Peeks the kind under the lock and only
+// removes on a match, so a crossed import (transferIn of a share token, or vice
+// versa) leaves the entry intact and reads as undefined instead of rebuilding the
+// wrong buffer type over the memory.
+fn take_store(token: u64, want_shared: bool) -> Option<v8::SharedRef<v8::BackingStore>> {
+    let mut reg = transfer_registry().lock().unwrap();
+    match reg.get(&token) {
+        Some(e) if e.shared == want_shared => reg.remove(&token).map(|e| e.store),
+        _ => None,
+    }
+}
+
+// NS.transferIn(token) -> a fresh ArrayBuffer over the transferred backing store
+// (no byte copy), or undefined for an unknown/crossed token (already imported, the
+// message was dropped, or it was a share token). 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;
+    };
+    if let Some(store) = take_store(token, false) {
+        rv.set(v8::ArrayBuffer::with_backing_store(scope, &store).into());
+    }
+}
+
+// NS.shareIn(token) -> a fresh SharedArrayBuffer over the shared backing store
+// (same memory as the source's SAB), or undefined for an unknown/crossed token.
+fn share_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;
+    };
+    if let Some(store) = take_store(token, true) {
+        rv.set(v8::SharedArrayBuffer::with_backing_store(scope, &store).into());
+    }
+}
+
+// NS.transferDrop(token): release a parked backing store (transfer OR share)
+// 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
@@ -1433,7 +1630,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>>); 9] = [
         ("drainMicrotasks", v8::Function::new(scope, drain_microtasks)),
         ("contextGlobal", v8::Function::new(scope, context_global)),
         ("contextOf", v8::Function::new(scope, context_of)),
@@ -1441,6 +1638,11 @@ 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)),
+        ("shareOut", v8::Function::new(scope, share_out)),
+        ("shareIn", v8::Function::new(scope, share_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)) {
@@ -2284,6 +2486,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 {
@@ -2818,5 +3031,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/stack.rs

@@ -6,6 +6,9 @@
 // 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)
+// don't warn it unused.
+#[cfg(target_os = "linux")]
 use std::ptr::null_mut;
 use std::sync::atomic::{AtomicBool, Ordering};
 

data/lib/rusty_racer/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rusty_racer
 version: !ruby/object:Gem::Version
-  version: 0.1.5
+  version: 0.1.7
 platform: ruby
 authors:
 - Keita Urashima