Add Ractor.check_isolation

Run the block in a real non-main Ractor while preserving its closure and
argument identities. Downgrade isolation violations to categorized warnings
so applications can sweep worker-Ractor compatibility without stopping at
the first failure.

Support an exclusive scheduler mode for race-free checks and cover the
isolation gates, fast paths, messaging, and thread inheritance.

Author: skipkayhil

error.c

@@ -89,6 +89,7 @@ static ID id_deprecated;
 static ID id_experimental;
 static ID id_performance;
 static ID id_strict_unused_block;
+static ID id_ractor_isolation;
 static VALUE sym_category;
 static VALUE sym_highlight;
 static struct {
@@ -224,6 +225,10 @@ rb_warning_category_enabled_p(rb_warning_category_t category)
  * +:performance+ ::
  *   performance hints
  *   * Shape variation limit
+ *
+ * +:ractor_isolation+ ::
+ *   Ractor isolation violations reported by Ractor.check_isolation
+ *   (downgraded from Ractor::IsolationError exceptions to warnings).
  */
 
 static VALUE
@@ -3884,6 +3889,7 @@ Init_Exception(void)
     id_experimental = rb_intern_const("experimental");
     id_performance = rb_intern_const("performance");
     id_strict_unused_block = rb_intern_const("strict_unused_block");
+    id_ractor_isolation = rb_intern_const("ractor_isolation");
     id_top = rb_intern_const("top");
     id_bottom = rb_intern_const("bottom");
     id_iseq = rb_make_internal_id();
@@ -3897,13 +3903,15 @@ Init_Exception(void)
     st_add_direct(warning_categories.id2enum, id_experimental, RB_WARN_CATEGORY_EXPERIMENTAL);
     st_add_direct(warning_categories.id2enum, id_performance, RB_WARN_CATEGORY_PERFORMANCE);
     st_add_direct(warning_categories.id2enum, id_strict_unused_block, RB_WARN_CATEGORY_STRICT_UNUSED_BLOCK);
+    st_add_direct(warning_categories.id2enum, id_ractor_isolation, RB_WARN_CATEGORY_RACTOR_ISOLATION);
 
     warning_categories.enum2id = rb_init_identtable();
     st_add_direct(warning_categories.enum2id, RB_WARN_CATEGORY_NONE, 0);
     st_add_direct(warning_categories.enum2id, RB_WARN_CATEGORY_DEPRECATED, id_deprecated);
     st_add_direct(warning_categories.enum2id, RB_WARN_CATEGORY_EXPERIMENTAL, id_experimental);
     st_add_direct(warning_categories.enum2id, RB_WARN_CATEGORY_PERFORMANCE, id_performance);
     st_add_direct(warning_categories.enum2id, RB_WARN_CATEGORY_STRICT_UNUSED_BLOCK, id_strict_unused_block);
+    st_add_direct(warning_categories.enum2id, RB_WARN_CATEGORY_RACTOR_ISOLATION, id_ractor_isolation);
 }
 
 void

gc.c

