mini_racer_rs 1.0.0

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

@@ -0,0 +1,261 @@
+use std::cell::RefCell;
+use std::sync::atomic::{AtomicBool, AtomicU64, AtomicUsize, Ordering};
+use std::sync::{Arc, Mutex, MutexGuard, OnceLock, Weak};
+use std::time::{Duration, Instant};
+
+use mini_racer_sync::{ForkGate, Phase, lock};
+
+use crate::control::ControlBlock;
+use crate::process::code_cache::CodeCache;
+use crate::process::tasks::TaskRegistry;
+use crate::process::watchdog::Watchdog;
+use crate::process::workers::Workers;
+
+// Long enough for any runner to answer and go idle, short enough that a fork
+// that cannot be quiesced is merely slow.
+const QUIESCE: Duration = Duration::from_millis(500);
+const POLL: Duration = Duration::from_micros(200);
+// A runner still running after this is interrupted to park in JavaScript.
+const INTERRUPT_AFTER: Duration = Duration::from_millis(50);
+// How long the worker threads get to finish the tasks they are running.
+const PAUSE: Duration = Duration::from_millis(100);
+
+// Forks since the engine's fork handlers were registered, counted by the child
+// handler. A process is told apart from its ancestors by this, never by pid,
+// which a descendant may get again once an ancestor has exited.
+static EPOCH: AtomicU64 = AtomicU64::new(0);
+
+/// Which process of a fork lineage this is.
+#[must_use]
+pub fn epoch() -> u64 {
+    EPOCH.load(Ordering::SeqCst)
+}
+
+// One process of a fork lineage. A child makes its own on first use and never
+// locks or frees what it inherited, which a thread that is gone may hold.
+pub struct Generation {
+    epoch: u64,
+    // Whether every fork that led to this process found its runners idle: a
+    // runner caught mid-change by any of them may have left V8's process-wide
+    // state locked for every process after it. True for the first process.
+    quiesced: bool,
+    prepared: AtomicBool,
+    gate: ForkGate,
+    // Held from the prepare handler to the parent handler, so forks from
+    // threads outside Ruby take turns with Ruby's.
+    forking: Mutex<()>,
+    blocks: Mutex<Vec<Weak<ControlBlock>>>,
+    // Per process, as a worker thread posting to it may have held its lock at
+    // the fork.
+    tasks: TaskRegistry,
+    watchdog: Mutex<Option<Arc<Watchdog>>>,
+    workers: Workers,
+    code_cache: CodeCache,
+    next: OnceLock<Box<Self>>,
+}
+
+static ROOT: OnceLock<Generation> = OnceLock::new();
+
+impl Generation {
+    fn new(epoch: u64, quiesced: bool, code_cache: CodeCache) -> Self {
+        Self {
+            epoch,
+            quiesced,
+            prepared: AtomicBool::new(false),
+            gate: ForkGate::default(),
+            forking: Mutex::new(()),
+            blocks: Mutex::new(Vec::new()),
+            tasks: TaskRegistry::default(),
+            watchdog: Mutex::new(None),
+            workers: Workers::default(),
+            code_cache,
+            next: OnceLock::new(),
+        }
+    }
+
+    pub const fn quiesced(&self) -> bool {
+        self.quiesced
+    }
+
+    pub(crate) const fn tasks(&self) -> &TaskRegistry {
+        &self.tasks
+    }
+
+    pub(crate) const fn watchdog(&self) -> &Mutex<Option<Arc<Watchdog>>> {
+        &self.watchdog
+    }
+
+    pub(crate) const fn workers(&self) -> &Workers {
+        &self.workers
+    }
+
+    #[must_use]
+    pub const fn code_cache(&self) -> &CodeCache {
+        &self.code_cache
+    }
+
+    pub fn register(&self, block: &Arc<ControlBlock>) {
+        let mut blocks = lock(&self.blocks);
+        blocks.retain(|block| block.strong_count() > 0);
+        blocks.push(Arc::downgrade(block));
+    }
+
+    /// Called by a runner about to use its isolate: once a fork began, it
+    /// waits without the isolate until the fork is over.
+    pub fn resume(&self, block: &ControlBlock) {
+        self.gate.resume(&block.phase);
+    }
+
+    /// Waits out a pending fork; a runner interrupted in JavaScript holds its
+    /// isolate meanwhile, and the child leaves that context alone.
+    pub fn pause(&self, block: &ControlBlock) {
+        self.gate.pause(&block.phase);
+    }
+}
+
+pub fn current() -> &'static Generation {
+    let epoch = epoch();
+    let mut generation = ROOT.get_or_init(|| Generation::new(epoch, true, CodeCache::default()));
+    while generation.epoch != epoch {
+        let quiesced = generation.quiesced && generation.prepared.load(Ordering::SeqCst);
+        let next = generation.epoch.saturating_add(1);
+        let parent = generation;
+        generation = parent.next.get_or_init(|| {
+            Box::new(Generation::new(
+                next,
+                quiesced,
+                parent.code_cache.inherited(),
+            ))
+        });
+    }
+    generation
+}
+
+// Forks from Ruby under way, counted so nested `_fork` hooks and Ruby threads
+// that move between native threads keep it right. Forks while it is zero run
+// no Ruby in the child (spawn, system and backticks on macOS) and leave the
+// runners be.
+static INTENDED: AtomicUsize = AtomicUsize::new(0);
+// Whether a fork from Ruby was under way when the latest fork was prepared.
+// Its child starts its own count from this: only the forking thread carries on
+// there, inside the one `_fork` hook it forked from, if any.
+static FORK_INTENDED: AtomicBool = AtomicBool::new(false);
+
+/// Marks the forks made until the matching `intend(false)` as ones whose child
+/// runs Ruby and may use the contexts it inherits.
+pub fn intend(forking: bool) {
+    if forking {
+        INTENDED.fetch_add(1, Ordering::SeqCst);
+    } else {
+        let mut count = INTENDED.load(Ordering::SeqCst);
+        while count > 0 {
+            match INTENDED.compare_exchange_weak(
+                count,
+                count.saturating_sub(1),
+                Ordering::SeqCst,
+                Ordering::SeqCst,
+            ) {
+                Ok(_) => break,
+                Err(now) => count = now,
+            }
+        }
+    }
+}
+
+// The fork this thread is preparing, so its parent handler alone reopens the
+// gate. A child inherits its forking thread's turn, which belongs to the
+// parent's generation.
+type Turn = (&'static Generation, MutexGuard<'static, ()>);
+
+// A turn taken in an ancestor process: its lock is left held, as the child
+// releases nothing it inherited.
+const fn abandon(turn: Turn) {
+    #[expect(
+        clippy::mem_forget,
+        reason = "the lock belongs to an ancestor's generation"
+    )]
+    std::mem::forget(turn);
+}
+
+thread_local! {
+    static FORKING: RefCell<Option<Turn>> = const { RefCell::new(None) };
+}
+
+// pthread_atfork's prepare handler, on the forking thread inside fork() and
+// after every Ruby `_fork` hook, so no Ruby code runs while runners are held.
+// It waits until every runner is idle or parked, then pauses the worker
+// threads until the parent handler and waits for the tasks they are running,
+// so the child finds no isolate mid-change. No runner needs Ruby to get
+// there: one waiting on a callback already counts as parked. Past the bounds
+// the fork goes ahead anyway.
+pub(crate) fn prepare() {
+    let intended = INTENDED.load(Ordering::SeqCst) != 0;
+    FORK_INTENDED.store(intended, Ordering::SeqCst);
+    if !intended {
+        return;
+    }
+    let generation = current();
+    let turn = lock(&generation.forking);
+    if let Some(stale) = FORKING.with(|forking| forking.borrow_mut().replace((generation, turn))) {
+        abandon(stale);
+    }
+    // Begun before the registry is read: a runner registered later sees it.
+    generation.gate.begin();
+    let blocks: Vec<Arc<ControlBlock>> = lock(&generation.blocks)
+        .iter()
+        .filter_map(Weak::upgrade)
+        .collect();
+    let started = Instant::now();
+    let mut interrupted = false;
+    let quiesced = loop {
+        let running: Vec<&Arc<ControlBlock>> = blocks
+            .iter()
+            .filter(|block| block.phase.get() == Phase::Running)
+            .collect();
+        if running.is_empty() {
+            break true;
+        }
+        let waited = started.elapsed();
+        if waited >= QUIESCE {
+            break false;
+        }
+        if !interrupted && waited >= INTERRUPT_AFTER {
+            interrupted = true;
+            for block in running {
+                block.interrupt_for_fork();
+            }
+        }
+        std::thread::sleep(POLL);
+    };
+    let paused = generation.workers.pause(PAUSE);
+    generation
+        .prepared
+        .store(quiesced && paused, Ordering::SeqCst);
+}
+
+// pthread_atfork's parent handler, whether or not the fork succeeded.
+pub(crate) fn parent() {
+    let Some((generation, turn)) = FORKING.with(|forking| forking.borrow_mut().take()) else {
+        return;
+    };
+    if generation.epoch != epoch() {
+        return abandon((generation, turn));
+    }
+    // Cleared before the gate opens, so no fork from another thread copies
+    // a prepared flag while runners move.
+    generation.prepared.store(false, Ordering::SeqCst);
+    generation.workers.resume();
+    generation.gate.end();
+    drop(turn);
+}
+
+// pthread_atfork's child handler: atomics only, which is all a child may touch
+// before it execs or returns to Ruby. Everything else the child reads lazily
+// from what it inherited.
+pub(crate) fn child() {
+    EPOCH.fetch_add(1, Ordering::SeqCst);
+    INTENDED.store(
+        usize::from(FORK_INTENDED.load(Ordering::SeqCst)),
+        Ordering::SeqCst,
+    );
+}

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

