mini_racer_rs 1.0.0

data/crates/mini_racer_sync/src/fork.rs

@@ -0,0 +1,116 @@
+use crate::lock::{lock, wait};
+use crate::primitives::{AtomicBool, AtomicU8, Condvar, Mutex, Ordering};
+
+/// Where a runner is, as a fork sees it. Only `Running` keeps a fork waiting.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+#[repr(u8)]
+pub enum Phase {
+    Running = 0,
+    /// Idle, with its isolate in the control block and no lock held.
+    Deposited = 1,
+    /// Holding its isolate with no V8 call under way: waiting for a request,
+    /// inside a callback waiting for Ruby, or awaiting a promise until a task
+    /// is due.
+    Parked = 2,
+    /// Woken while a fork was pending, before touching its isolate, or
+    /// interrupted in JavaScript to wait the fork out.
+    ParkedForFork = 3,
+    Exited = 4,
+}
+
+pub struct RunnerPhase(AtomicU8);
+
+impl Default for RunnerPhase {
+    fn default() -> Self {
+        Self(AtomicU8::new(Phase::Running as u8))
+    }
+}
+
+// Both sides of the gate's handshake are read-modify-writes of the phase, so
+// whichever comes second in its order sees the other: ordering that rests on
+// a store and a load alone is beyond what loom checks.
+impl RunnerPhase {
+    pub fn set(&self, phase: Phase) {
+        self.0.swap(phase as u8, Ordering::SeqCst);
+    }
+
+    /// For a forker or a forked child; a runner knows its own phase.
+    pub fn get(&self) -> Phase {
+        match self.0.fetch_add(0, Ordering::SeqCst) {
+            1 => Phase::Deposited,
+            2 => Phase::Parked,
+            3 => Phase::ParkedForFork,
+            4 => Phase::Exited,
+            _ => Phase::Running,
+        }
+    }
+}
+
+/// Holds runners back from their isolates while a fork is pending.
+///
+/// A runner publishes `Running` and then reads `begun`, and `begin` sets
+/// `begun` before the forker reads any phase, so either the runner sees the
+/// fork and waits or the forker sees it `Running` and waits for it. Every runner resumes before every request, so the
+/// common case takes no lock: one lock shared by all of a process's runners
+/// cost three quarters of the call rate of four busy threads.
+pub struct ForkGate {
+    begun: AtomicBool,
+    pending: Mutex<bool>,
+    released: Condvar,
+}
+
+impl Default for ForkGate {
+    fn default() -> Self {
+        Self {
+            begun: AtomicBool::new(false),
+            pending: Mutex::new(false),
+            released: Condvar::new(),
+        }
+    }
+}
+
+impl ForkGate {
+    pub fn begin(&self) {
+        let mut pending = lock(&self.pending);
+        *pending = true;
+        self.begun.store(true, Ordering::SeqCst);
+        drop(pending);
+    }
+
+    pub fn end(&self) {
+        let mut pending = lock(&self.pending);
+        *pending = false;
+        self.begun.store(false, Ordering::SeqCst);
+        drop(pending);
+        self.released.notify_all();
+    }
+
+    pub fn resume(&self, phase: &RunnerPhase) {
+        phase.set(Phase::Running);
+        if !self.begun.load(Ordering::SeqCst) {
+            return;
+        }
+        let mut pending = lock(&self.pending);
+        while *pending {
+            phase.set(Phase::ParkedForFork);
+            pending = wait(&self.released, pending);
+        }
+        phase.set(Phase::Running);
+        drop(pending);
+    }
+
+    /// Waits out a pending fork as `ParkedForFork`, for a runner interrupted
+    /// in JavaScript, which keeps its isolate meanwhile.
+    pub fn pause(&self, phase: &RunnerPhase) {
+        let mut pending = lock(&self.pending);
+        if !*pending {
+            return;
+        }
+        phase.set(Phase::ParkedForFork);
+        while *pending {
+            pending = wait(&self.released, pending);
+        }
+        phase.set(Phase::Running);
+        drop(pending);
+    }
+}

data/crates/mini_racer_sync/src/lib.rs