@@ -2097,6 +2097,12 @@ rb_undefine_finalizer(VALUE obj)
 {
     rb_check_frozen(obj);
 
+    if (rb_gc_obj_foreign_p(obj)) {
+        rb_ractor_isolation_violation(
+            "can not undefine a finalizer of an object of another Ractor");
+        return obj;
+    }
+
     rb_gc_impl_undefine_finalizer(rb_gc_get_objspace(), obj);
 
     return obj;
@@ -2217,7 +2223,13 @@ rb_define_finalizer(VALUE obj, VALUE block)
     should_be_finalizable(obj);
     should_be_callable(block);
 
-    block = rb_gc_impl_define_finalizer(rb_gc_get_objspace(), obj, block);
+    if (rb_gc_obj_foreign_p(obj)) {
+        rb_ractor_isolation_violation(
+            "can not define a finalizer for an object of another Ractor");
+    }
+    else {
+        block = rb_gc_impl_define_finalizer(rb_gc_get_objspace(), obj, block);
+    }
 
     block = rb_ary_new3(2, INT2FIX(0), block);
     OBJ_FREEZE(block);

include/ruby/internal/error.h

@@ -56,16 +56,21 @@ typedef enum {
     /** Warning is for checking unused block strictly */
     RB_WARN_CATEGORY_STRICT_UNUSED_BLOCK,
 
+    /** Warning is for Ractor isolation violations reported by Ractor.check_isolation. */
+    RB_WARN_CATEGORY_RACTOR_ISOLATION,
+
     RB_WARN_CATEGORY_DEFAULT_BITS = (
         (1U << RB_WARN_CATEGORY_DEPRECATED) |
         (1U << RB_WARN_CATEGORY_EXPERIMENTAL) |
+        (1U << RB_WARN_CATEGORY_RACTOR_ISOLATION) |
         0),
 
     RB_WARN_CATEGORY_ALL_BITS = (
         (1U << RB_WARN_CATEGORY_DEPRECATED) |
         (1U << RB_WARN_CATEGORY_EXPERIMENTAL) |
         (1U << RB_WARN_CATEGORY_PERFORMANCE) |
         (1U << RB_WARN_CATEGORY_STRICT_UNUSED_BLOCK) |
+        (1U << RB_WARN_CATEGORY_RACTOR_ISOLATION) |
         0)
 } rb_warning_category_t;
 

process.c

@@ -4109,7 +4109,7 @@ rb_pid_t
 rb_fork_ruby(int *status)
 {
     if (UNLIKELY(!rb_ractor_main_p())) {
-        rb_raise(rb_eRactorIsolationError, "can not fork from non-main Ractors");
+        rb_ractor_isolation_violation("can not fork from non-main Ractors");
     }
 
     struct rb_process_status child = {.status = 0};

ractor.c

@@ -5,6 +5,7 @@
 #include "ruby/ractor.h"
 #include "ruby/re.h"
 #include "ruby/thread_native.h"
+#include "ruby_atomic.h"
 #include "vm_core.h"
 #include "vm_sync.h"
 #include "ractor_core.h"
@@ -840,11 +841,12 @@ rb_ractor_main_setup(rb_vm_t *vm, rb_ractor_t *r, rb_thread_t *th)
 }
 
 static VALUE
-ractor_create(rb_execution_context_t *ec, VALUE self, VALUE loc, VALUE name, VALUE args, VALUE block)
+ractor_create0(rb_execution_context_t *ec, VALUE self, VALUE loc, VALUE name, VALUE args, VALUE block, bool isolation_check)
 {
     VALUE rv = ractor_alloc(self);
     rb_ractor_t *r = RACTOR_PTR(rv);
     ractor_init(r, name, loc);
+    r->isolation_check = isolation_check;
 
     r->pub.id = ractor_next_id();
     RUBY_DEBUG_LOG("r:%u", r->pub.id);
@@ -863,6 +865,12 @@ ractor_create(rb_execution_context_t *ec, VALUE self, VALUE loc, VALUE name, VAL
     return rv;
 }
 
+static VALUE
+ractor_create(rb_execution_context_t *ec, VALUE self, VALUE loc, VALUE name, VALUE args, VALUE block)
+{
+    return ractor_create0(ec, self, loc, name, args, block, false);
+}
+
 #if 0
 static VALUE
 ractor_create_func(VALUE klass, VALUE loc, VALUE name, VALUE args, rb_block_call_func_t func)
@@ -1850,6 +1858,12 @@ make_shareable_check_shareable(VALUE obj)
     }
     else if (!allow_frozen_shareable_p(obj)) {
         if (!RB_TYPE_P(obj, T_DATA)) {
+            if (rb_ractor_isolation_check_p()) {
+                rb_category_warn(RB_WARN_CATEGORY_RACTOR_ISOLATION,
+                                 "can not make shareable object of class %+"PRIsVALUE,
+                                 rb_class_of(obj));
+                return traverse_stop;
+            }
             rb_raise(rb_eRactorError,
                      "can not make shareable object for %+"PRIsVALUE, obj);
         }
@@ -1859,14 +1873,26 @@ make_shareable_check_shareable(VALUE obj)
                 RB_OBJ_SET_SHAREABLE(obj);
                 return traverse_skip;
             }
+            else if (rb_ractor_isolation_check_p()) {
+                rb_category_warn(RB_WARN_CATEGORY_RACTOR_ISOLATION,
+                                 "can not make shareable object of class %+"PRIsVALUE
+                                 " because it refers unshareable objects", rb_class_of(obj));
+                return traverse_stop;
+            }
             else {
                 rb_raise(rb_eRactorError,
                          "can not make shareable object for %+"PRIsVALUE" because it refers unshareable objects", obj);
             }
         }
         else if (rb_obj_is_proc(obj)) {
             rb_proc_ractor_make_shareable(obj, Qundef);
-            return traverse_cont;
+            return rb_ractor_shareable_p(obj) ? traverse_cont : traverse_stop;
+        }
+        else if (rb_ractor_isolation_check_p()) {
+            rb_category_warn(RB_WARN_CATEGORY_RACTOR_ISOLATION,
+                             "can not make shareable object of class %+"PRIsVALUE,
+                             rb_class_of(obj));
+            return traverse_stop;
         }
         else {
             rb_raise(rb_eRactorError, "can not make shareable object for %+"PRIsVALUE, obj);
@@ -1930,9 +1956,10 @@ VALUE
 rb_ractor_ensure_shareable(VALUE obj, VALUE name)
 {
     if (!rb_ractor_shareable_p(obj)) {
-        VALUE message = rb_sprintf("cannot assign unshareable object to %"PRIsVALUE,
-                                   name);
-        rb_exc_raise(rb_exc_new_str(rb_eRactorIsolationError, message));
+        rb_ractor_isolation_violation("cannot assign unshareable object to %"PRIsVALUE, name);
+        // In check_isolation mode the violation only warned: return obj as-is
+        // so the caller can keep going. The caller's invariant ("this is now
+        // shareable") will be wrong, which is exactly the bug we want surfaced.
     }
     return obj;
 }
@@ -1941,7 +1968,7 @@ void
 rb_ractor_ensure_main_ractor(const char *msg)
 {
     if (!rb_ractor_main_p()) {
-        rb_raise(rb_eRactorIsolationError, "%s", msg);
+        rb_ractor_isolation_violation("%s", msg);
     }
 }
 
@@ -3783,13 +3810,11 @@ ractor_local_value_store_if_absent(rb_execution_context_t *ec, VALUE self, VALUE
 static VALUE
 ractor_shareable_proc(rb_execution_context_t *ec, VALUE replace_self, bool is_lambda)
 {
-    if (!rb_ractor_shareable_p(replace_self)) {
-        rb_raise(rb_eRactorIsolationError, "self should be shareable: %" PRIsVALUE, replace_self);
-    }
-    else {
-        VALUE proc = is_lambda ? rb_block_lambda() : rb_block_proc();
-        return rb_proc_ractor_make_shareable(rb_proc_dup(proc), replace_self);
+    if (!rb_ractor_shareable_p(replace_self) && !rb_ractor_isolation_check_p()) {
+        rb_ractor_isolation_violation("self should be shareable: %" PRIsVALUE, replace_self);
     }
+    VALUE proc = is_lambda ? rb_block_lambda() : rb_block_proc();
+    return rb_proc_ractor_make_shareable(rb_proc_dup(proc), replace_self);
 }
 
 // Ractor#require
@@ -4001,4 +4026,76 @@ rb_ractor_autoload_load(VALUE module, ID name)
     }
 }
 
+// =============================================================================
+// Ractor.check_isolation { ... }
+//
+// A development/debugging mode: the block runs in a genuine non-main Ractor,
+// without isolating its Proc or copying its arguments. Violations are
+// downgraded from Ractor::IsolationError to :ractor_isolation category warnings
+// so the program can keep running and report more than the first violation.
+//
+// As a side effect (matches Ractor semantics), the VM is switched into
+// multi-ractor mode the first time check_isolation is enabled. Multi-ractor
+// mode cannot be turned off again, so the VM keeps paying that overhead for
+// the rest of the process lifetime.
+// =============================================================================
+
+bool
+rb_ractor_isolation_check_p(void)
+{
+    rb_execution_context_t *ec = rb_current_ec_noinline();
+    if (!ec) return false;
+    rb_ractor_t *r = rb_ec_ractor_ptr(ec);
+    return r && r->isolation_check;
+}
+
+void
+rb_ractor_isolation_violation_str(VALUE message)
+{
+    if (rb_ractor_isolation_check_p()) {
+        rb_category_warn(RB_WARN_CATEGORY_RACTOR_ISOLATION, "%s", StringValueCStr(message));
+        return;
+    }
+
+    rb_exc_raise(rb_exc_new_str(rb_eRactorIsolationError, message));
+}
+
+void
+rb_ractor_isolation_violation(const char *fmt, ...)
+{
+    va_list args;
+    va_start(args, fmt);
+    VALUE message = rb_vsprintf(fmt, args);
+    va_end(args);
+
+    rb_ractor_isolation_violation_str(message);
+}
+
+/* Set during native-thread scheduler initialization; see thread_sched.c. */
+extern int ruby_ractor_exclusive_enabled;
+
+static rb_atomic_t ractor_check_isolation_advisory_emitted;
+
+/* Return true to exactly one caller when nonexclusive mode needs its advisory.
+ * This state cannot live on Ractor itself: setting a class/module ivar from an
+ * ordinary non-main Ractor is itself an isolation violation. */
+static VALUE
+ractor_check_isolation_warn_p(rb_execution_context_t *ec, VALUE self)
+{
+    if (ruby_ractor_exclusive_enabled) return Qfalse;
+    return RBOOL(ATOMIC_EXCHANGE(ractor_check_isolation_advisory_emitted, 1) == 0);
+}
+
+static VALUE
+ractor_check_isolation_p(rb_execution_context_t *ec, VALUE self)
+{
+    return RBOOL(rb_ractor_isolation_check_p());
+}
+
+static VALUE
+ractor_check_isolation_create(rb_execution_context_t *ec, VALUE self, VALUE loc, VALUE name, VALUE args, VALUE block)
+{
+    return ractor_create0(ec, self, loc, name, args, block, true);
+}
+
 #include "ractor.rbinc"

ractor.rb

@@ -538,6 +538,50 @@ def self.main?
     }
   end
 
