rusty_racer 0.1.6 → 0.1.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6d14d201ab91d7e00d99d448826a92ad13c5b082b3ebe4b9d1f03778f89abf04
-  data.tar.gz: 3dc4d0bb904458984b24e12806dd756f17ae9f541f479df277e218fe8cb70478
+  metadata.gz: af5578c6ac8ba4eb6d367097be2faef786fdc0cb077ac5c76c14f1ec50106d41
+  data.tar.gz: 5cc05af64db35a3202c3fd72d2b0809e621ee7fa59c3db4e913ea537d835c438
 SHA512:
-  metadata.gz: 856d5dbbb8c3c70b1a4a574c85711c2bb89b3d343eaf4316d7714249ba5f6c04113187a728155627634a4eedcca0901cd427734e9fe9e89e9051fe0ffdaf4a6b
-  data.tar.gz: 07dd013c094a65e09e2e32ce97a2ac874b2b1dd357e440914a4fdd282612bae3afce4c41bfcc62302457573a7d8681e91117186f0d32cd0aefff27160032bdfa
+  metadata.gz: ab88c79367db640e4144c0844a2ffcc0168f353de01ad7c225902c756d350f7a48188d9a3c0890ec6da2a61dc83e6a2484e519ccb082bb171d4fa795f89a4e7f
+  data.tar.gz: da6ca243ceb13b6d353ce15c6b59e725d617c0712e146a13017f2bbb2d7715dad0705849c4ce36b1b941b0dcb1a2a1750390d557b80c3e7a196809a66a5d4efa

data/README.md