@@ -0,0 +1,194 @@
+use std::sync::atomic::{AtomicU8, Ordering};
+use std::sync::{Mutex, MutexGuard, PoisonError};
+
+use crate::FlagError;
+
+const MAX_FLAG_BYTES: usize = 256;
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Mode {
+    MultiThreaded,
+    SingleThreaded,
+}
+
+struct Flags {
+    list: Vec<String>,
+    frozen: bool,
+    mode: Mode,
+}
+
+static FLAGS: Mutex<Flags> = Mutex::new(Flags {
+    list: Vec::new(),
+    frozen: false,
+    mode: Mode::MultiThreaded,
+});
+
+fn flags() -> MutexGuard<'static, Flags> {
+    FLAGS.lock().unwrap_or_else(PoisonError::into_inner)
+}
+
+struct Normalized {
+    flag: String,
+    mode: Option<Mode>,
+}
+
+fn normalize(name: &[u8], value: Option<&[u8]>) -> Result<Normalized, FlagError> {
+    if name.contains(&0) || value.is_some_and(|v| v.contains(&0)) {
+        return Err(FlagError::Nul);
+    }
+    let name = name.strip_prefix(b"--").unwrap_or(name);
+    let mut flag = Vec::with_capacity(name.len() + value.map_or(0, <[u8]>::len) + 3);
+    flag.extend_from_slice(b"--");
+    flag.extend_from_slice(name);
+    if let Some(value) = value {
+        flag.push(b'=');
+        flag.extend_from_slice(value);
+    }
+    if flag.len() >= MAX_FLAG_BYTES {
+        return Err(FlagError::TooLong);
+    }
+    let squashed: Vec<u8> = flag
+        .iter()
+        .copied()
+        .filter(|b| !matches!(b, b'-' | b'_'))
+        .collect();
+    let mode = match squashed.as_slice() {
+        b"singlethreaded" => Some(Mode::SingleThreaded),
+        b"nosinglethreaded" => Some(Mode::MultiThreaded),
+        _ => None,
+    };
+    Ok(Normalized {
+        flag: String::from_utf8_lossy(&flag).into_owned(),
+        mode,
+    })
+}
+
+pub fn push_flag(name: &[u8], value: Option<&[u8]>) -> Result<(), FlagError> {
+    let normalized = normalize(name, value)?;
+    let mut flags = flags();
+    if flags.frozen {
+        return Err(FlagError::AlreadyInitialized);
+    }
+    if let Some(mode) = normalized.mode {
+        flags.mode = mode;
+    }
+    flags.list.push(normalized.flag);
+    drop(flags);
+    Ok(())
+}
+
+// The mode once frozen, readable without the flags lock, which runner threads
+// must not take: a fork that does not wait for them could leave it held.
+static FROZEN_MODE: AtomicU8 = AtomicU8::new(0);
+
+#[must_use]
+pub fn mode() -> Mode {
+    match FROZEN_MODE.load(Ordering::Acquire) {
+        1 => Mode::MultiThreaded,
+        2 => Mode::SingleThreaded,
+        _ => flags().mode,
+    }
+}
+
+#[must_use]
+pub fn is_initialized() -> bool {
+    flags().frozen
+}
+
+// The last --stack_size (or --stack-size) value, in KiB, as V8 parses it.
+#[must_use]
+pub fn stack_size_kb() -> Option<usize> {
+    flags().list.iter().rev().find_map(|flag| {
+        let value = flag
+            .strip_prefix("--stack_size=")
+            .or_else(|| flag.strip_prefix("--stack-size="))?;
+        value.parse().ok()
+    })
+}
+
+pub(crate) fn freeze() -> Vec<String> {
+    let mut flags = flags();
+    flags.frozen = true;
+    let frozen = match flags.mode {
+        Mode::MultiThreaded => 1,
+        Mode::SingleThreaded => 2,
+    };
+    FROZEN_MODE.store(frozen, Ordering::Release);
+    flags.list.clone()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn flag(name: &[u8], value: Option<&[u8]>) -> Result<String, FlagError> {
+        normalize(name, value).map(|n| n.flag)
+    }
+
+    #[test]
+    fn normalizes_like_upstream() {
+        assert_eq!(flag(b"use_strict", None).as_deref(), Ok("--use_strict"));
+        assert_eq!(flag(b"--use_strict", None).as_deref(), Ok("--use_strict"));
+        assert_eq!(
+            flag(b"stack_size", Some(b"512")).as_deref(),
+            Ok("--stack_size=512")
+        );
+        assert_eq!(flag(b"bad\0", None), Err(FlagError::Nul));
+        assert_eq!(flag(b"name", Some(b"v\0")), Err(FlagError::Nul));
+        assert!(flag(&[b'a'; 253], None).is_ok());
+        assert_eq!(flag(&[b'a'; 254], None), Err(FlagError::TooLong));
+        assert!(flag(&[b'a'; 250], Some(b"xx")).is_ok());
+        assert_eq!(flag(&[b'a'; 251], Some(b"xx")), Err(FlagError::TooLong));
+    }
+
+    #[test]
+    fn detects_single_threaded_spellings() {
+        for name in [
+            &b"single_threaded"[..],
+            b"--single-threaded",
+            b"singlethreaded",
+        ] {
+            assert_eq!(
+                normalize(name, None).map(|n| n.mode),
+                Ok(Some(Mode::SingleThreaded))
+            );
+        }
+        for name in [
+            &b"no_single_threaded"[..],
+            b"--no-single-threaded",
+            b"nosingle_threaded",
+        ] {
+            assert_eq!(
+                normalize(name, None).map(|n| n.mode),
+                Ok(Some(Mode::MultiThreaded))
+            );
+        }
+        assert_eq!(normalize(b"use_strict", None).map(|n| n.mode), Ok(None));
+    }
+
+    // Flags freeze at the first initialization in a process, so this runs in
+    // a process of its own even where other tests share one.
+    #[test]
+    fn rejects_flags_after_initialization() {
+        const ALONE: &str = "MINI_RACER_RS_TEST_ALONE";
+        if std::env::var_os(ALONE).is_none() {
+            let status = std::process::Command::new(std::env::current_exe().expect("test binary"))
+                .args([
+                    "process::platform::tests::rejects_flags_after_initialization",
+                    "--exact",
+                ])
+                .env(ALONE, "1")
+                .status()
+                .expect("run the test binary");
+            assert!(status.success(), "{status}");
+            return;
+        }
+        assert_eq!(push_flag(b"use_strict", None), Ok(()));
+        assert_eq!(freeze(), vec!["--use_strict".to_owned()]);
+        assert!(is_initialized());
+        assert_eq!(
+            push_flag(b"expose_gc", None),
+            Err(FlagError::AlreadyInitialized)
+        );
+    }
+}

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

