mini_racer_rs 1.0.1 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aeb35a422c03ec1f8366cc6794daefa2cbacd69d8e113c0e1cb1d369a274cf07
-  data.tar.gz: e672b7b588ec4eb10e95317af8eea2a5d03aaf7340200b70c307f6a74e988606
+  metadata.gz: 1b53466394528b78785dc0cac7e884a5b59f0200ca037d405c95375152a12d72
+  data.tar.gz: 06b9b34066ec568f0a41186f5f7c533c3a17f7acb90a625ec8e9fff22b3069f5
 SHA512:
-  metadata.gz: 95f7422df0c8a5f74675fdcdcf9ba1d9e9c3e7278a67b1bd57a4964ee38a022570b2b968db0a3b81af8e6320b2d2bbb9d98489bdfd87b3a8f78edb5971a595f9
-  data.tar.gz: 5288702eb114fe82c194a5071e15c99f36e6d2dbfb7c6541813074b89fb774a446dd84f4198c494306401a26cfda8932a082d8904f28bd468f01cda11bc29dcd
+  metadata.gz: 7e9f4ee092b37374b56a701831bd4ba868af74de863c220a9f58aae583505cc3c4000106107cfe8c8e709552863d5b484b8715cd016306ecb06241f2d84fe759
+  data.tar.gz: d5dc38c171b8d11683d53840d6c671cbf90ae042dba02f1a46e9786f343e555356808e41e2fb460b00a440c326a2da23f737b1149ab96d359b4e2269981c8b36

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [1.0.2](https://github.com/andymai/mini_racer_rs/compare/v1.0.1...v1.0.2) (2026-10-18)
+
+
+### Performance
+
+* **engine:** share one copy of a large repeated source across contexts ([#85](https://github.com/andymai/mini_racer_rs/issues/85)) ([9fe050a](https://github.com/andymai/mini_racer_rs/commit/9fe050a7a612314264e255f9bcc40ca146e93571))
+
 ## [1.0.1](https://github.com/andymai/mini_racer_rs/compare/v1.0.0...v1.0.1) (2026-10-18)
 
 

data/COMPATIBILITY.md

@@ -4,7 +4,7 @@
 
 | Engine | Done | Planned | Deviation |
 |---|---|---|---|
-| CRuby | 54 | 0 | 25 |
+| CRuby | 54 | 0 | 26 |
 | TruffleRuby | 58 | 0 | 0 |
 
 ## Surface
@@ -180,6 +180,12 @@ mini_racer_rs supports glibc Linux on x86_64 and aarch64, plus macOS on arm64 an
 
 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.
+
+Approved 2026-10-18.
+
 ### `behavior:snapshot-filter-context@ruby`
 
 mini_racer_rs returns the same filtered results from a snapshot-based context as from a context without a snapshot. In a context made from `MiniRacer::Snapshot.new("Object.getOwnPropertyDescriptors = () => ({})")`, `({a: 1, f() {}})` returns `{"a" => 1}`, and `[1, function() {}]` returns `[1]`. mini_racer 0.22.1 returns `nil` for both. Both gems copy results that V8 refuses to serialize as is through a filter in a separate safe context. mini_racer_rs keeps an untouched context in each snapshot blob and uses it for that filter, while mini_racer 0.22.1 builds the safe context from the snapshot, exposing the filter's built-ins to snapshot code. User code still sees the replacement in both gems: `Object.getOwnPropertyDescriptors({a: 1})` returns `{}`.

data/Cargo.lock

@@ -458,7 +458,7 @@ checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
 
 [[package]]
 name = "mini_racer_engine"
-version = "1.0.1"
+version = "1.0.2"
 dependencies = [
  "deno_core_icudata",
  "libc",
@@ -470,7 +470,7 @@ dependencies = [
 
 [[package]]
 name = "mini_racer_rs"
-version = "1.0.1"
+version = "1.0.2"
 dependencies = [
  "magnus",
  "mini_racer_engine",
@@ -481,7 +481,7 @@ dependencies = [
 
 [[package]]
 name = "mini_racer_sync"
-version = "1.0.1"
+version = "1.0.2"
 dependencies = [
  "loom",
  "thiserror",
@@ -489,7 +489,7 @@ dependencies = [
 
 [[package]]
 name = "mini_racer_wire"
-version = "1.0.1"
+version = "1.0.2"
 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.1"
+version = "1.0.2"
 
 [workspace.dependencies]
 deno_core_icudata = "=0.78.0"

data/README.md

@@ -183,7 +183,7 @@ bundle exec ruby bench/run.rb --cpus 0-7
 
 | Engine | Done | Planned | Deviation |
 |---|---|---|---|
-| CRuby | 54 | 0 | 25 |
+| CRuby | 54 | 0 | 26 |
 | TruffleRuby | 58 | 0 | 0 |
 
 See [COMPATIBILITY.md](COMPATIBILITY.md).

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

@@ -77,15 +77,26 @@ impl Drop for Building {
 
 /// How the runner compiles a large script.
 pub(crate) enum Plan {
-    /// From source: a first sighting, a key being built elsewhere, a refused
-    /// cache, or the cache is off.
-    Compile,
+    /// From source: a first sighting or the cache is off, or with its key, 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),
     /// From the entry, falling back to source if V8 refuses it.
     Consume(Arc<Entry>, Key),
 }
 
+impl Plan {
+    /// The key of a script the process has seen before.
+    pub(crate) const fn key(&self) -> Option<&Key> {
+        match self {
+            Self::Compile(key) => key.as_ref(),
+            Self::Make(building) => Some(&building.key),
+            Self::Consume(_, key) => Some(key),
+        }
+    }
+}
+
 impl CodeCache {
     pub(crate) fn plan(
         &'static self,
@@ -94,7 +105,7 @@ impl CodeCache {
         snapshot: Option<u64>,
     ) -> Plan {
         if !enabled() {
-            return Plan::Compile;
+            return Plan::Compile(None);
         }
         let sighting = self.sighting(filename, source, snapshot);
         let seen = touch(&self.sightings, sighting, MAX_SIGHTINGS);
@@ -103,7 +114,7 @@ impl CodeCache {
             .iter()
             .any(|entry| entry.key.sighting == sighting);
         if !seen && !cached {
-            return Plan::Compile;
+            return Plan::Compile(None);
         }
         let key = Key {
             filename: filename.clone(),
@@ -121,9 +132,10 @@ impl CodeCache {
         }
         drop(entries);
         if lock(&self.refused).contains(&key) {
-            return Plan::Compile;
+            return Plan::Compile(Some(key));
         }
-        self.begin(key).map_or(Plan::Compile, Plan::Make)
+        self.begin(key.clone())
+            .map_or(Plan::Compile(Some(key)), Plan::Make)
     }
 
     /// Claims `key` for this context to build, unless another is building it.
@@ -300,7 +312,7 @@ mod tests {
         let cache = cache();
         assert!(matches!(
             cache.plan(&name(), &source(1), None),
-            Plan::Compile
+            Plan::Compile(None)
         ));
         cached(cache, &source(1), Box::from(&b"compiled"[..]));
         assert!(matches!(
@@ -309,11 +321,11 @@ mod tests {
         ));
         assert!(matches!(
             cache.plan(&name(), &source(1), Some(7)),
-            Plan::Compile
+            Plan::Compile(None)
         ));
         assert!(matches!(
             cache.plan(&JsText::from("other.js"), &source(1), None),
-            Plan::Compile
+            Plan::Compile(None)
         ));
     }
 
@@ -355,10 +367,9 @@ mod tests {
         let _ = cache.plan(&name(), &source(3), None);
         let first = cache.plan(&name(), &source(3), None);
         assert!(matches!(first, Plan::Make(..)));
-        assert!(matches!(
-            cache.plan(&name(), &source(3), None),
-            Plan::Compile
-        ));
+        let elsewhere = cache.plan(&name(), &source(3), None);
+        assert!(matches!(elsewhere, Plan::Compile(Some(_))));
+        assert!(elsewhere.key() == first.key());
         drop(first);
         assert!(matches!(
             cache.plan(&name(), &source(3), None),
@@ -402,7 +413,7 @@ mod tests {
         assert_eq!(cache.stored(), 1);
         assert!(matches!(
             cache.plan(&name(), &source(7), None),
-            Plan::Compile
+            Plan::Compile(Some(_))
         ));
         assert!(matches!(
             cache.plan(&name(), &source(6), None),

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

@@ -7,6 +7,7 @@ use mini_racer_sync::{ForkGate, Phase, lock};
 
 use crate::control::ControlBlock;
 use crate::process::code_cache::CodeCache;
+use crate::process::sources::Sources;
 use crate::process::tasks::TaskRegistry;
 use crate::process::watchdog::Watchdog;
 use crate::process::workers::Workers;
@@ -51,13 +52,14 @@ pub struct Generation {
     watchdog: Mutex<Option<Arc<Watchdog>>>,
     workers: Workers,
     code_cache: CodeCache,
+    sources: Sources,
     next: OnceLock<Box<Self>>,
 }
 
 static ROOT: OnceLock<Generation> = OnceLock::new();
 
 impl Generation {
-    fn new(epoch: u64, quiesced: bool, code_cache: CodeCache) -> Self {
+    fn new(epoch: u64, quiesced: bool, code_cache: CodeCache, sources: Sources) -> Self {
         Self {
             epoch,
             quiesced,
@@ -69,6 +71,7 @@ impl Generation {
             watchdog: Mutex::new(None),
             workers: Workers::default(),
             code_cache,
+            sources,
             next: OnceLock::new(),
         }
     }
@@ -94,6 +97,11 @@ impl Generation {
         &self.code_cache
     }
 
+    #[must_use]
+    pub const fn sources(&self) -> &Sources {
+        &self.sources
+    }
+
     pub fn register(&self, block: &Arc<ControlBlock>) {
         let mut blocks = lock(&self.blocks);
         blocks.retain(|block| block.strong_count() > 0);
@@ -115,7 +123,8 @@ impl Generation {
 
 pub fn current() -> &'static Generation {
     let epoch = epoch();
-    let mut generation = ROOT.get_or_init(|| Generation::new(epoch, true, CodeCache::default()));
+    let mut generation =
+        ROOT.get_or_init(|| Generation::new(epoch, true, CodeCache::default(), Sources::default()));
     while generation.epoch != epoch {
         let quiesced = generation.quiesced && generation.prepared.load(Ordering::SeqCst);
         let next = generation.epoch.saturating_add(1);
@@ -125,6 +134,7 @@ pub fn current() -> &'static Generation {
                 next,
                 quiesced,
                 parent.code_cache.inherited(),
+                parent.sources.inherited(),
             ))
         });
     }

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

@@ -0,0 +1,539 @@
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::sync::{Arc, Mutex};
+
+use mini_racer_sync::lock;
+
+use crate::control::JsText;
+use crate::process::code_cache::Key;
+
+const MAX_SOURCES: usize = 8;
+const MAX_BYTES: usize = 256 << 20;
+const MAX_REFUSED: 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.
+#[derive(Clone)]
+pub(crate) enum Units {
+    OneByte(Arc<[u8]>),
+    TwoByte(Arc<[u16]>),
+}
+
+impl Units {
+    // V8 decodes valid UTF-8 to the same units; invalid UTF-8 is left to its
+    // own decoder, whose replacements this does not repeat.
+    fn of(text: &JsText) -> Option<Self> {
+        Some(match text {
+            JsText::Latin1(bytes) => Self::OneByte(Arc::from(bytes.as_slice())),
+            JsText::Utf8(bytes) if bytes.is_ascii() => Self::OneByte(Arc::from(bytes.as_slice())),
+            JsText::Utf8(bytes) => {
+                let text = std::str::from_utf8(bytes).ok()?;
+                text.chars()
+                    .map(u8::try_from)
+                    .collect::<Result<_, _>>()
+                    .map_or_else(
+                        |_| Self::TwoByte(text.encode_utf16().collect()),
+                        Self::OneByte,
+                    )
+            }
+            JsText::Utf16(units) => units
+                .iter()
+                .map(|&unit| u8::try_from(unit))
+                .collect::<Result<_, _>>()
+                .map_or_else(
+                    |_| Self::TwoByte(Arc::from(units.as_slice())),
+                    Self::OneByte,
+                ),
+        })
+    }
+
+    fn bytes(&self) -> usize {
+        match self {
+            Self::OneByte(bytes) => bytes.len(),
+            Self::TwoByte(units) => units.len() * 2,
+        }
+    }
+
+    fn references(&self) -> usize {
+        match self {
+            Self::OneByte(bytes) => Arc::strong_count(bytes),
+            Self::TwoByte(units) => Arc::strong_count(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.
+/// 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.
+pub struct Sources {
+    list: Mutex<List>,
+    // How many sources, and how many bytes of them, may be kept and read.
+    bounds: (usize, usize),
+    made: AtomicU64,
+    reads: AtomicU64,
+    conversions: AtomicU64,
+}
+
+impl Default for Sources {
+    fn default() -> Self {
+        Self::bounded(MAX_SOURCES, MAX_BYTES)
+    }
+}
+
+#[derive(Default)]
+struct List {
+    // Most recently used last.
+    kept: Vec<Kept>,
+    // What each source converted and left unkept takes, too much for the room
+    // 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)>,
+}
+
+struct Kept {
+    key: Key,
+    units: Units,
+    // 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,
+}
+
+impl Kept {
+    fn unread(&self) -> bool {
+        self.units.references() == self.held
+    }
+}
+
+impl List {
+    fn find(&mut self, key: &Key) -> Option<Units> {
+        let at = self.kept.iter().position(|kept| kept.key == *key)?;
+        let found = self.kept.remove(at);
+        let units = found.units.clone();
+        self.kept.push(found);
+        Some(units)
+    }
+
+    // Whether `bytes` more fit beside what strings still read, which nothing
+    // can drop.
+    fn room(&self, bytes: usize, (sources, most): (usize, usize)) -> bool {
+        let (read, read_bytes) = self
+            .kept
+            .iter()
+            .filter(|kept| !kept.unread())
+            .fold((0, 0), |(count, total), kept| {
+                (count + 1, total + kept.units.bytes())
+            });
+        read < sources && read_bytes.saturating_add(bytes) <= most
+    }
+
+    fn refuse(&mut self, key: &Key, bytes: usize) {
+        self.refused.retain(|(refused, _)| refused != key);
+        if self.refused.len() >= MAX_REFUSED {
+            self.refused.remove(0);
+        }
+        self.refused.push((key.clone(), bytes));
+    }
+
+    fn least_bytes(&self, key: &Key, text: &JsText) -> usize {
+        self.refused
+            .iter()
+            .find(|(refused, _)| refused == key)
+            .map_or_else(|| least_bytes(text), |&(_, bytes)| bytes)
+    }
+}
+
+// The fewest bytes `text` can take as units, so a source that cannot fit is
+// never converted: UTF-8 takes at least a byte for every two, as Latin-1
+// written in UTF-8 does.
+const fn least_bytes(text: &JsText) -> usize {
+    match text {
+        JsText::Latin1(bytes) => bytes.len(),
+        JsText::Utf8(bytes) => bytes.len().div_ceil(2),
+        JsText::Utf16(units) => units.len(),
+    }
+}
+
+impl Sources {
+    fn bounded(sources: usize, bytes: usize) -> Self {
+        Self {
+            list: Mutex::default(),
+            bounds: (sources, bytes),
+            made: AtomicU64::new(0),
+            reads: AtomicU64::new(0),
+            conversions: AtomicU64::new(0),
+        }
+    }
+
+    /// 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> {
+        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;
+        }
+        drop(list);
+        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) {
+            return Some(found);
+        }
+        let bytes = units.as_ref().map_or(usize::MAX, Units::bytes);
+        if !list.room(bytes, self.bounds) {
+            list.refuse(key, bytes);
+            drop(list);
+            return None;
+        }
+        let units = units?;
+        list.refused.retain(|(refused, _)| refused != key);
+        let (sources, most) = self.bounds;
+        let mut dropped = Vec::new();
+        while list.kept.len() >= sources
+            || list
+                .kept
+                .iter()
+                .map(|kept| kept.units.bytes())
+                .sum::<usize>()
+                + bytes
+                > most
+        {
+            let Some(at) = list.kept.iter().position(Kept::unread) else {
+                break;
+            };
+            dropped.push(list.kept.remove(at));
+        }
+        list.kept.push(Kept {
+            key: key.clone(),
+            units: units.clone(),
+            held: 1,
+        });
+        drop(list);
+        // Freed once the lock is released, as a large source takes a while.
+        drop(dropped);
+        self.made.fetch_add(1, Ordering::Relaxed);
+        Some(units)
+    }
+
+    pub(crate) fn read(&self) {
+        self.reads.fetch_add(1, Ordering::Relaxed);
+    }
+
+    /// A forked child's sources: what its parent kept, unless a thread of the
+    /// parent held them at the fork. The parent's list keeps its references
+    /// in the child, so the child frees none of these.
+    pub(crate) fn inherited(&self) -> Self {
+        let list = self
+            .list
+            .try_lock()
+            .map(|list| List {
+                kept: list
+                    .kept
+                    .iter()
+                    .map(|kept| Kept {
+                        key: kept.key.clone(),
+                        units: kept.units.clone(),
+                        held: kept.held + 1,
+                    })
+                    .collect(),
+                refused: list.refused.clone(),
+            })
+            .unwrap_or_default();
+        Self {
+            list: Mutex::new(list),
+            ..Self::bounded(self.bounds.0, self.bounds.1)
+        }
+    }
+
+    /// Sources this process made and kept.
+    #[must_use]
+    pub fn made(&self) -> u64 {
+        self.made.load(Ordering::Relaxed)
+    }
+
+    /// Strings this process's contexts made from a kept source.
+    #[must_use]
+    pub fn reads(&self) -> u64 {
+        self.reads.load(Ordering::Relaxed)
+    }
+
+    /// Sources this process converted to the units V8 reads, kept or not.
+    #[must_use]
+    pub fn conversions(&self) -> u64 {
+        self.conversions.load(Ordering::Relaxed)
+    }
+
+    /// Strings alive now that read a kept source.
+    #[must_use]
+    pub fn reading(&self) -> usize {
+        lock(&self.list)
+            .kept
+            .iter()
+            .map(|kept| kept.units.references().saturating_sub(kept.held))
+            .sum()
+    }
+}
+
+#[cfg(test)]
+#[allow(clippy::panic, reason = "a test fails by panicking")]
+mod tests {
+    use std::sync::Arc;
+
+    use super::{MAX_SOURCES, Sources, Units};
+    use crate::control::JsText;
+    use crate::process::code_cache::{CodeCache, Key};
+
+    // A script's key once the code cache has seen it twice.
+    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)
+            .key()
+            .cloned()
+            .unwrap_or_else(|| panic!("a second sighting has a key"))
+    }
+
+    fn script(seed: u8) -> JsText {
+        JsText::Latin1(vec![seed; 2 << 20])
+    }
+
+    fn one_byte(units: Option<Units>) -> Arc<[u8]> {
+        match units {
+            Some(Units::OneByte(bytes)) => bytes,
+            _ => panic!("one byte a unit"),
+        }
+    }
+
+    fn two_byte(units: Option<Units>) -> Arc<[u16]> {
+        match units {
+            Some(Units::TwoByte(units)) => units,
+            _ => panic!("two bytes a unit"),
+        }
+    }
+
+    #[test]
+    fn keeps_a_source_in_the_form_v8_stores_a_string_of_it() {
+        assert_eq!(
+            *one_byte(Units::of(&JsText::Latin1(vec![b'a', 0xE9]))),
+            [b'a', 0xE9]
+        );
+        assert_eq!(*one_byte(Units::of(&JsText::from("a\0b"))), *b"a\0b");
+        assert_eq!(
+            *two_byte(Units::of(&JsText::from("\u{FEFF}a"))),
+            [0xFEFF, 0x61]
+        );
+        assert_eq!(
+            *one_byte(Units::of(&JsText::from("caf\u{E9}\u{FF}"))),
+            *b"caf\xE9\xFF"
+        );
+        assert_eq!(
+            *two_byte(Units::of(&JsText::from("a\u{100}\u{1F600}"))),
+            [0x61, 0x100, 0xD83D, 0xDE00]
+        );
+        assert_eq!(
+            *one_byte(Units::of(&JsText::Utf16(vec![0x61, 0xE9]))),
+            [0x61, 0xE9]
+        );
+        assert_eq!(
+            *two_byte(Units::of(&JsText::Utf16(vec![0xD800, 0x61, 0xDC00]))),
+            [0xD800, 0x61, 0xDC00]
+        );
+        assert!(Units::of(&JsText::Utf8(vec![b'a', 0xFF])).is_none());
+    }
+
+    #[test]
+    fn every_context_compiling_a_script_reads_one_copy() {
+        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));
+        assert!(Arc::ptr_eq(&first, &second));
+        assert_eq!(sources.made(), 1);
+        assert_eq!(sources.reading(), 2);
+        drop((first, second));
+        assert_eq!(sources.reading(), 0);
+    }
+
+    fn same(first: Option<&Units>, second: Option<&Units>) -> bool {
+        match (first, second) {
+            (Some(Units::OneByte(first)), Some(Units::OneByte(second))) => {
+                Arc::ptr_eq(first, second)
+            }
+            (Some(Units::TwoByte(first)), Some(Units::TwoByte(second))) => {
+                Arc::ptr_eq(first, second)
+            }
+            _ => false,
+        }
+    }
+
+    #[test]
+    fn a_source_still_read_is_kept_and_an_unread_one_makes_room() {
+        let sources = Sources::default();
+        let count = u8::try_from(MAX_SOURCES).unwrap_or(u8::MAX);
+        let texts: Vec<JsText> = (10..10 + count).map(script).collect();
+        let keys: Vec<Key> = texts.iter().map(key).collect();
+        let mut read: Vec<Option<Units>> = texts
+            .iter()
+            .zip(&keys)
+            .map(|(text, key)| sources.units(key, text))
+            .collect();
+        let extra = script(100);
+        let extra_key = key(&extra);
+        assert!(sources.units(&extra_key, &extra).is_none());
+        drop(read.remove(3));
+        drop(read.remove(0));
+        drop(sources.units(&keys[3], &texts[3]));
+        // Of the two unread, the least recently used makes room.
+        assert!(sources.units(&extra_key, &extra).is_some());
+        let made = sources.made();
+        assert_eq!(made, u64::from(count) + 1);
+        drop(sources.units(&keys[3], &texts[3]));
+        assert_eq!(sources.made(), made);
+        drop(sources.units(&keys[0], &texts[0]));
+        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(),
+                held.as_ref()
+            ));
+        }
+        assert_eq!(sources.made(), made + 1);
+    }
+
+    #[test]
+    fn a_full_list_converts_nothing() {
+        let sources = Sources::default();
+        let count = u8::try_from(MAX_SOURCES).unwrap_or(u8::MAX);
+        let read: Vec<Option<Units>> = (40..40 + count)
+            .map(|seed| {
+                let text = script(seed);
+                sources.units(&key(&text), &text)
+            })
+            .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_eq!(sources.conversions(), converted);
+        drop(read);
+        assert!(sources.units(&extra_key, &extra).is_some());
+        assert_eq!(sources.conversions(), converted + 1);
+    }
+
+    // Under a 5 MiB bound with 2 MiB still read, 4 MiB of Latin-1 cannot fit
+    // and is never converted; 2 MiB of UTF-8 may fit, until converting it
+    // shows one astral character makes it 4.
+    #[test]
+    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);
+        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_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_eq!(sources.conversions(), 2);
+        drop(still_read);
+        assert!(two_byte(sources.units(&astral_key, &astral)).len() > 2 << 20);
+        assert_eq!((sources.conversions(), sources.made()), (3, 2));
+    }
+
+    #[test]
+    fn invalid_utf8_is_tried_once() {
+        let sources = Sources::default();
+        let mut invalid = vec![b'a'; 2 << 20];
+        invalid.push(0xFF);
+        let invalid = JsText::Utf8(invalid);
+        let invalid_key = key(&invalid);
+        for _ in 0..3 {
+            assert!(sources.units(&invalid_key, &invalid).is_none());
+        }
+        assert_eq!((sources.conversions(), sources.made()), (1, 0));
+    }
+
+    #[test]
+    fn a_child_reads_its_parents_copy_and_never_frees_it() {
+        let parent: &'static Sources = Box::leak(Box::default());
+        let text = script(2);
+        let key = key(&text);
+        let shared = parent.units(&key, &text);
+        let child = parent.inherited();
+        let in_child = child.units(&key, &text);
+        assert!(same(shared.as_ref(), in_child.as_ref()));
+        assert_eq!(child.reading(), 2);
+        let copy = Arc::downgrade(&one_byte(shared));
+        drop(in_child);
+        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));
+        }
+        assert_eq!(copy.strong_count(), 1);
+        let again = one_byte(child.units(&key, &text));
+        assert!(
+            !copy
+                .upgrade()
+                .is_some_and(|copy| Arc::ptr_eq(&copy, &again))
+        );
+        let from_parent = one_byte(parent.units(&key, &text));
+        assert!(
+            copy.upgrade()
+                .is_some_and(|copy| Arc::ptr_eq(&copy, &from_parent))
+        );
+    }
+
+    // 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]
+    fn a_child_inheriting_a_full_list_converts_nothing() {
+        let parent = Sources::default();
+        let count = u8::try_from(MAX_SOURCES).unwrap_or(u8::MAX);
+        let read: Vec<Option<Units>> = (60..60 + count)
+            .map(|seed| {
+                let text = script(seed);
+                parent.units(&key(&text), &text)
+            })
+            .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_eq!(child.conversions(), 0);
+        drop(read);
+    }
+
+    #[test]
+    fn a_child_forked_while_the_sources_were_held_starts_without_them() {
+        let parent = Sources::default();
+        let text = script(3);
+        let key = key(&text);
+        let shared = one_byte(parent.units(&key, &text));
+        let held = parent.list.lock();
+        let child = parent.inherited();
+        drop(held);
+        assert!(!Arc::ptr_eq(&shared, &one_byte(child.units(&key, &text))));
+        assert_eq!(child.made(), 1);
+    }
+}

data/crates/mini_racer_engine/src/process.rs

@@ -1,6 +1,7 @@
 pub mod code_cache;
 pub mod fork;
 pub mod platform;
+pub mod sources;
 pub(crate) mod tasks;
 pub(crate) mod watchdog;
 pub(crate) mod workers;

data/crates/mini_racer_engine/src/runner.rs

@@ -16,7 +16,7 @@ use crate::control::{
     CallRequest, CallbackReply, ControlBlock, Depth, IsolateTerminator, JsText, Request,
 };
 use crate::fast_calls::{self, Hoisted, Shape};
-use crate::process::code_cache::{Building, Plan};
+use crate::process::code_cache::{Building, Key, Plan};
 use crate::process::fork::Generation;
 use crate::process::platform::{self, Mode};
 use crate::process::watchdog;
@@ -775,10 +775,12 @@ fn evaluate(
             .code_cache()
             .plan(filename, source, runtime.snapshot)
     } else {
-        Plan::Compile
+        Plan::Compile(None)
     };
     let too_large = || EngineError::Internal("source too large".to_owned());
-    let source = string(tc, source).ok_or_else(too_large)?;
+    let source = shared_source(tc, runtime, plan.key(), source)
+        .or_else(|| string(tc, source))
+        .ok_or_else(too_large)?;
     let name = string(tc, filename).ok_or_else(too_large)?;
     let origin = serialize::origin(tc, name.into());
     let (script, make) = compile(tc, runtime, source, &origin, plan);
@@ -794,6 +796,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.
+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() {
+        return None;
+    }
+    let sources = runtime.generation.sources();
+    let string = sys::external_string(scope, &sources.units(key?, source)?)?;
+    sources.read();
+    Some(string)
+}
+
 fn settle<'s>(
     tc: &mut Tc<'s, '_, '_, '_>,
     runtime: &Runtime,
@@ -1045,7 +1066,7 @@ fn compile<'s>(
     plan: Plan,
 ) -> (Option<v8::Local<'s, v8::Script>>, Option<Building>) {
     let (entry, key) = match plan {
-        Plan::Compile => return (v8::Script::compile(scope, source, Some(origin)), None),
+        Plan::Compile(_) => return (v8::Script::compile(scope, source, Some(origin)), None),
         Plan::Make(building) => {
             return (
                 v8::Script::compile(scope, source, Some(origin)),

data/crates/mini_racer_engine/src/sys.rs

@@ -1,7 +1,10 @@
-use std::ffi::c_void;
+use std::ffi::{c_char, c_void};
 use std::ptr::NonNull;
+use std::sync::Arc;
 use std::time::Duration;
 
+use crate::process::sources::Units;
+
 // The prebuilt V8 archive marks every heap mapping MADV_DONTFORK, so a forked
 // child would lose the isolate's memory. `-Wl,--wrap=madvise` (build.rs) routes
 // V8's calls here; this drops that one advice and forwards the rest unchanged.
@@ -47,6 +50,77 @@ pub fn startup_data(blob: &crate::SnapshotBlob) -> v8::StartupData {
     v8::StartupData::from(bytes)
 }
 
+/// A string V8 reads from `units` in place. It holds a reference to them,
+/// which V8 hands back through `release_one_byte` or `release_two_byte` once,
+/// on whatever thread it runs that on: when the string dies in a collection
+/// or its isolate's teardown, or when V8 internalizes it while it lives and
+/// gives the units to the internalized string, to release when that one dies,
+/// or releases them at once if that string has its own (`MigrateExternalString`
+/// in V8's `string.cc`). `None` past V8's length limit.
+pub fn external_string<'s>(
+    scope: &v8::PinScope<'s, '_>,
+    units: &Units,
+) -> Option<v8::Local<'s, v8::String>> {
+    // V8 refuses a resource past its limit without disposing of it, which
+    // would keep the reference for good, so it never gets one.
+    match units {
+        Units::OneByte(bytes) if bytes.len() <= v8::String::MAX_LENGTH => {
+            let data = Arc::into_raw(Arc::clone(bytes));
+            // SAFETY: the bytes stay where they are, unchanged, while the
+            // reference made here lives; V8 only reads them, and hands the
+            // reference back through `release_one_byte`, with this pointer and
+            // length, once the string dies.
+            unsafe {
+                v8::String::new_external_onebyte_raw(
+                    scope,
+                    data.cast::<c_char>().cast_mut(),
+                    bytes.len(),
+                    release_one_byte,
+                )
+            }
+        }
+        Units::TwoByte(units) if units.len() <= v8::String::MAX_LENGTH => {
+            let data = Arc::into_raw(Arc::clone(units));
+            // SAFETY: as for one byte a unit, through `release_two_byte`.
+            unsafe {
+                v8::String::new_external_twobyte_raw(
+                    scope,
+                    data.cast::<u16>().cast_mut(),
+                    units.len(),
+                    release_two_byte,
+                )
+            }
+        }
+        Units::OneByte(_) | Units::TwoByte(_) => None,
+    }
+}
+
+// Each runs once per string `external_string` made, and only releases its
+// reference: the list in `process::sources` holds another for as long as any
+// string reads them, so the units are never freed here.
+unsafe extern "C" fn release_one_byte(data: *mut c_char, length: usize) {
+    let released = std::panic::catch_unwind(|| {
+        let bytes = std::ptr::slice_from_raw_parts(data.cast::<u8>().cast_const(), length);
+        // SAFETY: V8 passes back the pointer and length `external_string`
+        // gave it, once, so this releases the one reference it made.
+        unsafe { Arc::decrement_strong_count(bytes) };
+    });
+    if released.is_err() {
+        std::process::abort();
+    }
+}
+
+unsafe extern "C" fn release_two_byte(data: *mut u16, length: usize) {
+    let released = std::panic::catch_unwind(|| {
+        let units = std::ptr::slice_from_raw_parts(data.cast_const(), length);
+        // SAFETY: as in `release_one_byte`.
+        unsafe { Arc::decrement_strong_count(units) };
+    });
+    if released.is_err() {
+        std::process::abort();
+    }
+}
+
 /// The address V8 names `isolate` by when it posts the isolate a task.
 #[must_use]
 pub fn isolate_key(isolate: &v8::Isolate) -> usize {

data/lib/mini_racer_rs/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mini_racer_rs
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.0.2
 platform: ruby
 authors:
 - Andy Aragon
@@ -54,6 +54,7 @@ files:
 - crates/mini_racer_engine/src/process/code_cache.rs
 - crates/mini_racer_engine/src/process/fork.rs
 - crates/mini_racer_engine/src/process/platform.rs
+- crates/mini_racer_engine/src/process/sources.rs
 - crates/mini_racer_engine/src/process/tasks.rs
 - crates/mini_racer_engine/src/process/watchdog.rs
 - crates/mini_racer_engine/src/process/workers.rs