FIX: reuse native runner across fork

Run single-threaded V8 dispatches on a reusable mini_racer-owned native
thread.

All V8 work must be isolated from Ruby owned threads or we risk segfaults

Author: SamSaffron

CHANGELOG

@@ -1,3 +1,8 @@
+- 0.21.1 - 25-05-2026
+  - Run `:single_threaded` V8 dispatches on a reusable mini_racer-owned native thread so V8 does not execute on Ruby-owned threads
+  - Stop and join the reusable `:single_threaded` runner when contexts are disposed
+  - Document `:single_threaded` fork-safety requirements for pre-fork contexts
+
 - 0.21.0 - 16-04-2026
   - Add MiniRacer::Binary for returning Uint8Array to JavaScript from attached Ruby callbacks
 

DESIGN.md

@@ -54,9 +54,11 @@ they are almost universally:
 deliberate changes & known bugs
 ===============================
 
-- `MiniRacer::Platform.set_flags! :single_threaded` still runs everything on
-  the same thread but is prone to crashes in Ruby < 3.4.0 due to a Ruby runtime
-  bug that clobbers thread-local variables.
+- `MiniRacer::Platform.set_flags! :single_threaded` runs V8 dispatches on a
+  reusable mini_racer-owned native thread. Pre-fork contexts may be used in the
+  child only if the process forks while MiniRacer is quiescent; applications that
+  fork from a multi-threaded process should guard all MiniRacer context
+  operations and `fork` with the same lock.
 
 - The `Isolate` class is gone. Maintaining a one-to-many relationship between
   isolates and contexts in a multi-threaded environment had a bad cost/benefit

README.md