@@ -15,7 +15,10 @@ Embed [V8](https://v8.dev/) in Ruby, built on [rusty_v8](https://crates.io/crate
   not just classic scripts.
 - **Faithful value marshalling**: `BigInt`, `Date`, `Map`, `Set`, typed binary
   (`Uint8Array`/`ArrayBuffer` ↔ binary `String`), and shared/cyclic object
-  graphs all round-trip — no lossy JSON hop.
+  graphs all round-trip — no lossy JSON hop. A JS `Map` surfaces in Ruby as a
+  `RustyRacer::JSMap` (a `Hash` subclass — it reads like a `Hash` but keeps its
+  non-string keys) and marshals back to a JS `Map`; a plain `Hash` still maps to a
+  JS object.
 - **In-thread execution** — V8 runs on the calling Ruby thread, with no dedicated
   V8 thread and no per-op thread hop; fast when you run many small ops.
 - **Drop-in [ExecJS](#execjs) runtime** — any ExecJS consumer switches with no
@@ -58,7 +61,7 @@ ctx.eval("1 + 1")                        # => 2
 ctx.eval("({a: 1, b: [true, 'x']})")     # => {"a"=>1, "b"=>[true, "x"]}
 
 # Call a JS function with marshalled args (BigInt/Date/Map/Set/shared refs
-# all round-trip faithfully).
+# all round-trip faithfully; a JS Map surfaces as a RustyRacer::JSMap).
 ctx.eval("function add(a, b) { return a + b }")
 ctx.call("add", 20, 22)                  # => 42
 ctx.call_void("doSideEffect")            # runs it; never marshals the return
@@ -154,19 +157,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 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.
+- **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.6"
+version = "0.1.8"
 edition = "2021"
 publish = false
 

data/ext/rusty_racer/src/lib.rs

@@ -649,23 +649,33 @@ static LEAKED_ISOLATES: std::sync::atomic::AtomicUsize = std::sync::atomic::Atom
 
 // ── 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,
+// 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 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.
+// 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 newtype with a
+// 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(v8::SharedRef<v8::BackingStore>);
+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
@@ -1363,10 +1373,9 @@ fn set_promise_reject_handler(
 // 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.
+// (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<'_>,
@@ -1404,12 +1413,36 @@ fn transfer_out(
     transfer_registry()
         .lock()
         .unwrap()
-        .insert(token, SendBackingStore(store));
+        .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 transferOut never issues, and tokens are f64-exact
+// "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
@@ -1422,10 +1455,23 @@ fn transfer_token(scope: &mut v8::PinScope<'_, '_>, value: v8::Local<v8::Value>)
         .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 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.
+// (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<'_>,
@@ -1434,16 +1480,30 @@ fn transfer_in(
     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 {
+    if let Some(store) = take_store(token, false) {
         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.
+// 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<'_>,
@@ -1570,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>>); 7] = [
+    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)),
@@ -1580,6 +1640,8 @@ fn install_host_namespace(
         ),
         ("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 {
@@ -2957,6 +3019,13 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
     jsmodule.define_method("dispose", method!(JsModule::dispose, 0))?;
     jsmodule.define_method("disposed?", method!(JsModule::disposed, 0))?;
 
+    // A JS Map marshals to this Hash subclass (not a plain Hash) so the reverse
+    // direction can tell it apart from a JS Object — also a Hash — and rebuild a
+    // JS Map instead of a plain object. It behaves exactly like a Hash (so
+    // `assert_kind_of Hash` / `h[k]` still work); users may also construct one to
+    // hand a JS Map to JS. See marshal.rs.
+    module.define_class("JSMap", ruby.class_object().const_get::<_, magnus::RClass>("Hash")?)?;
+
     let platform = module.define_module("Platform")?;
     platform.define_singleton_method("set_flags!", function!(platform_set_flags, -1))?;
 

data/ext/rusty_racer/src/marshal.rs

@@ -48,8 +48,11 @@ pub(crate) enum JsVal {
     Array { id: u32, items: Vec<JsVal> },
     // JS object / Ruby Hash with string keys. Insertion order preserved.
     Obj { id: u32, entries: Vec<(String, JsVal)> },
-    // JS Map <-> Ruby Hash. Keys are arbitrary values (not just strings), so
-    // this is distinct from Obj. Insertion order preserved.
+    // JS Map <-> Ruby RustyRacer::JSMap (a Hash subclass). Keys are arbitrary
+    // values (not just strings), so this is distinct from Obj. Insertion order
+    // preserved. The JSMap subclass is what lets a Map round-trip: a plain Ruby
+    // Hash marshals to Obj (a JS Object), a JSMap to Map — the return leg tells
+    // them apart by class (Ruby has no native Map type).
     Map { id: u32, pairs: Vec<(JsVal, JsVal)> },
     // JS Set <-> Ruby Set (stdlib).
     Set { id: u32, items: Vec<JsVal> },
@@ -431,6 +434,15 @@ pub(crate) fn jsval_to_ruby(ruby: &Ruby, val: &JsVal) -> Result<Value, Error> {
 // reference. This invariant is load-bearing: do NOT refactor an arm to stash a
 // value in `built` without keeping it rooted by a live local until it's grafted.
 
+// The RustyRacer::JSMap class (a Hash subclass), defined in init. A JS Map
+// marshals to an instance of it so the reverse direction can distinguish it from
+// a plain Hash (a JS Object) and rebuild a JS Map. Errors only if init didn't run.
+fn js_map_class(ruby: &Ruby) -> Result<magnus::RClass, Error> {
+    ruby.class_object()
+        .const_get::<_, magnus::RModule>("RustyRacer")?
+        .const_get::<_, magnus::RClass>("JSMap")
+}
+
 fn jsval_to_ruby_d(
     ruby: &Ruby,
     val: &JsVal,
@@ -494,16 +506,27 @@ fn jsval_to_ruby_d(
             }
             h.as_value()
         }
-        // JS Map -> Ruby Hash (arbitrary marshalled keys, not just strings).
+        // JS Map -> RustyRacer::JSMap, a Hash subclass: arbitrary marshalled keys
+        // (not just strings) AND distinguishable from a JS Object (a plain Hash),
+        // so ruby_to_jsval can rebuild a JS Map rather than a plain object. Build
+        // empty then aset so a cyclic Map (a value referring back to the Map)
+        // resolves through the Ref table.
+        //
+        // LIMITATION: keys collapse by Ruby Hash equality (eql?/hash), but a JS
+        // Map keys by identity (SameValueZero). Primitive keys (string/number/
+        // bool/bigint) round-trip exactly; two distinct-but-structurally-equal
+        // OBJECT keys (e.g. `{}` and `{}`) become ONE entry — inherent to a Hash
+        // representation, and object identity can't survive copy-marshalling anyway.
         JsVal::Map { id, pairs } => {
-            let h = ruby.hash_new();
-            built.insert(*id, h.as_value());
+            let map_obj: Value = js_map_class(ruby)?.funcall("new", ())?;
+            built.insert(*id, map_obj);
+            let h = RHash::from_value(map_obj).expect("JSMap is a Hash");
             for (k, v) in pairs {
                 let kk = jsval_to_ruby_d(ruby, k, built)?;
                 let vv = jsval_to_ruby_d(ruby, v, built)?;
                 let _ = h.aset(kk, vv);
             }
-            h.as_value()
+            map_obj
         }
         // JS Set -> Ruby Set (stdlib); build empty then add so a cyclic Set
         // (a Set containing itself) resolves through the Ref table.
@@ -726,6 +749,31 @@ fn ruby_to_jsval_d(val: Value, seen: &mut RbSeen, depth: u32) -> Result<JsVal, E
         }
         return Ok(JsVal::Array { id, items });
     }
+    // RustyRacer::JSMap (a Hash subclass) -> JS Map, preserving arbitrary keys as
+    // real JS values (NOT string-coerced like a plain Hash -> JS Object). Must come
+    // BEFORE the Hash branch, since a JSMap IS-A Hash. This is what makes a JS Map
+    // round-trip (JS Map -> JSMap -> JS Map) instead of degrading to an object.
+    if let Ok(js_map) = js_map_class(&ruby) {
+        if val.is_kind_of(js_map) {
+            let id = match rb_container_id(seen, val, depth)? {
+                RbId::New(id) => id,
+                RbId::Reuse(jv) => return Ok(jv),
+            };
+            let hash = RHash::from_value(val).expect("JSMap is a Hash");
+            let pairs = RefCell::new(Vec::new());
+            hash.foreach(|k: Value, v: Value| {
+                pairs.borrow_mut().push((
+                    ruby_to_jsval_d(k, seen, depth + 1)?,
+                    ruby_to_jsval_d(v, seen, depth + 1)?,
+                ));
+                Ok(magnus::r_hash::ForEach::Continue)
+            })?;
+            return Ok(JsVal::Map {
+                id,
+                pairs: pairs.into_inner(),
+            });
+        }
+    }
     if let Ok(hash) = RHash::try_convert(val) {
         let id = match rb_container_id(seen, val, depth)? {
             RbId::New(id) => id,

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.6"
+  VERSION = "0.1.8"
 end

metadata

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