mini_racer_rs 1.0.3 → 1.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dfd3987a3aebfd95013e67e552b2041b991fd7b0da4933f98ae92335f7caa3a4
-  data.tar.gz: 51ccdf38b39ab3f33f771f3cf7fdbd7422bda16037e8bc026cfd64dc6fdfbdae
+  metadata.gz: c1f337ddf902559ced22f49783b4f541c2ead54c00d1a72ee7a354e1e0b831fc
+  data.tar.gz: 45fe66cb3b1fd6af17aa4da11fa689d387a586eaab1ffd3fe0349fddc90bbec8
 SHA512:
-  metadata.gz: ca5321d48ea8913f86d8966b6f475857d11b962c1f109e15f049fed590a517233f2cc3772fad99a9ff189f110995d3b2a0268f54e9f90aa48fcdd3cc1ac2b916
-  data.tar.gz: 3c2a6c804148cfd0bdf198d5a63ef4b440d63c667d7468ab646e8b85b277eb15ec0fa26f5d9877f426c01427e8f841723cf31d00bec0ee546881c895d373c61b
+  metadata.gz: 924bb67c0d847c12570f983e86594d3ea432f76f206f73d725c3908b272634b5252699652a46231655e714ece2822942c474832b9618681d3bea3c120f7138b4
+  data.tar.gz: 8ead9bef3dac6010fe255d66e009583a7d1e2e8dc2c07aa655dbf21a3f9cda6b0416a74d676a28ff18e916a60f6c644d54e8265d3abe65c0927f5dc6870bcf89

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [1.0.5](https://github.com/andymai/mini_racer_rs/compare/v1.0.4...v1.0.5) (2026-10-19)
+
+
+### Performance
+
+* **encode:** send Ruby strings to V8 in the form V8 stores them ([#93](https://github.com/andymai/mini_racer_rs/issues/93)) ([62f9c85](https://github.com/andymai/mini_racer_rs/commit/62f9c851917cb0ce7d760b5fc545aa014df0a53b))
+
+## [1.0.4](https://github.com/andymai/mini_racer_rs/compare/v1.0.3...v1.0.4) (2026-10-19)
+
+
+### Performance
+
+* **engine:** share a large source from its first evaluation ([#91](https://github.com/andymai/mini_racer_rs/issues/91)) ([31425e1](https://github.com/andymai/mini_racer_rs/commit/31425e1fc72083fd1c6564d5f50d30b8e2d746aa))
+
 ## [1.0.3](https://github.com/andymai/mini_racer_rs/compare/v1.0.2...v1.0.3) (2026-10-18)
 
 

data/COMPATIBILITY.md

@@ -182,7 +182,7 @@ Approved 2026-10-16.
 
 ### `behavior:shared-source-heap-stats@ruby`
 
-`Context#heap_stats` can report large source text differently from mini_racer 0.22.1. When a context evaluates a source of 1 MiB or more that the process has evaluated before under the same file name and startup snapshot, mini_racer_rs gives V8 one copy shared by every such context and held outside V8's heap. It reports that source in `:external_memory` and omits it from `:used_heap_size`. V8 counts the shared source by its length in characters, so two-byte text reports half its bytes. mini_racer 0.22.1 reports `:external_memory` as 0 and counts each context's own copy in `:used_heap_size`. JavaScript sees the same source text in both gems. Contexts using `max_memory:` and sources that are not valid UTF-8 retain individual copies. Setting `MINI_RACER_RS_CODE_CACHE=off` before creating the first context disables sharing and makes `heap_stats` count every source as mini_racer does.
+`Context#heap_stats` reports shared sources differently from mini_racer 0.22.1: when a context evaluates a source of 1 MiB or more, mini_racer_rs includes it in `:external_memory` and excludes it from `:used_heap_size`. mini_racer_rs gives V8 one copy held outside V8's heap, shared starting with the first evaluation by every context using the same source, file name, and startup snapshot. The process shares at most 8 such sources and 256 MiB of them. Past that bound, a context evaluating another large source keeps its own copy, and its `heap_stats` count that source as mini_racer's do. V8 counts shared sources in `:external_memory` by character length, so two-byte text reports half its bytes. mini_racer 0.22.1 reports `:external_memory` as 0 and counts each context's own copy in `:used_heap_size`. JavaScript sees the same source text in both gems. Contexts created with `max_memory:` and sources that are not valid UTF-8 keep their own copies. Setting `MINI_RACER_RS_CODE_CACHE=off` before the first context prevents source sharing and makes `heap_stats` count every source as mini_racer does.
 
 Approved 2026-10-18.
 

data/Cargo.lock

@@ -458,7 +458,7 @@ checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
 
 [[package]]
 name = "mini_racer_engine"
-version = "1.0.3"
+version = "1.0.5"
 dependencies = [
  "deno_core_icudata",
  "libc",
@@ -470,7 +470,7 @@ dependencies = [
 
 [[package]]
 name = "mini_racer_rs"
-version = "1.0.3"
+version = "1.0.5"
 dependencies = [
  "magnus",
  "mini_racer_engine",
@@ -481,7 +481,7 @@ dependencies = [
 
 [[package]]
 name = "mini_racer_sync"
-version = "1.0.3"
+version = "1.0.5"
 dependencies = [
  "loom",
  "thiserror",
@@ -489,7 +489,7 @@ dependencies = [
 
 [[package]]
 name = "mini_racer_wire"
-version = "1.0.3"
+version = "1.0.5"
 dependencies = [
  "proptest",
  "thiserror",

data/Cargo.toml

@@ -14,7 +14,7 @@ license = "MIT"
 publish = false
 repository = "https://github.com/andymai/mini_racer_rs"
 rust-version = "1.91"
-version = "1.0.3"
+version = "1.0.5"
 
 [workspace.dependencies]
 deno_core_icudata = "=0.78.0"

data/README.md

@@ -21,10 +21,10 @@ mini_racer_rs implements the `MiniRacer` Ruby API from mini_racer 0.22.1, with f
 
 ## Highlights
 
-- **4 to 5 times faster Ruby round trips.** An eval, call, or callback round trip takes 1.3 to 1.6 µs, against 6.1 to 6.6 µs in mini_racer. A call on a context with `timeout:` takes 1.6 µs instead of 21.1 µs because one watchdog serves the process.
-- **1.9 times faster Babel transforms.** A transform through ExecJS takes 5.3 ms instead of 10.0 ms. Babel itself takes 5.3 ms inside V8 15.2, against 10.3 ms inside V8 13.6. Terser and React rendering take about the same time in both gems.
-- **4.6 times faster production bundle loads.** Scripts of 1 MB or more compile from a process-wide V8 code cache. A 44 MB production server rendering bundle loads into a new context in 215 ms against 983 ms. The 8.2 MB MUI bundle loads and renders once in 121 ms against 167 ms, and startup plus Babel takes 14.8 ms against 44.8 ms.
-- **Less memory for loaded and abandoned contexts.** A context holding the 44 MB bundle takes 136 MB against 301 MB, and one holding the MUI bundle takes 56 MB against 110 MB. When 20,000 contexts are left to Ruby's garbage collector, resident memory peaks at 102 MB against 2,916 MB.
+- **JavaScript round trips are 5 to 9 times faster.** An eval takes 1.09 µs against 6.91 µs, a call takes 0.72 µs against 6.51 µs, and a callback takes 1.12 µs against 6.12 µs. A call on a context with `timeout:` takes 0.76 µs instead of 20.48 µs because one watchdog serves the process.
+- **A Babel transform through ExecJS is 1.95x faster.** It takes 5.15 ms instead of 10.05 ms. Babel itself takes 5.3 ms inside V8 15.2, against 10.3 ms inside V8 13.6, while Terser and React rendering take about the same time in both gems.
+- **A 44 MB production server rendering bundle loads 4.6x faster.** It loads into a new context in 215 ms against 983 ms, measured at commit `2513a48`, and scripts of 1 MB or more compile from a process-wide V8 code cache. At commit `220bfe7`, the 8.2 MB MUI bundle loads and renders once in 105 ms against 167 ms, while startup plus Babel takes 13.3 ms against 44.4 ms.
+- **A context holding the MUI bundle uses 44 MB instead of 110 MB.** At commit `220bfe7`, a context holding Babel uses 15.2 MB against 28.5 MB, and contexts loading the same large script read one shared copy of its source. A context holding the 44 MB production bundle used 136 MB against 301 MB at commit `2513a48`, before sources were shared. When 20,000 contexts are left to Ruby's garbage collector, resident memory peaks at 102 MB against 2,920 MB.
 - **Forks pause worker work, and children use their own threads.** For forks made through Ruby's `fork`, `IO.popen("-")`, or `Process.daemon`, mini_racer_rs waits for context runners, pauses its worker pool, and waits for running tasks; an async `WebAssembly.compile` in a new default-mode child completes on the child's own pool. On Ubuntu 24.04 with glibc 2.39, 20 of 20 mini_racer children aborted with signal 6 after loading and rendering React, while 20 of 20 mini_racer_rs children exited cleanly. On Fedora, mini_racer children hung within the first 50 forks of `test/stress/fork_busy.rb`, while mini_racer_rs completed 300 forks per run on Fedora and Ubuntu.
 - **V8 15.2.124.1.** mini_racer 0.22.1 uses V8 13.6.233.17.
 - **No compiler at release install.** Native gems cover glibc Linux on x86_64 and aarch64, plus macOS on arm64 and x86_64. Each carries extensions for Ruby 3.3, 3.4, and 4.0. mini_racer 0.22.1 ships as source and compiles C++ against libv8-node.
@@ -156,21 +156,27 @@ gem "mini_racer", github: "andymai/mini_racer_rs", tag: "vX.Y.Z", glob: "shim/*.
 
 The repository tests shim resolution with `path:` sources and rtlcss in `test/consumers/transitive/`. The `github:` form has not been run end to end. A dependency whose `mini_racer` requirement excludes version 0.22.1 cannot use the shim.
 
+### Forking servers such as Puma
+
+Prime the process-wide V8 code cache before forking by evaluating each bundle of 1 MB or more twice in the master, using exactly the source text and file name the renderer uses, then dispose those contexts. The second evaluation builds the cache, later matching evaluations compile from it, and forked children inherit it. For Babel's 2.3 MB bundle at commit `5e13c1c`, a forked child's first load took, as medians across 5 trials, 60.8 ms when the parent had not loaded it, 65.5 ms after one load, and 25.0 ms after two loads. You can prime a `react-rails` app by building its server renderer twice. Parent contexts are not used in children. Only the cache carries over.
+
+With `mini_racer` 0.22.1, each worker compiles the bundle from source on its first load because there is no code cache.
+
 ## Benchmarks
 
 | Workload | mini_racer 0.22.1 | mini_racer_rs | Ratio |
 |---|---:|---:|---:|
-| Babel transform of a 3 KB JSX component, through ExecJS | 10.0 ms | 5.3 ms | 1.9x |
-| Terser minify of a 78 KB library, through ExecJS | 51.6 ms | 51.2 ms | 1.0x |
-| React server render of 1,000 items (17 KB of HTML), through ExecJS | 192 µs | 174 µs | 1.1x |
-| React in a new context: load the bundle and render 1,000 items, through ExecJS | 12.0 ms | 12.1 ms | 1.0x |
-| Handlebars render of 50 rows, through `Context#call` | 47.9 µs | 40.1 µs | 1.2x |
-| Autoprefixer on Bootstrap's 280 KB stylesheet, through ExecJS | 27.2 ms | 23.7 ms | 1.1x |
-| MUI dashboard server render of 200 rows and 299 icons (469 KB of HTML), through ExecJS | 32.2 ms | 30.5 ms | 1.1x |
-| MUI in a new context: load the 8.2 MB bundle and render once, through ExecJS | 167 ms | 121 ms | 1.4x |
+| Babel transform of a 3 KB JSX component, through ExecJS | 10.1 ms | 5.2 ms | 2.0x |
+| Terser minify of a 78 KB library, through ExecJS | 51.1 ms | 52.0 ms | 1.0x |
+| React server render of 1,000 items (17 KB of HTML), through ExecJS | 191 µs | 174 µs | 1.1x |
+| React in a new context: load the bundle and render 1,000 items, through ExecJS | 11.9 ms | 11.8 ms | 1.0x |
+| Handlebars render of 50 rows, through `Context#call` | 49.1 µs | 34.9 µs | 1.4x |
+| Autoprefixer on Bootstrap's 280 KB stylesheet, through ExecJS | 26.3 ms | 23.7 ms | 1.1x |
+| MUI dashboard server render of 200 rows and 299 icons (469 KB of HTML), through ExecJS | 32.6 ms | 29.8 ms | 1.1x |
+| MUI in a new context: load the 8.2 MB bundle and render once, through ExecJS | 167 ms | 105 ms | 1.6x |
 | Load a 44 MB production server rendering bundle into a new context, through ExecJS | 983 ms | 215 ms | 4.6x |
 
-The table reports the eight library workloads plus the 44 MB production server rendering bundle load. Results are medians of 5 runs from the release build of commit `2513a48`, with every workload producing identical output in both gems. They were measured on Ruby 3.4.2 and Linux on an AMD Ryzen 9 7950X3D, with the CPU governor set to `performance` and both gems pinned to CPUs 0 through 7.
+Results are medians of 5 runs, with every workload producing identical output in both gems. The eight library workloads use the release build of commit `220bfe7`, and the 44 MB production server rendering bundle load uses commit `2513a48`. Measurements ran on Ruby 3.4.2 and Linux on an AMD Ryzen 9 7950X3D, with the CPU governor set to `performance` and both gems pinned to CPUs 0 through 7.
 
 ```sh
 bundle exec ruby bench/run.rb --cpus 0-7

data/crates/mini_racer_engine/src/lib.rs

@@ -14,8 +14,10 @@ mod spin;
     reason = "the engine's only FFI fence: symbols the linker routes into V8"
 )]
 mod sys;
+mod text;
 
 pub use context::{ContextHandle, Host, Unparker, WaitHandle, WaitOutcome};
 pub use control::{CallRequest, CallbackReply, ContextConfig, JsText};
 pub use error::{EngineError, FlagError, InvalidSnapshot, JsError, JsErrorKind, TerminationCause};
 pub use snapshot::{SnapshotBlob, WeakSnapshotBlob};
+pub use text::{Decoded, Transcoder};

data/crates/mini_racer_engine/src/process/code_cache.rs

@@ -21,8 +21,9 @@ const SAMPLE_POINTS: usize = 8;
 /// compiling it again.
 ///
 /// A script is cached the second time the process sees it. The first sighting
-/// costs a sampled digest, not a full one or a cache, as a large script
-/// evaluated once (per-request data, say) gains nothing from either.
+/// costs a sampled digest and no cache, as a large script evaluated once
+/// (per-request data, say) gains nothing from one; it costs the full digest
+/// too only in a context that reads the script from its shared source.
 #[derive(Default)]
 pub struct CodeCache {
     // Most recently used last.
@@ -77,8 +78,9 @@ impl Drop for Building {
 
 /// How the runner compiles a large script.
 pub(crate) enum Plan {
-    /// From source: a first sighting or the cache is off, or with its key, a
-    /// key being built elsewhere or a refused cache.
+    /// From source: the cache is off or a first sighting, or with its key, a
+    /// first sighting whose source is shared, a key being built elsewhere or
+    /// a refused cache.
     Compile(Option<Key>),
     /// From source, then a cache made once the dispatch is over.
     Make(Building),
@@ -87,7 +89,7 @@ pub(crate) enum Plan {
 }
 
 impl Plan {
-    /// The key of a script the process has seen before.
+    /// The script's key, unless the plan needed none.
     pub(crate) const fn key(&self) -> Option<&Key> {
         match self {
             Self::Compile(key) => key.as_ref(),
@@ -98,11 +100,14 @@ impl Plan {
 }
 
 impl CodeCache {
+    /// `shared` asks for a first sighting's key as well, which only a
+    /// context reading the script from its shared source needs.
     pub(crate) fn plan(
         &'static self,
         filename: &JsText,
         source: &JsText,
         snapshot: Option<u64>,
+        shared: bool,
     ) -> Plan {
         if !enabled() {
             return Plan::Compile(None);
@@ -113,7 +118,8 @@ impl CodeCache {
         let cached = lock(&self.entries)
             .iter()
             .any(|entry| entry.key.sighting == sighting);
-        if !seen && !cached {
+        let first = !seen && !cached;
+        if first && !shared {
             return Plan::Compile(None);
         }
         let key = Key {
@@ -123,6 +129,9 @@ impl CodeCache {
             digest: self.hasher.hash_one(source),
             sighting,
         };
+        if first {
+            return Plan::Compile(Some(key));
+        }
         let mut entries = lock(&self.entries);
         if let Some(at) = entries.iter().position(|entry| entry.key == key) {
             let entry = entries.remove(at);
@@ -300,8 +309,8 @@ mod tests {
 
     // Sees `text` twice and stores a cache for it.
     fn cached(cache: &'static CodeCache, text: &JsText, data: Box<[u8]>) {
-        let _ = cache.plan(&name(), text, None);
-        let Plan::Make(building) = cache.plan(&name(), text, None) else {
+        let _ = cache.plan(&name(), text, None, true);
+        let Plan::Make(building) = cache.plan(&name(), text, None, true) else {
             panic!("a second sighting makes a cache");
         };
         cache.store(building, data);
@@ -311,22 +320,46 @@ mod tests {
     fn caches_a_script_the_second_time_it_is_seen() {
         let cache = cache();
         assert!(matches!(
-            cache.plan(&name(), &source(1), None),
-            Plan::Compile(None)
+            cache.plan(&name(), &source(1), None, true),
+            Plan::Compile(Some(_))
         ));
         cached(cache, &source(1), Box::from(&b"compiled"[..]));
         assert!(matches!(
-            cache.plan(&name(), &source(1), None),
+            cache.plan(&name(), &source(1), None, true),
             Plan::Consume(..)
         ));
         assert!(matches!(
-            cache.plan(&name(), &source(1), Some(7)),
-            Plan::Compile(None)
+            cache.plan(&name(), &source(1), Some(7), true),
+            Plan::Compile(Some(_))
         ));
         assert!(matches!(
-            cache.plan(&JsText::from("other.js"), &source(1), None),
+            cache.plan(&JsText::from("other.js"), &source(1), None, true),
+            Plan::Compile(Some(_))
+        ));
+    }
+
+    // The key a first sighting has for its shared source is the one the
+    // cache is then made and found under.
+    #[test]
+    fn a_first_sighting_has_its_key_only_for_a_shared_source() {
+        let cache = cache();
+        assert!(matches!(
+            cache.plan(&name(), &source(8), None, false),
             Plan::Compile(None)
         ));
+        let first = cache.plan(&name(), &source(9), None, true);
+        assert!(matches!(first, Plan::Compile(Some(_))));
+        let second = cache.plan(&name(), &source(9), None, false);
+        assert!(matches!(second, Plan::Make(..)));
+        assert!(first.key() == second.key());
+        let Plan::Make(building) = second else {
+            panic!("a second sighting makes a cache");
+        };
+        cache.store(building, Box::from(&b"compiled"[..]));
+        let Plan::Consume(_, key) = cache.plan(&name(), &source(9), None, true) else {
+            panic!("a stored cache is found");
+        };
+        assert!(first.key() == Some(&key));
     }
 
     // Sources that match on every sampled unit and differ elsewhere share a
@@ -344,7 +377,10 @@ mod tests {
             cache.sighting(&name(), &second, None)
         );
         cached(cache, &first, Box::from(&b"compiled"[..]));
-        assert!(matches!(cache.plan(&name(), &second, None), Plan::Make(..)));
+        assert!(matches!(
+            cache.plan(&name(), &second, None, true),
+            Plan::Make(..)
+        ));
     }
 
     #[test]
@@ -353,10 +389,10 @@ mod tests {
         cached(cache, &source(2), Box::from(&b"compiled"[..]));
         // More sightings than the list keeps.
         for seed in 10_u8..80 {
-            let _ = cache.plan(&name(), &source(seed), None);
+            let _ = cache.plan(&name(), &source(seed), None, false);
         }
         assert!(matches!(
-            cache.plan(&name(), &source(2), None),
+            cache.plan(&name(), &source(2), None, true),
             Plan::Consume(..)
         ));
     }
@@ -364,15 +400,15 @@ mod tests {
     #[test]
     fn a_script_being_built_is_built_once() {
         let cache = cache();
-        let _ = cache.plan(&name(), &source(3), None);
-        let first = cache.plan(&name(), &source(3), None);
+        let _ = cache.plan(&name(), &source(3), None, true);
+        let first = cache.plan(&name(), &source(3), None, true);
         assert!(matches!(first, Plan::Make(..)));
-        let elsewhere = cache.plan(&name(), &source(3), None);
+        let elsewhere = cache.plan(&name(), &source(3), None, true);
         assert!(matches!(elsewhere, Plan::Compile(Some(_))));
         assert!(elsewhere.key() == first.key());
         drop(first);
         assert!(matches!(
-            cache.plan(&name(), &source(3), None),
+            cache.plan(&name(), &source(3), None, true),
             Plan::Make(..)
         ));
     }
@@ -383,7 +419,7 @@ mod tests {
         cached(cache, &source(4), Box::from(&b"compiled"[..]));
         let child: &'static CodeCache = Box::leak(Box::new(cache.inherited()));
         assert!(matches!(
-            child.plan(&name(), &source(4), None),
+            child.plan(&name(), &source(4), None, true),
             Plan::Consume(..)
         ));
     }
@@ -396,7 +432,7 @@ mod tests {
         let child: &'static CodeCache = Box::leak(Box::new(cache.inherited()));
         drop(held);
         assert!(matches!(
-            child.plan(&name(), &source(5), None),
+            child.plan(&name(), &source(5), None, true),
             Plan::Make(..)
         ));
     }
@@ -412,11 +448,11 @@ mod tests {
         );
         assert_eq!(cache.stored(), 1);
         assert!(matches!(
-            cache.plan(&name(), &source(7), None),
+            cache.plan(&name(), &source(7), None, true),
             Plan::Compile(Some(_))
         ));
         assert!(matches!(
-            cache.plan(&name(), &source(6), None),
+            cache.plan(&name(), &source(6), None, true),
             Plan::Consume(..)
         ));
     }