@@ -139,6 +139,15 @@ Since 0.6.1 mini_racer does support V8 single threaded platform mode which shoul
 MiniRacer::Platform.set_flags!(:single_threaded)
 ```
 
+When using pre-fork `MiniRacer::Context` objects in `:single_threaded` mode,
+ensure the process only forks while MiniRacer is quiescent: no thread may be
+evaluating JavaScript, calling into a context, disposing/freeing a context,
+running a Ruby callback from JavaScript, or otherwise using MiniRacer at the
+instant of `fork`. In multi-threaded applications, guard all MiniRacer context
+operations and the `fork` itself with the same application-level lock. Forking
+while a MiniRacer operation is in progress can leave inherited pthread mutexes
+in an unusable state in the child process.
+
 If you want to ensure your application does not leak memory after fork either:
 
 1. Ensure no `MiniRacer::Context` objects are created in the master process; or

ext/mini_racer_extension/mini_racer_extension.c

@@ -4,6 +4,7 @@
 #include <stdlib.h>
 #include <string.h>
 #include <pthread.h>
+#include <unistd.h>
 #include <math.h>
 
 #if defined(__linux__) && !defined(__GLIBC__)
@@ -136,6 +137,9 @@ typedef struct Context
     VALUE exception;   // pending exception or Qnil
     Buf req, res;      // ruby->v8 request/response, mediated by |mtx| and |cv|
     Buf snapshot;
+    pthread_t single_threaded_thr;
+    pid_t single_threaded_pid;
+    int single_threaded_thr_started;
     // |rr_mtx| stands for "recursive ruby mutex"; it's used to exclude
     // other ruby threads but allow reentrancy from the same ruby thread
     // (think ruby->js->ruby->js calls)
@@ -868,18 +872,10 @@ void v8_dispatch(Context *c)
 // only called when inside v8_call, v8_eval, or v8_pump_message_loop
 void v8_roundtrip(Context *c, const uint8_t **p, size_t *n)
 {
-    struct rendezvous_nogvl *args;
-
     buf_reset(&c->req);
-    if (single_threaded) {
-        assert(*c->res.buf == 'c'); // js -> ruby callback
-        args = &(struct rendezvous_nogvl){c, &c->req, &c->res};
-        rb_thread_call_with_gvl(rendezvous_callback, args);
-    } else {
-        pthread_cond_signal(&c->cv);
-        while (!c->req.len)
-            pthread_cond_wait(&c->cv, &c->mtx);
-    }
+    pthread_cond_signal(&c->cv);
+    while (!c->req.len)
+        pthread_cond_wait(&c->cv, &c->mtx);
     buf_reset(&c->res);
     *p = c->req.buf;
     *n = c->req.len;
@@ -991,10 +987,45 @@ static void *rendezvous_callback(void *arg)
     goto out;
 }
 
+static void *single_threaded_runner(void *arg)
+{
+    Context *c;
+
+    c = arg;
+    pthread_mutex_lock(&c->mtx);
+    for (;;) {
+        while (!c->req.len && atomic_load(&c->quit) < 1)
+            pthread_cond_wait(&c->cv, &c->mtx);
+        if (atomic_load(&c->quit) >= 1)
+            break;
+        v8_single_threaded_enter(c->pst, c, dispatch);
+        pthread_cond_signal(&c->cv);
+    }
+    pthread_mutex_unlock(&c->mtx);
+    return NULL;
+}
+
+static int single_threaded_runner_start(Context *c)
+{
+    pid_t pid;
+    int r;
+
+    pid = getpid();
+    if (c->single_threaded_thr_started && c->single_threaded_pid == pid)
+        return 0;
+    c->single_threaded_thr_started = 0;
+    c->single_threaded_pid = pid;
+    r = pthread_create(&c->single_threaded_thr, NULL, single_threaded_runner, c);
+    if (!r)
+        c->single_threaded_thr_started = 1;
+    return r;
+}
+
 static inline void *rendezvous_nogvl(void *arg)
 {
     struct rendezvous_nogvl *a;
     Context *c;
+    int r;
 
     a = arg;
     c = a->context;
@@ -1010,7 +1041,16 @@ static inline void *rendezvous_nogvl(void *arg)
     assert(c->res.len == 0);
     buf_move(a->req, &c->req); // v8 thread takes ownership of req
     if (single_threaded) {
-        v8_single_threaded_enter(c->pst, c, dispatch);
+        r = single_threaded_runner_start(c);
+        if (r) {
+            buf_move(&c->req, a->req);
+            pthread_mutex_unlock(&c->mtx);
+            c->depth--;
+            pthread_mutex_unlock(&c->rr_mtx);
+            return (void *)(intptr_t)r;
+        }
+        pthread_cond_signal(&c->cv);
+        do pthread_cond_wait(&c->cv, &c->mtx); while (!c->res.len);
     } else {
         pthread_cond_signal(&c->cv);
         do pthread_cond_wait(&c->cv, &c->mtx); while (!c->res.len);
@@ -1019,6 +1059,7 @@ static inline void *rendezvous_nogvl(void *arg)
     pthread_mutex_unlock(&c->mtx);
     if (*a->res->buf == 'c') { // js -> ruby callback?
         rb_thread_call_with_gvl(rendezvous_callback, a);
+        buf_reset(a->res);
         goto next;
     }
     c->depth--;
@@ -1028,12 +1069,16 @@ static inline void *rendezvous_nogvl(void *arg)
 
 static void rendezvous_no_des(Context *c, Buf *req, Buf *res)
 {
+    void *r;
+
     if (atomic_load(&c->quit)) {
         buf_reset(req);
         rb_raise(context_disposed_error, "disposed context");
     }
-    rb_nogvl(rendezvous_nogvl, &(struct rendezvous_nogvl){c, req, res},
-             NULL, NULL, 0);
+    r = rb_nogvl(rendezvous_nogvl, &(struct rendezvous_nogvl){c, req, res},
+                 NULL, NULL, 0);
+    if (r)
+        rb_raise(runtime_error, "pthread_create: %s", strerror((int)(intptr_t)r));
 }
 
 // send request to & receive reply from v8 thread; takes ownership of |req|
@@ -1190,7 +1235,16 @@ static void *context_free_thread_do(void *arg)
     Context *c;
 
     c = arg;
-    v8_single_threaded_dispose(c->pst);
+    if (single_threaded && c->single_threaded_thr_started && c->single_threaded_pid == getpid()) {
+        pthread_mutex_lock(&c->mtx);
+        atomic_store(&c->quit, 2);
+        pthread_cond_signal(&c->cv);
+        pthread_mutex_unlock(&c->mtx);
+        pthread_join(c->single_threaded_thr, NULL);
+    }
+    if (c->pst)
+        v8_single_threaded_dispose(c->pst);
+    pthread_mutex_lock(&c->mtx);
     context_destroy(c);
     return NULL;
 }
@@ -1284,8 +1338,18 @@ static void *context_dispose_do(void *arg)
 
     c = arg;
     if (single_threaded) {
+        pthread_mutex_lock(&c->mtx);
+        while (c->req.len || c->res.len)
+            pthread_cond_wait(&c->cv, &c->mtx);
         atomic_store(&c->quit, 1);   // disposed
-        // intentionally a no-op for now
+        if (c->single_threaded_thr_started && c->single_threaded_pid == getpid()) {
+            pthread_cond_signal(&c->cv);
+            pthread_mutex_unlock(&c->mtx);
+            pthread_join(c->single_threaded_thr, NULL);
+            pthread_mutex_lock(&c->mtx);
+            c->single_threaded_thr_started = 0;
+        }
+        pthread_mutex_unlock(&c->mtx);
     } else {
         pthread_mutex_lock(&c->mtx);
         while (c->req.len || c->res.len)

lib/mini_racer/version.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 module MiniRacer
-  VERSION = "0.21.0"
+  VERSION = "0.21.1"
   LIBV8_NODE_VERSION = "~> 24.12.0.1"
 end

test/single_threaded_test.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require "test_helper"
+require "open3"
+require "rbconfig"
+require "tempfile"
+
+class MiniRacerSingleThreadedTest < Minitest::Test
+  def assert_single_threaded_script(script)
+    skip "single-threaded V8 platform tests are only for CRuby" unless RUBY_ENGINE == "ruby"
+
+    file = Tempfile.new(["mini_racer_single_threaded", ".rb"])
+    file.write(<<~RUBY)
+      $LOAD_PATH.unshift #{File.expand_path("../lib", __dir__).inspect}
+      require "mini_racer"
+
+      MiniRacer::Platform.set_flags!(:single_threaded)
+
+      #{script}
+    RUBY
+    file.close
+
+    stdout, stderr, status = Open3.capture3(RbConfig.ruby, file.path)
+    assert status.success?, <<~MSG
+      single-threaded script failed with status #{status.exitstatus}
+      stdout:
+      #{stdout}
+      stderr:
+      #{stderr}
+    MSG
+  ensure
+    file&.unlink
+  end
+
+  def test_basic_eval_and_call
+    assert_single_threaded_script <<~'RUBY'
+      context = MiniRacer::Context.new
+      raise "bad eval" unless context.eval("1 + 1") == 2
+      context.eval("function add(a, b) { return a + b }")
+      raise "bad call" unless context.call("add", 20, 22) == 42
+    RUBY
+  end
+
+  def test_ruby_callback_from_javascript
+    assert_single_threaded_script <<~'RUBY'
+      context = MiniRacer::Context.new
+      context.attach("ruby_add", proc { |a, b| a + b })
+      raise "bad callback result" unless context.eval("ruby_add(20, 22)") == 42
+    RUBY
+  end
+
+  def test_nested_javascript_ruby_javascript_call
+    assert_single_threaded_script <<~'RUBY'
+      context = MiniRacer::Context.new
+      context.eval("function js_add(a, b) { return a + b }")
+      context.attach("ruby_calls_js", proc { context.call("js_add", 20, 22) })
+      raise "bad nested callback result" unless context.eval("ruby_calls_js()") == 42
+    RUBY
+  end
+
+  def test_recursive_javascript_ruby_callback_ping_pong
+    assert_single_threaded_script <<~'RUBY'
+      context = MiniRacer::Context.new
+      context.attach("ruby_recurse", proc { |n|
+        n <= 0 ? "done" : context.call("js_recurse", n - 1)
+      })
+      context.eval(<<~JS)
+        function js_recurse(n) {
+          if (n <= 0) return "done";
+          return ruby_recurse(n);
+        }
+      JS
+      raise "bad recursive callback result" unless context.call("js_recurse", 10) == "done"
+    RUBY
+  end
+
+  def test_ruby_callback_exception_propagates
+    assert_single_threaded_script <<~'RUBY'
+      context = MiniRacer::Context.new
+      context.attach("boom", proc { raise "ruby boom" })
+
+      begin
+        context.eval("boom()")
+        raise "expected callback exception"
+      rescue RuntimeError => e
+        raise "wrong exception: #{e.class}: #{e.message}" unless e.message.include?("ruby boom")
+      end
+    RUBY
+  end
+
+  def test_dispose_after_runner_started
+    assert_single_threaded_script <<~'RUBY'
+      context = MiniRacer::Context.new
+      raise "bad eval" unless context.eval("1 + 1") == 2
+      context.dispose
+
+      begin
+        context.eval("1 + 1")
+        raise "expected disposed error"
+      rescue MiniRacer::ContextDisposedError
+      end
+
+      context = nil
+      GC.start
+    RUBY
+  end
+
+  def test_multiple_contexts_and_dispose_one
+    assert_single_threaded_script <<~'RUBY'
+      a = MiniRacer::Context.new
+      b = MiniRacer::Context.new
+
+      a.eval("var x = 1")
+      b.eval("var x = 2")
+
+      raise "bad context a" unless a.eval("x") == 1
+      raise "bad context b" unless b.eval("x") == 2
+
+      a.dispose
+      raise "context b broke after disposing a" unless b.eval("x + 40") == 42
+    RUBY
+  end
+
+  def test_fork_after_runner_started_and_idle
+    assert_single_threaded_script <<~'RUBY'
+      exit 0 unless Process.respond_to?(:fork)
+
+      context = MiniRacer::Context.new
+      context.eval("var answer = 41")
+      context.eval("answer += 1") # starts the reusable runner and leaves it idle
+
+      pid = fork do
+        exit(context.eval("answer") == 42 ? 0 : 1)
+      end
+      Process.wait(pid)
+      raise "child failed" unless $?.success?
+    RUBY
+  end
+end