mini_racer_rs 1.0.3 → 1.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dfd3987a3aebfd95013e67e552b2041b991fd7b0da4933f98ae92335f7caa3a4
-  data.tar.gz: 51ccdf38b39ab3f33f771f3cf7fdbd7422bda16037e8bc026cfd64dc6fdfbdae
+  metadata.gz: 7a8339f7ec9dcc06bd136d68328c3b5a8acd48bcb59061fe0e1de97d8163e7a5
+  data.tar.gz: fdb040a4e14239cce537be6724a36410432093b6f6ca0f62d6eec5830d32c6b5
 SHA512:
-  metadata.gz: ca5321d48ea8913f86d8966b6f475857d11b962c1f109e15f049fed590a517233f2cc3772fad99a9ff189f110995d3b2a0268f54e9f90aa48fcdd3cc1ac2b916
-  data.tar.gz: 3c2a6c804148cfd0bdf198d5a63ef4b440d63c667d7468ab646e8b85b277eb15ec0fa26f5d9877f426c01427e8f841723cf31d00bec0ee546881c895d373c61b
+  metadata.gz: e0fa4008ea43a6f4b7b23a5d324d8c58b659da2688243681b59ddb0af21b16fb54bb2677b9952f24381df1965c66ae47722f1c93d5e82d53b89748c2d7e8a60f
+  data.tar.gz: 0b8bb09c4ca879533aa582fc800c9779b56326dc1c52c61d9d78a95132efa96f0898d596a550255d77839c6c51d09695dfe042021b5992141d5dcb3bbbcc57c8

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [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.4"
 dependencies = [
  "deno_core_icudata",
  "libc",
@@ -470,7 +470,7 @@ dependencies = [
 
 [[package]]
 name = "mini_racer_rs"
-version = "1.0.3"
+version = "1.0.4"
 dependencies = [
  "magnus",
  "mini_racer_engine",
@@ -481,7 +481,7 @@ dependencies = [
 
 [[package]]
 name = "mini_racer_sync"
-version = "1.0.3"
+version = "1.0.4"
 dependencies = [
  "loom",
  "thiserror",
@@ -489,7 +489,7 @@ dependencies = [
 
 [[package]]
 name = "mini_racer_wire"
-version = "1.0.3"
+version = "1.0.4"
 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.4"
 
 [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/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(..)
         ));
     }

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

@@ -9,6 +9,7 @@ use crate::process::code_cache::Key;
 const MAX_SOURCES: usize = 8;
 const MAX_BYTES: usize = 256 << 20;
 const MAX_REFUSED: usize = 8;
+const MAX_SWEPT: usize = 8;
 
 /// A large script's source as V8 stores a string of it: a byte a unit when
 /// every unit fits Latin-1, two otherwise. Never changed once made.
@@ -63,8 +64,9 @@ impl Units {
 
 /// One copy of each large script's source, outside every V8 heap.
 ///
-/// A script is kept once the process has seen it before, and every context
-/// compiling it then reads the kept copy in place of one on its own heap.
+/// A script is kept by the first context to compile it, and every context
+/// compiling it, that one included, reads the kept copy in place of one on
+/// its own heap.
 /// Each string V8 makes from one holds a reference to it, which V8 hands back
 /// when the string dies (`sys::external_string`). A source is dropped only
 /// when no string holds one, so V8 never releases the last reference itself.
@@ -72,6 +74,8 @@ pub struct Sources {
     list: Mutex<List>,
     // How many sources, and how many bytes of them, may be kept and read.
     bounds: (usize, usize),
+    // The number the next context's reads are told apart by.
+    next_reader: AtomicU64,
     made: AtomicU64,
     reads: AtomicU64,
     conversions: AtomicU64,
@@ -91,6 +95,9 @@ struct List {
     // left or, as invalid UTF-8, unbounded, so that while it is among the last
     // `MAX_REFUSED` refused it is not converted again without room for it.
     refused: Vec<(Key, usize)>,
+    // The last `MAX_SWEPT` sources swept, so one made again, which a second
+    // context has now read after all, is kept as such.
+    swept: Vec<Key>,
 }
 
 struct Kept {
@@ -99,23 +106,60 @@ struct Kept {
     // The references from this process's list and every ancestor's, which a
     // forked child never touches again; the strings reading it hold the rest.
     held: usize,
+    readers: Readers,
+}
+
+// The contexts that have read a kept source. One alone, as a script evaluated
+// once has, gains nothing from a copy no string reads any more; a source more
+// have read is likely to be read again, and an inherited one is only copied
+// again if a child drops it, so both stay until a new source needs the room.
+#[derive(Clone, Copy, PartialEq, Eq)]
+enum Readers {
+    One(u64),
+    Many,
 }
 
 impl Kept {
     fn unread(&self) -> bool {
         self.units.references() == self.held
     }
+
+    fn spent(&self) -> bool {
+        matches!(self.readers, Readers::One(_)) && self.unread()
+    }
 }
 
 impl List {
-    fn find(&mut self, key: &Key) -> Option<Units> {
+    fn find(&mut self, key: &Key, reader: u64) -> Option<Units> {
         let at = self.kept.iter().position(|kept| kept.key == *key)?;
-        let found = self.kept.remove(at);
+        let mut found = self.kept.remove(at);
+        if found.readers != Readers::One(reader) {
+            found.readers = Readers::Many;
+        }
         let units = found.units.clone();
         self.kept.push(found);
         Some(units)
     }
 
+    // V8's release of a string touches only the count, so a copy whose last
+    // string has gone waits for the next `Sources::units` call.
+    fn sweep(&mut self) -> Vec<Kept> {
+        let spent: Vec<Kept> = self.kept.extract_if(.., |kept| kept.spent()).collect();
+        for kept in &spent {
+            if self.swept.len() >= MAX_SWEPT {
+                self.swept.remove(0);
+            }
+            self.swept.push(kept.key.clone());
+        }
+        spent
+    }
+
+    fn unswept(&mut self, key: &Key) -> bool {
+        let before = self.swept.len();
+        self.swept.retain(|swept| swept != key);
+        self.swept.len() < before
+    }
+
     // Whether `bytes` more fit beside what strings still read, which nothing
     // can drop.
     fn room(&self, bytes: usize, (sources, most): (usize, usize)) -> bool {
@@ -161,30 +205,43 @@ impl Sources {
         Self {
             list: Mutex::default(),
             bounds: (sources, bytes),
+            next_reader: AtomicU64::new(0),
             made: AtomicU64::new(0),
             reads: AtomicU64::new(0),
             conversions: AtomicU64::new(0),
         }
     }
 
+    /// A number for a new context to read shared sources as, told apart from
+    /// every other context of this process.
+    pub(crate) fn reader(&self) -> u64 {
+        self.next_reader.fetch_add(1, Ordering::Relaxed)
+    }
+
     /// The shared source of the script `text` under `key`, kept from the first
-    /// context that asks for it. `None` leaves the context its own copy: the
-    /// source is invalid UTF-8, or too large for what is kept and still read.
-    /// Only a source that may fit is converted, outside the lock.
-    pub(crate) fn units(&self, key: &Key, text: &JsText) -> Option<Units> {
+    /// context that asks for it, for the context `reader`. `None` leaves the
+    /// context its own copy: the source is invalid UTF-8, or too large for
+    /// what is kept and still read. Only a source that may fit is converted,
+    /// outside the lock. Every call looks up the requested source, then drops
+    /// each other copy that no string reads and that one context alone ever
+    /// read.
+    pub(crate) fn units(&self, key: &Key, text: &JsText, reader: u64) -> Option<Units> {
         let mut list = lock(&self.list);
-        if let Some(units) = list.find(key) {
-            return Some(units);
-        }
-        if !list.room(list.least_bytes(key, text), self.bounds) {
-            return None;
-        }
+        // Found before the sweep, so a copy the context before this one left
+        // unread is read again, and kept, rather than copied again.
+        let found = list.find(key, reader);
+        let spent = list.sweep();
+        let room = found.is_none() && list.room(list.least_bytes(key, text), self.bounds);
         drop(list);
+        drop(spent);
+        if !room {
+            return found;
+        }
         self.conversions.fetch_add(1, Ordering::Relaxed);
         let units = Units::of(text);
         let mut list = lock(&self.list);
         // Made meanwhile by a context loading the same script.
-        if let Some(found) = list.find(key) {
+        if let Some(found) = list.find(key, reader) {
             return Some(found);
         }
         let bytes = units.as_ref().map_or(usize::MAX, Units::bytes);
@@ -211,13 +268,20 @@ impl Sources {
             };
             dropped.push(list.kept.remove(at));
         }
+        let readers = if list.unswept(key) {
+            Readers::Many
+        } else {
+            Readers::One(reader)
+        };
         list.kept.push(Kept {
             key: key.clone(),
             units: units.clone(),
             held: 1,
+            readers,
         });
         drop(list);
-        // Freed once the lock is released, as a large source takes a while.
+        // Freed once the lock is released, as a large source takes a while,
+        // like the spent copies above.
         drop(dropped);
         self.made.fetch_add(1, Ordering::Relaxed);
         Some(units)
@@ -242,9 +306,11 @@ impl Sources {
                         key: kept.key.clone(),
                         units: kept.units.clone(),
                         held: kept.held + 1,
+                        readers: Readers::Many,
                     })
                     .collect(),
                 refused: list.refused.clone(),
+                swept: list.swept.clone(),
             })
             .unwrap_or_default();
         Self {
@@ -291,16 +357,14 @@ mod tests {
     use crate::control::JsText;
     use crate::process::code_cache::{CodeCache, Key};
 
-    // A script's key once the code cache has seen it twice.
+    // A script's key, as its first sighting in a context sharing it has it.
     fn key(text: &JsText) -> Key {
         let cache: &'static CodeCache = Box::leak(Box::default());
-        let name = JsText::from("bundle.js");
-        let _ = cache.plan(&name, text, None);
         cache
-            .plan(&name, text, None)
+            .plan(&JsText::from("bundle.js"), text, None, true)
             .key()
             .cloned()
-            .unwrap_or_else(|| panic!("a second sighting has a key"))
+            .unwrap_or_else(|| panic!("a shared first sighting has a key"))
     }
 
     fn script(seed: u8) -> JsText {
@@ -356,8 +420,8 @@ mod tests {
         let sources = Sources::default();
         let text = script(1);
         let key = key(&text);
-        let first = one_byte(sources.units(&key, &text));
-        let second = one_byte(sources.units(&key, &text));
+        let first = one_byte(sources.units(&key, &text, sources.reader()));
+        let second = one_byte(sources.units(&key, &text, sources.reader()));
         assert!(Arc::ptr_eq(&first, &second));
         assert_eq!(sources.made(), 1);
         assert_eq!(sources.reading(), 2);
@@ -377,6 +441,12 @@ mod tests {
         }
     }
 
+    // A copy two contexts have read, the second still reading it.
+    fn shared(sources: &Sources, key: &Key, text: &JsText) -> Option<Units> {
+        drop(sources.units(key, text, sources.reader()));
+        sources.units(key, text, sources.reader())
+    }
+
     #[test]
     fn a_source_still_read_is_kept_and_an_unread_one_makes_room() {
         let sources = Sources::default();
@@ -386,31 +456,108 @@ mod tests {
         let mut read: Vec<Option<Units>> = texts
             .iter()
             .zip(&keys)
-            .map(|(text, key)| sources.units(key, text))
+            .map(|(text, key)| shared(&sources, key, text))
             .collect();
         let extra = script(100);
         let extra_key = key(&extra);
-        assert!(sources.units(&extra_key, &extra).is_none());
+        assert!(shared(&sources, &extra_key, &extra).is_none());
         drop(read.remove(3));
         drop(read.remove(0));
-        drop(sources.units(&keys[3], &texts[3]));
+        drop(sources.units(&keys[3], &texts[3], sources.reader()));
         // Of the two unread, the least recently used makes room.
-        assert!(sources.units(&extra_key, &extra).is_some());
+        assert!(shared(&sources, &extra_key, &extra).is_some());
         let made = sources.made();
         assert_eq!(made, u64::from(count) + 1);
-        drop(sources.units(&keys[3], &texts[3]));
+        drop(sources.units(&keys[3], &texts[3], sources.reader()));
         assert_eq!(sources.made(), made);
-        drop(sources.units(&keys[0], &texts[0]));
+        drop(sources.units(&keys[0], &texts[0], sources.reader()));
         assert_eq!(sources.made(), made + 1);
         for (at, held) in [1, 2, 4, 5, 6, 7].into_iter().zip(&read) {
             assert!(same(
-                sources.units(&keys[at], &texts[at]).as_ref(),
+                sources
+                    .units(&keys[at], &texts[at], sources.reader())
+                    .as_ref(),
                 held.as_ref()
             ));
         }
         assert_eq!(sources.made(), made + 1);
     }
 
+    // One context's copy, however often it read it, waits for no new source
+    // once no string reads it: the next call drops and frees it.
+    #[test]
+    fn a_copy_one_context_read_goes_at_the_next_call_once_unread() {
+        let sources = Sources::default();
+        let (text, other) = (script(70), script(71));
+        let (key, other_key) = (key(&text), key(&other));
+        let reader = sources.reader();
+        let first = one_byte(sources.units(&key, &text, reader));
+        let again = one_byte(sources.units(&key, &text, reader));
+        assert!(Arc::ptr_eq(&first, &again));
+        let copy = Arc::downgrade(&first);
+        drop((first, again));
+        assert!(copy.upgrade().is_some());
+        drop(sources.units(&other_key, &other, sources.reader()));
+        assert!(copy.upgrade().is_none());
+        drop(sources.units(&key, &text, sources.reader()));
+        assert_eq!(sources.made(), 3);
+    }
+
+    #[test]
+    fn a_copy_two_contexts_read_in_turn_stays_once_unread() {
+        let sources = Sources::default();
+        let (text, other) = (script(72), script(73));
+        let (key, other_key) = (key(&text), key(&other));
+        let copy = Arc::downgrade(&one_byte(shared(&sources, &key, &text)));
+        drop(sources.units(&other_key, &other, sources.reader()));
+        let again = one_byte(sources.units(&key, &text, sources.reader()));
+        assert!(
+            copy.upgrade()
+                .is_some_and(|copy| Arc::ptr_eq(&copy, &again))
+        );
+        assert_eq!(sources.made(), 2);
+    }
+
+    #[test]
+    fn a_copy_a_second_context_reads_while_the_first_does_stays_once_unread() {
+        let sources = Sources::default();
+        let (text, other) = (script(74), script(75));
+        let (key, other_key) = (key(&text), key(&other));
+        let first = one_byte(sources.units(&key, &text, sources.reader()));
+        let second = one_byte(sources.units(&key, &text, sources.reader()));
+        let copy = Arc::downgrade(&first);
+        drop((first, second));
+        drop(sources.units(&other_key, &other, sources.reader()));
+        let again = one_byte(sources.units(&key, &text, sources.reader()));
+        assert!(
+            copy.upgrade()
+                .is_some_and(|copy| Arc::ptr_eq(&copy, &again))
+        );
+        assert_eq!(sources.made(), 2);
+    }
+
+    // Contexts loading two scripts in turn, each gone before the next, sweep
+    // each other's copy; a copy made again after its sweep is kept as one more
+    // than one context read, so each script is converted twice in all.
+    #[test]
+    fn scripts_loaded_in_turn_by_short_lived_contexts_stay_after_their_second_copy() {
+        let sources = Sources::default();
+        let texts = [script(78), script(79)];
+        let keys = texts.each_ref().map(key);
+        for _ in 0..2 {
+            for (key, text) in keys.iter().zip(&texts) {
+                drop(sources.units(key, text, sources.reader()));
+            }
+        }
+        assert_eq!(sources.made(), 4);
+        for _ in 0..3 {
+            for (key, text) in keys.iter().zip(&texts) {
+                drop(sources.units(key, text, sources.reader()));
+            }
+        }
+        assert_eq!(sources.made(), 4);
+    }
+
     #[test]
     fn a_full_list_converts_nothing() {
         let sources = Sources::default();
@@ -418,18 +565,26 @@ mod tests {
         let read: Vec<Option<Units>> = (40..40 + count)
             .map(|seed| {
                 let text = script(seed);
-                sources.units(&key(&text), &text)
+                sources.units(&key(&text), &text, sources.reader())
             })
             .collect();
         let converted = sources.conversions();
         let extra = script(100);
         let extra_key = key(&extra);
         for _ in 0..3 {
-            assert!(sources.units(&extra_key, &extra).is_none());
+            assert!(
+                sources
+                    .units(&extra_key, &extra, sources.reader())
+                    .is_none()
+            );
         }
         assert_eq!(sources.conversions(), converted);
         drop(read);
-        assert!(sources.units(&extra_key, &extra).is_some());
+        assert!(
+            sources
+                .units(&extra_key, &extra, sources.reader())
+                .is_some()
+        );
         assert_eq!(sources.conversions(), converted + 1);
     }
 
@@ -440,21 +595,29 @@ mod tests {
     fn a_source_is_converted_only_while_it_may_fit() {
         let sources = Sources::bounded(MAX_SOURCES, 5 << 20);
         let read = script(50);
-        let still_read = sources.units(&key(&read), &read);
+        let still_read = sources.units(&key(&read), &read, sources.reader());
         assert!(still_read.is_some());
         let too_large = JsText::Latin1(vec![51; 4 << 20]);
-        assert!(sources.units(&key(&too_large), &too_large).is_none());
+        assert!(
+            sources
+                .units(&key(&too_large), &too_large, sources.reader())
+                .is_none()
+        );
         assert_eq!(sources.conversions(), 1);
         let mut astral = vec![b'a'; 2 << 20];
         astral.extend_from_slice("\u{1F600}".as_bytes());
         let astral = JsText::Utf8(astral);
         let astral_key = key(&astral);
         for _ in 0..3 {
-            assert!(sources.units(&astral_key, &astral).is_none());
+            assert!(
+                sources
+                    .units(&astral_key, &astral, sources.reader())
+                    .is_none()
+            );
         }
         assert_eq!(sources.conversions(), 2);
         drop(still_read);
-        assert!(two_byte(sources.units(&astral_key, &astral)).len() > 2 << 20);
+        assert!(two_byte(sources.units(&astral_key, &astral, sources.reader())).len() > 2 << 20);
         assert_eq!((sources.conversions(), sources.made()), (3, 2));
     }
 
@@ -466,7 +629,11 @@ mod tests {
         let invalid = JsText::Utf8(invalid);
         let invalid_key = key(&invalid);
         for _ in 0..3 {
-            assert!(sources.units(&invalid_key, &invalid).is_none());
+            assert!(
+                sources
+                    .units(&invalid_key, &invalid, sources.reader())
+                    .is_none()
+            );
         }
         assert_eq!((sources.conversions(), sources.made()), (1, 0));
     }
@@ -476,32 +643,56 @@ mod tests {
         let parent: &'static Sources = Box::leak(Box::default());
         let text = script(2);
         let key = key(&text);
-        let shared = parent.units(&key, &text);
+        let shared = parent.units(&key, &text, parent.reader());
         let child = parent.inherited();
-        let in_child = child.units(&key, &text);
+        let in_child = child.units(&key, &text, child.reader());
         assert!(same(shared.as_ref(), in_child.as_ref()));
         assert_eq!(child.reading(), 2);
         let copy = Arc::downgrade(&one_byte(shared));
         drop(in_child);
+        // Sources the child still reads fill its list, so the unread
+        // inherited copy makes room.
         let count = u8::try_from(MAX_SOURCES).unwrap_or(u8::MAX);
-        for seed in 30..30 + count {
-            let other = script(seed);
-            drop(child.units(&self::key(&other), &other));
-        }
+        let others: Vec<Option<Units>> = (30..30 + count)
+            .map(|seed| {
+                let other = script(seed);
+                child.units(&self::key(&other), &other, child.reader())
+            })
+            .collect();
         assert_eq!(copy.strong_count(), 1);
-        let again = one_byte(child.units(&key, &text));
+        drop(others);
+        let again = one_byte(child.units(&key, &text, child.reader()));
         assert!(
             !copy
                 .upgrade()
                 .is_some_and(|copy| Arc::ptr_eq(&copy, &again))
         );
-        let from_parent = one_byte(parent.units(&key, &text));
+        let from_parent = one_byte(parent.units(&key, &text, parent.reader()));
         assert!(
             copy.upgrade()
                 .is_some_and(|copy| Arc::ptr_eq(&copy, &from_parent))
         );
     }
 
+    // Dropping an inherited copy frees nothing in a child, and its next
+    // context loading the script would copy it again, so the child keeps
+    // one only its parent's context read.
+    #[test]
+    fn a_child_keeps_an_inherited_copy_one_context_read() {
+        let parent: &'static Sources = Box::leak(Box::default());
+        let (text, other) = (script(76), script(77));
+        let (key, other_key) = (key(&text), key(&other));
+        let copy = Arc::downgrade(&one_byte(parent.units(&key, &text, parent.reader())));
+        let child = parent.inherited();
+        drop(child.units(&other_key, &other, child.reader()));
+        let in_child = one_byte(child.units(&key, &text, child.reader()));
+        assert!(
+            copy.upgrade()
+                .is_some_and(|copy| Arc::ptr_eq(&copy, &in_child))
+        );
+        assert_eq!(child.made(), 1);
+    }
+
     // A child's inherited copies stay read while its parent's strings hold
     // them, so a child forked with a full list must not convert either.
     #[test]
@@ -511,14 +702,14 @@ mod tests {
         let read: Vec<Option<Units>> = (60..60 + count)
             .map(|seed| {
                 let text = script(seed);
-                parent.units(&key(&text), &text)
+                parent.units(&key(&text), &text, parent.reader())
             })
             .collect();
         let child = parent.inherited();
         let extra = script(110);
         let extra_key = key(&extra);
         for _ in 0..3 {
-            assert!(child.units(&extra_key, &extra).is_none());
+            assert!(child.units(&extra_key, &extra, child.reader()).is_none());
         }
         assert_eq!(child.conversions(), 0);
         drop(read);
@@ -529,11 +720,14 @@ mod tests {
         let parent = Sources::default();
         let text = script(3);
         let key = key(&text);
-        let shared = one_byte(parent.units(&key, &text));
+        let shared = one_byte(parent.units(&key, &text, parent.reader()));
         let held = parent.list.lock();
         let child = parent.inherited();
         drop(held);
-        assert!(!Arc::ptr_eq(&shared, &one_byte(child.units(&key, &text))));
+        assert!(!Arc::ptr_eq(
+            &shared,
+            &one_byte(child.units(&key, &text, child.reader()))
+        ));
         assert_eq!(child.made(), 1);
     }
 }

data/crates/mini_racer_engine/src/runner.rs

@@ -62,6 +62,9 @@ struct Runtime {
     freed: AtomicBool,
     // The startup snapshot this isolate began from, for the code cache's key.
     snapshot: Option<u64>,
+    // Tells this context's reads of a shared source from other contexts', as
+    // a copy only one context read is dropped once no string reads it.
+    reader: u64,
     // Large scripts to cache once their dispatch is over, so making a cache
     // never counts against a timeout.
     uncached: Mutex<Vec<Uncached>>,
@@ -142,6 +145,7 @@ impl Runtime {
             running: AtomicU32::new(0),
             freed: AtomicBool::new(false),
             snapshot,
+            reader: generation.sources().reader(),
             uncached: Mutex::default(),
             hoisting: Mutex::default(),
             frames: Mutex::default(),
@@ -770,10 +774,12 @@ fn evaluate(
     }
     let plan = if large(source) {
         runtime.freed.store(true, Ordering::Relaxed);
-        runtime
-            .generation
-            .code_cache()
-            .plan(filename, source, runtime.snapshot)
+        runtime.generation.code_cache().plan(
+            filename,
+            source,
+            runtime.snapshot,
+            shares_sources(runtime),
+        )
     } else {
         Plan::Compile(None)
     };
@@ -796,21 +802,25 @@ fn evaluate(
     Ok(reply)
 }
 
-// A large script the process has seen before reads its source from the copy
-// every context compiling it shares, outside the V8 heap. `max_memory:`
-// measures the heap, where mini_racer keeps the source, so a context with it
-// keeps its own copy.
+// `max_memory:` measures the heap, where mini_racer keeps the source, so a
+// context with it keeps its own copy.
+fn shares_sources(runtime: &Runtime) -> bool {
+    runtime.block.config.max_memory.is_none()
+}
+
+// A large script reads its source from the copy every context compiling it
+// shares, outside the V8 heap, made by the first of them.
 fn shared_source<'s>(
     scope: &v8::PinScope<'s, '_>,
     runtime: &Runtime,
     key: Option<&Key>,
     source: &JsText,
 ) -> Option<v8::Local<'s, v8::String>> {
-    if runtime.block.config.max_memory.is_some() {
+    if !shares_sources(runtime) {
         return None;
     }
     let sources = runtime.generation.sources();
-    let string = sys::external_string(scope, &sources.units(key?, source)?)?;
+    let string = sys::external_string(scope, &sources.units(key?, source, runtime.reader)?)?;
     sources.read();
     Some(string)
 }

data/lib/mini_racer_rs/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module MiniRacerRs
-  VERSION = "1.0.3"
+  VERSION = "1.0.4"
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: mini_racer_rs
 version: !ruby/object:Gem::Version
-  version: 1.0.3
+  version: 1.0.4
 platform: ruby
 authors:
 - Andy Aragon
 bindir: bin
 cert_chain: []
-date: 2026-10-18 00:00:00.000000000 Z
+date: 2026-10-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rb_sys