+  # call-seq:
+  #   Ractor.check_isolation(*args, name: nil) {|*args| ... } -> result of block
+  #
+  # Runs the block in a genuine non-main \Ractor while downgrading isolation
+  # violations to +:ractor_isolation+ category warnings. Unlike +Ractor.new+,
+  # the block is not isolated and its arguments are passed by reference, so it
+  # can close over and inspect existing non-shareable application state.
+  #
+  # The block therefore observes production worker-Ractor behavior:
+  # +Ractor.main?+ is false and +Ractor.current+ is the newly created \Ractor.
+  # Its return value is delivered through +Ractor#value+, and exceptions are
+  # re-raised there as for an ordinary \Ractor.
+  #
+  # On builds with M:N scheduling, booting with +RUBY_RACTOR_EXCLUSIVE=1+
+  # limits the scheduler to one shared native thread. This prevents simultaneous
+  # Ruby execution on shared native threads, but does not make the block atomic:
+  # blocking operations can hand the run slot to another \Ractor, and dedicated
+  # native threads are not covered. Without that mode, this method emits a
+  # one-time advisory because other \Ractors may run in parallel.
+  #
+  # Calling this method switches the VM into multi-Ractor mode permanently.
+  # Suppress isolation warnings with +Warning[:ractor_isolation] = false+ or
+  # +-W:no-ractor_isolation+.
+  def self.check_isolation(*args, name: nil, &block)
+    b = block # TODO: builtin bug
+    raise ArgumentError, "must be called with a block" unless block
+
+    if Primitive.ractor_check_isolation_warn_p
+      Kernel.warn("Ractor.check_isolation: other Ractors can run in parallel " \
+                  "with the isolation-check Ractor. On builds with M:N scheduling, " \
+                  "RUBY_RACTOR_EXCLUSIVE=1 prevents simultaneous Ruby execution on " \
+                  "shared native threads.", uplevel: 1)
+    end
+
+    loc = caller_locations(1, 1).first
+    loc = "#{loc.path}:#{loc.lineno}"
+    Primitive.ractor_check_isolation_create(loc, name, args, b).value
+  end
+
+  # Returns true when the current \Ractor is running an isolation check.
+  def self.check_isolation?
+    Primitive.ractor_check_isolation_p
+  end
+
   # internal method
   def self._require feature # :nodoc:
     if main?