@@ -0,0 +1,20 @@
+#![forbid(unsafe_code)]
+
+mod channel;
+mod fork;
+mod lock;
+mod parker;
+pub mod primitives;
+mod tasks;
+mod termination;
+mod workers;
+
+pub use channel::{Channel, ChannelError, Nesting, Notifier, Protocol, Side, ToRuby, ToV8};
+pub use fork::{ForkGate, Phase, RunnerPhase};
+pub use lock::{lock, wait, wait_timeout};
+pub use tasks::TaskQueue;
+pub use termination::{
+    DispatchId, DispatchKind, Halt, Inherited, Interrupt, RequestMark, TermCell, TermError,
+    TerminationCause, Terminator,
+};
+pub use workers::WorkerQueue;

data/crates/mini_racer_sync/src/lock.rs

@@ -0,0 +1,49 @@
+use std::sync::PoisonError;
+use std::time::Duration;
+
+use crate::primitives::{Condvar, Mutex, MutexGuard};
+
+// Recovering is the poison policy: every critical section in a protocol type is
+// a single write or take, so a panic cannot leave state half-updated, and
+// failing instead would strand the Ruby thread waiting on the other side.
+pub fn lock<T>(mutex: &Mutex<T>) -> MutexGuard<'_, T> {
+    mutex.lock().unwrap_or_else(PoisonError::into_inner)
+}
+
+pub fn wait<'a, T>(condvar: &Condvar, guard: MutexGuard<'a, T>) -> MutexGuard<'a, T> {
+    condvar.wait(guard).unwrap_or_else(PoisonError::into_inner)
+}
+
+pub fn wait_timeout<'a, T>(
+    condvar: &Condvar,
+    guard: MutexGuard<'a, T>,
+    timeout: Duration,
+) -> MutexGuard<'a, T> {
+    condvar
+        .wait_timeout(guard, timeout)
+        .map_or_else(|poisoned| poisoned.into_inner().0, |(guard, _)| guard)
+}
+
+#[cfg(test)]
+#[cfg(not(loom))]
+mod tests {
+    use super::*;
+
+    #[test]
+    #[expect(
+        clippy::significant_drop_tightening,
+        reason = "the guard must be held while the thread unwinds"
+    )]
+    fn a_panic_while_held_does_not_strand_later_lockers() {
+        let mutex = Mutex::new(0);
+        let unwound = std::panic::catch_unwind(|| {
+            let mut guard = lock(&mutex);
+            *guard = 1;
+            std::panic::resume_unwind(Box::new("unwinding while the lock is held"));
+        });
+
+        assert!(unwound.is_err());
+        assert!(mutex.is_poisoned());
+        assert_eq!(*lock(&mutex), 1);
+    }
+}

data/crates/mini_racer_sync/src/parker.rs

@@ -0,0 +1,44 @@
+use std::time::Duration;
+
+use crate::lock::{lock, wait, wait_timeout};
+use crate::primitives::{Condvar, Mutex};
+
+// A token parker: an unpark that arrives before the park is kept, so the waker
+// never has to know whether the waiter is asleep yet.
+pub struct Parker {
+    token: Mutex<bool>,
+    wake: Condvar,
+}
+
+impl Default for Parker {
+    fn default() -> Self {
+        Self {
+            token: Mutex::new(false),
+            wake: Condvar::new(),
+        }
+    }
+}
+
+impl Parker {
+    pub fn park(&self, timeout: Option<Duration>) {
+        let mut token = lock(&self.token);
+        match timeout {
+            None => {
+                while !*token {
+                    token = wait(&self.wake, token);
+                }
+            }
+            Some(timeout) => {
+                if !*token {
+                    token = wait_timeout(&self.wake, token, timeout);
+                }
+            }
+        }
+        *token = false;
+    }
+
+    pub fn unpark(&self) {
+        *lock(&self.token) = true;
+        self.wake.notify_one();
+    }
+}

data/crates/mini_racer_sync/src/primitives.rs