@@ -0,0 +1,96 @@
+use std::collections::HashMap;
+use std::ffi::c_void;
+use std::panic::{AssertUnwindSafe, catch_unwind};
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::sync::{Arc, Mutex};
+use std::time::Duration;
+
+use mini_racer_sync::{TaskQueue, lock};
+
+use crate::process::fork;
+
+pub type Tasks = TaskQueue<v8::Task>;
+
+/// The queues V8's foreground tasks go to in one process, by the address V8
+/// names each isolate by.
+#[derive(Default)]
+pub struct TaskRegistry {
+    queues: Mutex<HashMap<usize, Arc<Tasks>>>,
+}
+
+impl TaskRegistry {
+    /// Sends the isolate's tasks to `tasks`. An entry a disposed isolate at the
+    /// same address left behind is replaced.
+    pub fn register(&self, isolate: usize, tasks: &Arc<Tasks>) {
+        lock(&self.queues).insert(isolate, Arc::clone(tasks));
+    }
+
+    /// Stops sending tasks to `tasks`, unless a newer isolate at the same
+    /// address has taken the entry over.
+    pub fn unregister(&self, isolate: usize, tasks: &Arc<Tasks>) {
+        let mut queues = lock(&self.queues);
+        if queues
+            .get(&isolate)
+            .is_some_and(|queued| Arc::ptr_eq(queued, tasks))
+        {
+            queues.remove(&isolate);
+        }
+    }
+
+    fn find(&self, isolate: usize) -> Option<Arc<Tasks>> {
+        lock(&self.queues).get(&isolate).cloned()
+    }
+}
+
+/// Takes V8's foreground tasks off its platform, so a runner can sleep until
+/// one is due and a termination can wake it.
+pub struct Foreground;
+
+impl v8::PlatformImpl for Foreground {
+    fn post_task(&self, isolate: *mut c_void, task: v8::Task) {
+        post(isolate, task, true, 0.0);
+    }
+
+    fn post_non_nestable_task(&self, isolate: *mut c_void, task: v8::Task) {
+        post(isolate, task, false, 0.0);
+    }
+
+    fn post_delayed_task(&self, isolate: *mut c_void, task: v8::Task, delay: f64) {
+        post(isolate, task, true, delay);
+    }
+
+    fn post_non_nestable_delayed_task(&self, isolate: *mut c_void, task: v8::Task, delay: f64) {
+        post(isolate, task, false, delay);
+    }
+
+    // The platform is built without idle task support, so V8 posts none.
+    fn post_idle_task(&self, _isolate: *mut c_void, task: v8::IdleTask) {
+        drop(task);
+    }
+}
+
+static UNSERVED: AtomicU64 = AtomicU64::new(0);
+
+pub fn unserved() -> u64 {
+    UNSERVED.load(Ordering::Relaxed)
+}
+
+// Called from any thread. A task for an isolate no runner serves (one being
+// built into a snapshot, made or torn down) is dropped where it was posted,
+// as nothing would ever run it.
+fn post(isolate: *mut c_void, task: v8::Task, nestable: bool, delay: f64) {
+    let posted = catch_unwind(AssertUnwindSafe(|| {
+        let delay = Duration::try_from_secs_f64(delay).unwrap_or(Duration::MAX);
+        let Some(tasks) = fork::current().tasks().find(isolate.addr()) else {
+            UNSERVED.fetch_add(1, Ordering::Relaxed);
+            drop(task);
+            return;
+        };
+        if let Err(refused) = tasks.post(task, nestable, delay) {
+            drop(refused);
+        }
+    }));
+    if posted.is_err() {
+        std::process::abort();
+    }
+}