ractor_core.h

@@ -144,6 +144,7 @@ struct rb_ractor_struct {
 
     bool malloc_gc_disabled;
     bool main_ractor;
+    bool isolation_check;
     void *newobj_cache;
 
     /* This Ractor's objspace.  The main Ractor receives the boot objspace from
@@ -235,6 +236,20 @@ VALUE rb_ractor_autoload_load(VALUE space, ID id);
 VALUE rb_ractor_ensure_shareable(VALUE obj, VALUE name);
 st_table *rb_ractor_targeted_hooks(rb_ractor_t *cr);
 
+/* True if the current Ractor was created by Ractor.check_isolation. */
+bool rb_ractor_isolation_check_p(void);
+
+/* Report a Ractor isolation violation:
+ *   - if Ractor.check_isolation is active on the current Ractor, emit a
+ *     :ractor_isolation category warning and return;
+ *   - otherwise, raise Ractor::IsolationError (does not return).
+ *
+ * Use the printf-style overload for ad-hoc messages and the _str overload
+ * when the message is already constructed (e.g. via several rb_str_catf
+ * calls). */
+PRINTF_ARGS(void rb_ractor_isolation_violation(const char *fmt, ...), 1, 2);
+void rb_ractor_isolation_violation_str(VALUE message);
+
 RUBY_SYMBOL_EXPORT_BEGIN
 void rb_ractor_finish_marking(bool full_mark);
 

ractor_sync.c

@@ -1068,6 +1068,20 @@ ractor_prepare_payload(rb_execution_context_t *ec, VALUE obj, enum ractor_basket
             *ptype = basket_type_ref;
             return obj;
         }
+        else if (rb_ractor_isolation_check_p()) {
+            // Under Ractor.check_isolation, don't copy non-shareable messages.
+            // Copying can fail outright (e.g. Procs -> "can not copy Proc
+            // object"), which would abort a real-Ractor sweep at the first
+            // Ractor::Dispatch call. Exclusive mode (RUBY_RACTOR_EXCLUSIVE)
+            // guarantees no other Ractor runs concurrently, so passing the
+            // original object by reference is safe; warn and continue.
+            rb_category_warn(RB_WARN_CATEGORY_RACTOR_ISOLATION,
+                             "can not copy an unshareable %"PRIsVALUE" across Ractors; "
+                             "passing by reference under Ractor.check_isolation",
+                             rb_class_of(obj));
+            *ptype = basket_type_ref;
+            return obj;
+        }
         else {
             /* Snapshot the object on the sender side without calling the user-visible
              * #clone.  Both forms are off-heap, so an in-flight payload is never a GC