@@ -0,0 +1,10 @@
+// Protocol types name only these, so the loom models in tests/loom.rs check
+// the same code the engine runs.
+#[cfg(loom)]
+pub use loom::sync::atomic::{AtomicBool, AtomicU8, AtomicU64, Ordering};
+#[cfg(loom)]
+pub use loom::sync::{Condvar, Mutex, MutexGuard};
+#[cfg(not(loom))]
+pub use std::sync::atomic::{AtomicBool, AtomicU8, AtomicU64, Ordering};
+#[cfg(not(loom))]
+pub use std::sync::{Condvar, Mutex, MutexGuard};

data/crates/mini_racer_sync/src/tasks.rs

@@ -0,0 +1,345 @@
+use std::collections::VecDeque;
+use std::time::{Duration, Instant};
+
+use crate::lock::lock;
+use crate::parker::Parker;
+use crate::primitives::Mutex;
+
+// V8 asks for delays of seconds; anything longer is held to this, so every
+// deadline fits the clock.
+const LONGEST_DELAY: Duration = Duration::from_hours(365 * 24);
+
+struct Entry<T> {
+    task: T,
+    nestable: bool,
+}
+
+struct Delayed<T> {
+    due: Instant,
+    entry: Entry<T>,
+}
+
+pub struct Queue<T> {
+    ready: VecDeque<Entry<T>>,
+    // In posting order, which breaks ties between equal deadlines.
+    delayed: Vec<Delayed<T>>,
+    closed: bool,
+}
+
+impl<T> Default for Queue<T> {
+    fn default() -> Self {
+        Self {
+            ready: VecDeque::new(),
+            delayed: Vec::new(),
+            closed: false,
+        }
+    }
+}
+
+impl<T> Queue<T> {
+    pub fn push(&mut self, task: T, nestable: bool, delay: Duration) {
+        let entry = Entry { task, nestable };
+        if delay.is_zero() {
+            self.ready.push_back(entry);
+        } else {
+            let now = Instant::now();
+            let due = now.checked_add(delay.min(LONGEST_DELAY)).unwrap_or(now);
+            self.delayed.push(Delayed { due, entry });
+        }
+    }
+
+    pub fn pop(&mut self, now: Instant, nested: bool) -> Option<T> {
+        self.promote(now);
+        let index = self.position(nested)?;
+        self.ready.remove(index).map(|entry| entry.task)
+    }
+
+    // Delayed tasks that have come due join the ready ones, earliest first.
+    fn promote(&mut self, now: Instant) {
+        if !self.delayed.iter().any(|delayed| delayed.due <= now) {
+            return;
+        }
+        let (mut due, later): (Vec<_>, Vec<_>) = std::mem::take(&mut self.delayed)
+            .into_iter()
+            .partition(|delayed| delayed.due <= now);
+        due.sort_by_key(|delayed| delayed.due);
+        self.delayed = later;
+        self.ready
+            .extend(due.into_iter().map(|delayed| delayed.entry));
+    }
+
+    fn position(&self, nested: bool) -> Option<usize> {
+        self.ready
+            .iter()
+            .position(|entry| !nested || entry.nestable)
+    }
+
+    pub fn next_due(&self) -> Option<Instant> {
+        self.delayed.iter().map(|delayed| delayed.due).min()
+    }
+
+    fn drain(&mut self) -> Vec<T> {
+        let mut delayed = std::mem::take(&mut self.delayed);
+        delayed.sort_by_key(|delayed| delayed.due);
+        std::mem::take(&mut self.ready)
+            .into_iter()
+            .chain(delayed.into_iter().map(|delayed| delayed.entry))
+            .map(|entry| entry.task)
+            .collect()
+    }
+}
+
+/// One isolate's foreground tasks, as V8's own task runner keeps them: run in
+/// posting order once due, and a non-nestable task never runs inside another.
+///
+/// Any thread may post. The runner pops and runs one task at a time, and
+/// sleeps in `wait` until a task is due or `ring` is called, which is how a
+/// termination reaches a runner awaiting a promise. A post or ring that lands
+/// before the runner sleeps ends that sleep at once, so neither is lost.
+pub struct TaskQueue<T> {
+    queue: Mutex<Queue<T>>,
+    doorbell: Parker,
+}
+
+impl<T> Default for TaskQueue<T> {
+    fn default() -> Self {
+        Self {
+            queue: Mutex::new(Queue::default()),
+            doorbell: Parker::default(),
+        }
+    }
+}
+
+impl<T> TaskQueue<T> {
+    /// Queues `task` to run once `delay` has passed. A closed queue refuses
+    /// it, and the caller drops it.
+    pub fn post(&self, task: T, nestable: bool, delay: Duration) -> Result<(), T> {
+        let mut queue = lock(&self.queue);
+        if queue.closed {
+            drop(queue);
+            return Err(task);
+        }
+        queue.push(task, nestable, delay);
+        drop(queue);
+        self.doorbell.unpark();
+        Ok(())
+    }
+
+    /// The oldest task that is due. `nested`, for a pump inside a running
+    /// task, passes over non-nestable ones.
+    pub fn pop(&self, nested: bool) -> Option<T> {
+        let mut queue = lock(&self.queue);
+        let task = queue.pop(Instant::now(), nested);
+        drop(queue);
+        task
+    }
+
+    /// Sleeps until a task is due, a task is posted, or `ring` is called;
+    /// returns at once if a task is due already or the queue is closed. May
+    /// return early: callers check again. Only an outermost dispatch waits,
+    /// so every task counts.
+    pub fn wait(&self) {
+        let timeout = {
+            let mut queue = lock(&self.queue);
+            let now = Instant::now();
+            queue.promote(now);
+            if queue.closed || !queue.ready.is_empty() {
+                return;
+            }
+            queue
+                .next_due()
+                .map(|due| due.saturating_duration_since(now))
+        };
+        self.doorbell.park(timeout);
+    }
+
+    /// Ends a `wait`, or the next one if none is under way.
+    pub fn ring(&self) {
+        self.doorbell.unpark();
+    }
+
+    /// Refuses every later post and hands back what is queued, for its owner
+    /// to drop where the tasks belong.
+    pub fn close(&self) -> Vec<T> {
+        let mut queue = lock(&self.queue);
+        queue.closed = true;
+        let tasks = queue.drain();
+        drop(queue);
+        self.doorbell.unpark();
+        tasks
+    }
+
+    /// What a forked child takes over with an idle isolate: the queued tasks,
+    /// moved into a new queue and out of this one. `None` while the lock is
+    /// held, which in a child means by a thread that is gone.
+    #[must_use]
+    pub fn inherited(&self) -> Option<Self> {
+        let mut queue = self.queue.try_lock().ok()?;
+        let taken = Queue {
+            ready: std::mem::take(&mut queue.ready),
+            delayed: std::mem::take(&mut queue.delayed),
+            closed: queue.closed,
+        };
+        drop(queue);
+        Some(Self {
+            queue: Mutex::new(taken),
+            doorbell: Parker::default(),
+        })
+    }
+}
+
+impl<T> Drop for TaskQueue<T> {
+    // Tasks are dropped only by the thread their isolate runs on, which takes
+    // them with `close`. Any left here are leaked.
+    fn drop(&mut self) {
+        let leftover = lock(&self.queue).drain();
+        if !leftover.is_empty() {
+            #[expect(
+                clippy::mem_forget,
+                reason = "tasks may be dropped only where their isolate runs"
+            )]
+            std::mem::forget(leftover);
+        }
+    }
+}
+
+#[cfg(test)]
+#[cfg(not(loom))]
+mod tests {
+    use std::sync::Arc;
+    use std::sync::atomic::{AtomicUsize, Ordering};
+
+    use super::*;
+
+    const NOW: Duration = Duration::ZERO;
+
+    fn drained(queue: &TaskQueue<u32>, nested: bool) -> Vec<u32> {
+        std::iter::from_fn(|| queue.pop(nested)).collect()
+    }
+
+    #[test]
+    fn runs_tasks_in_posting_order() {
+        let queue = TaskQueue::default();
+        for task in 0..4 {
+            queue.post(task, true, NOW).expect("open");
+        }
+        assert_eq!(drained(&queue, false), [0, 1, 2, 3]);
+    }
+
+    #[test]
+    fn holds_a_delayed_task_until_it_is_due() {
+        let queue = TaskQueue::default();
+        queue
+            .post(1, true, Duration::from_millis(30))
+            .expect("open");
+        queue.post(2, true, NOW).expect("open");
+        assert_eq!(drained(&queue, false), [2]);
+        let started = Instant::now();
+        let mut waits = 0;
+        while queue.pop(false).is_none() {
+            queue.wait();
+            waits += 1;
+        }
+        assert!(started.elapsed() >= Duration::from_millis(25));
+        // The posts left the doorbell rung once; then one sleep to the deadline.
+        assert!(waits <= 3, "woke {waits} times");
+    }
+
+    // As V8's runner moves expired delayed tasks: behind those already ready,
+    // earliest deadline first.
+    #[test]
+    fn due_tasks_join_behind_ready_ones_by_deadline() {
+        let queue = TaskQueue::default();
+        queue
+            .post(1, true, Duration::from_millis(20))
+            .expect("open");
+        queue
+            .post(2, true, Duration::from_millis(10))
+            .expect("open");
+        queue
+            .post(3, true, Duration::from_millis(10))
+            .expect("open");
+        std::thread::sleep(Duration::from_millis(25));
+        queue.post(4, true, NOW).expect("open");
+        assert_eq!(drained(&queue, false), [4, 2, 3, 1]);
+    }
+
+    #[test]
+    fn a_nested_pop_passes_over_non_nestable_tasks() {
+        let queue = TaskQueue::default();
+        queue.post(1, false, NOW).expect("open");
+        queue.post(2, true, NOW).expect("open");
+        assert_eq!(drained(&queue, true), [2]);
+        assert_eq!(drained(&queue, false), [1]);
+    }
+
+    #[test]
+    fn close_hands_back_everything_and_refuses_later_posts() {
+        let queue = TaskQueue::default();
+        queue.post(1, true, Duration::from_secs(60)).expect("open");
+        queue.post(2, false, NOW).expect("open");
+        assert_eq!(queue.close(), [2, 1]);
+        assert_eq!(queue.post(3, true, NOW), Err(3));
+        assert_eq!(queue.pop(false), None);
+        queue.wait();
+    }
+
+    #[test]
+    fn a_ring_ends_a_wait_with_nothing_due() {
+        let queue = Arc::new(TaskQueue::<u32>::default());
+        let ringer = Arc::clone(&queue);
+        let thread = std::thread::spawn(move || {
+            std::thread::sleep(Duration::from_millis(20));
+            ringer.ring();
+        });
+        queue.wait();
+        thread.join().expect("ringer");
+    }
+
+    #[test]
+    fn an_absurd_delay_is_held_to_a_year() {
+        let queue = TaskQueue::default();
+        queue.post(1, true, Duration::MAX).expect("open");
+        assert_eq!(queue.pop(false), None);
+        assert_eq!(queue.close(), [1]);
+    }
+
+    #[test]
+    fn a_child_takes_the_tasks_over() {
+        let queue = TaskQueue::default();
+        queue.post(1, true, NOW).expect("open");
+        queue.post(2, true, Duration::from_secs(60)).expect("open");
+        let inherited = queue.inherited().expect("unlocked");
+        assert_eq!(queue.pop(false), None);
+        assert_eq!(inherited.pop(false), Some(1));
+        assert_eq!(inherited.close(), [2]);
+    }
+
+    #[test]
+    fn a_held_lock_leaves_nothing_to_take_over() {
+        let queue = TaskQueue::<u32>::default();
+        let held = lock(&queue.queue);
+        assert!(queue.inherited().is_none());
+        drop(held);
+    }
+
+    struct Counted(Arc<AtomicUsize>);
+
+    impl Drop for Counted {
+        fn drop(&mut self) {
+            self.0.fetch_add(1, Ordering::SeqCst);
+        }
+    }
+
+    #[test]
+    fn tasks_left_in_a_dropped_queue_are_leaked() {
+        let drops = Arc::new(AtomicUsize::new(0));
+        let queue = TaskQueue::default();
+        queue
+            .post(Counted(Arc::clone(&drops)), true, NOW)
+            .map_err(drop)
+            .expect("open");
+        drop(queue);
+        assert_eq!(drops.load(Ordering::SeqCst), 0);
+    }
+}