Run C extensions marked as rb_ext_ractor_safe()/rb_ext_thread_safe() without the C extension lock

* Fixes #2136.
* Rename *c_mutex* methods to *cext_lock* for consistency and clarity.

Author: eregon

CHANGELOG.md

@@ -18,6 +18,7 @@ Compatibility:
 
 Performance:
 
+* Run C extensions marked as `rb_ext_ractor_safe()` or `rb_ext_thread_safe()` in parallel (without the C extension lock) (#2136, @eregon).
 
 Changes:
 

doc/user/benchmarking.md

@@ -44,10 +44,12 @@ See [this documentation](reporting-performance-problems.md) for more details abo
 
 ### Consider Disabling the Global C-Extension Lock
 
-On TruffleRuby, C extensions by default use a global lock for maximum compatibility with CRuby.
-If you are benchmarking a multi-threaded Ruby program (e.g. Rails on a multi-threaded server), it is worth trying
+On TruffleRuby, C extensions by default use a global extension lock for maximum compatibility with CRuby.
+Extensions marked as thread-safe by using `rb_ext_ractor_safe()` or `rb_ext_thread_safe()` do not use the global extension lock and run in parallel.
+
+If you are benchmarking a multi-threaded Ruby program (e.g. Rails on a multi-threaded server),
+and not all extensions are already marked as thread-safe, it is worth trying
 `TRUFFLERUBYOPT="--experimental-options --cexts-lock=false"`.
-[This issue](https://github.com/oracle/truffleruby/issues/2136) tracks a way to automatically not use the lock for extensions which do not need it.
 
 ## Recommendations
 

doc/user/compatibility.md

@@ -194,6 +194,15 @@ To help alleviate this problem, backtraces are automatically disabled in cases w
 
 ## C Extension Compatibility
 
+### Global Extension Lock
+
+Native extensions are by default considered thread-unsafe for maximum compatibility with CRuby and use the global extension lock (unless `--cexts-lock=false` is used).
+
+Extensions can mark themselves as thread-safe either by using `rb_ext_ractor_safe()` or `rb_ext_thread_safe()`.
+Such extensions are then run by TruffleRuby without a global extension lock, i.e. in parallel.
+
+See [Thread-Safe Extensions](thread-safe-extensions.md) for how to mark extensions as Ractor-safe or thread-safe.
+
 ### Identifiers may be macros or functions
 
 Identifiers which are normally macros may be functions, functions may be macros, and global variables may be macros.

doc/user/thread-safe-extensions.md

@@ -0,0 +1,54 @@
+---
+layout: docs-experimental
+toc_group: ruby
+link_title: Thread-Safe Extensions
+permalink: /reference-manual/ruby/ThreadSafeExtensions/
+---
+# Thread-Safe Extensions
+
+Native extensions are by default considered thread-unsafe for maximum compatibility with CRuby and use the global extension lock (unless `--cexts-lock=false` is used).
+
+Extensions can mark themselves as thread-safe either by using `rb_ext_ractor_safe()` or `rb_ext_thread_safe()` (TruffleRuby-specific).
+Such extensions are then run by TruffleRuby without a global extension lock, i.e. in parallel.
+
+Here is an example of an extension marking itself as Ractor-safe.
+Such an extension must then satisfy [the conditions for Ractor-safe extensions](https://github.com/ruby/ruby/blob/master/doc/extension.rdoc#appendix-f-ractor-support-).
+```c
+void Init_my_extension(void) {
+    #ifdef HAVE_RB_EXT_RACTOR_SAFE
+    rb_ext_ractor_safe(true);
+    #endif
+
+    rb_define_method(myClass, "foo", foo_impl, 0); // The C function foo_impl can be called from multiple threads in parallel
+}
+```
+
+Here is an example of an extension marking itself as thread-safe:
+```c
+void Init_my_extension(void) {
+    #ifdef HAVE_RB_EXT_THREAD_SAFE
+    rb_ext_thread_safe(true);
+    #endif
+
+    rb_define_method(myClass, "foo", foo_impl, 0); // The C function foo_impl can be called from multiple threads in parallel
+}
+```
+
+The conditions for an extension to be thread-safe are the following.
+This is similar to [the conditions for Ractor-safe extensions](https://github.com/ruby/ruby/blob/master/doc/extension.rdoc#appendix-f-ractor-support-) but not all conditions are necessary.
+1. The extension should make it clear in its documentation which objects are safe to share between threads and which are not.
+   This already needs to be done on CRuby with the GVL, as threads run concurrently.
+   It helps gem users to avoid sharing objects between threads incorrectly.
+2. The extension's own code must be thread-safe, e.g. not mutate state shared between threads without synchronization.
+   For example accesses to a `struct` shared between threads should typically be synchronized if it's not immutable.
+3. If the extension calls native library functions which are not thread-safe it must ensure that function cannot be called from multiple threads at the same time, e.g. using a [lock](https://github.com/oracle/truffleruby/blob/fd8dc74a72d107f8e58feaf1be1cfbb2f31d2e85/lib/cext/include/ruby/thread_native.h).
+4. Ruby C API functions/macros (like `rb_*()`) are generally thread-safe on TruffleRuby, because most of them end up calling some Ruby method.
+
+These are the differences in comparison to Ractor-safe:
+* It is allowed to share Ruby objects between multiple threads from an extension, because it is the same as sharing them with only Ruby code.
+* There is no need to mark objects as Ractor-shareable.
+
+Another way to look at this is to reason about the guarantees that a global extension lock provides:
+* C functions or sections of C code which does __*not*__ use any Ruby C API functions/macros (like `rb_*()`) are executed sequentially, i.e. one after another.
+* Calls to any Ruby C API function/macro have the possibility to trigger thread switching, and so for another part of the extension code to execute, while the current function is "suspended".
+* Therefore functions given to `rb_define_method`, if they call Ruby C API functions/macros (very likely), do not really benefit from the global extension lock as thread switching can happen in the middle of them, and they already need to take care about other functions executing in between.

lib/cext/include/ruby/internal/intern/load.h

@@ -248,6 +248,11 @@ void rb_ext_ractor_safe(bool flag);
  */
 #define HAVE_RB_EXT_RACTOR_SAFE 1
 
+#ifdef TRUFFLERUBY
+void rb_ext_thread_safe(bool flag);
+#define RB_EXT_THREAD_SAFE(f) rb_ext_thread_safe(f)
+#define HAVE_RB_EXT_THREAD_SAFE 1
+#endif
 /** @} */
 
 RBIMPL_SYMBOL_EXPORT_END()

lib/truffle/truffle/cext.rb

@@ -236,7 +236,7 @@ def init_extension(library, library_path)
 
     init_function = library[function_name]
 
-    Primitive.call_with_c_mutex_and_frame(-> {
+    Primitive.call_with_cext_lock_and_frame(-> {
       begin
         Primitive.interop_execute(VOID_TO_VOID_WRAPPER, [init_function])
       ensure
@@ -260,6 +260,10 @@ def check_abi_version(embedded_abi_version, extension_path)
     end
   end
 
+  def rb_tr_cext_lock_owned_p
+    Primitive.cext_lock_owned?
+  end
+
   def rb_stdin
     $stdin
   end
@@ -853,7 +857,7 @@ def rb_str_new_frozen(value)
 
   def rb_tracepoint_new(events, func, data)
     TracePoint.new(*events_to_events_array(events)) do |tp|
-      Primitive.call_with_c_mutex_and_frame(
+      Primitive.call_with_cext_lock_and_frame(
         POINTER2_TO_VOID_WRAPPER,
         [func, Primitive.cext_wrap(tp), data],
         Primitive.caller_special_variables_if_available,
@@ -1201,7 +1205,7 @@ def rb_path_to_class(path)
 
   def rb_proc_new(function, value)
     Proc.new do |*args, &block|
-      Primitive.call_with_c_mutex_and_frame_and_unwrap(RB_BLOCK_CALL_FUNC_WRAPPER, [
+      Primitive.call_with_cext_lock_and_frame_and_unwrap(RB_BLOCK_CALL_FUNC_WRAPPER, [
         function,
         Primitive.cext_wrap(args.first), # yieldarg
         Primitive.cext_wrap(value), # procarg,
@@ -1472,7 +1476,7 @@ def rb_enumeratorize(obj, meth, args)
   def rb_enumeratorize_with_size(obj, meth, args, size_fn)
     return rb_enumeratorize(obj, meth, args) if Primitive.interop_null?(size_fn)
     enum = obj.to_enum(meth, *args) do
-      Primitive.call_with_c_mutex_and_frame_and_unwrap(
+      Primitive.call_with_cext_lock_and_frame_and_unwrap(
         POINTER3_TO_POINTER_WRAPPER,
         [size_fn, Primitive.cext_wrap(obj), Primitive.cext_wrap(args), Primitive.cext_wrap(enum)],
         Primitive.caller_special_variables_if_available,
@@ -1491,7 +1495,7 @@ def rb_newobj_of(ruby_class)
 
   def rb_define_alloc_func(ruby_class, function)
     ruby_class.singleton_class.define_method(:__allocate__) do
-      Primitive.call_with_c_mutex_and_frame_and_unwrap(
+      Primitive.call_with_cext_lock_and_frame_and_unwrap(
         POINTER_TO_POINTER_WRAPPER,
         [function, Primitive.cext_wrap(self)],
         Primitive.caller_special_variables_if_available,
@@ -1694,7 +1698,7 @@ def rb_nativethread_lock_destroy(lock)
 
   def rb_set_end_proc(func, data)
     at_exit do
-      Primitive.call_with_c_mutex_and_frame(
+      Primitive.call_with_cext_lock_and_frame(
         POINTER_TO_VOID_WRAPPER, [func, data],
         Primitive.caller_special_variables_if_available, nil)
     end
@@ -1733,7 +1737,7 @@ def RTYPEDDATA(object)
   private def data_sizer(sizer_function, rtypeddata)
     raise unless sizer_function.respond_to?(:call)
     proc {
-      Primitive.call_with_c_mutex_and_frame(
+      Primitive.call_with_cext_lock_and_frame(
         POINTER_TO_SIZE_T_WRAPPER, [sizer_function, rtypeddata],
         Primitive.caller_special_variables_if_available, nil)
     }
@@ -1775,7 +1779,7 @@ def rb_data_typed_object_wrap(ruby_class, data, data_type, mark, free, size)
   end
 
   def run_data_finalizer(function, data)
-    Primitive.call_with_c_mutex_and_frame POINTER_TO_VOID_WRAPPER, [function, data], nil, nil
+    Primitive.call_with_cext_lock_and_frame POINTER_TO_VOID_WRAPPER, [function, data], nil, nil
   end
 
   def run_marker(obj)
@@ -1832,7 +1836,7 @@ def send_splatted(object, method, args)
 
   def rb_block_call(object, method, args, func, data)
     object.__send__(method, *args) do |*block_args|
-      Primitive.cext_unwrap(Primitive.call_with_c_mutex(RB_BLOCK_CALL_FUNC_WRAPPER, [ # Probably need to save the frame here for blocks.
+      Primitive.cext_unwrap(Primitive.call_with_cext_lock(RB_BLOCK_CALL_FUNC_WRAPPER, [ # Probably need to save the frame here for blocks.
         func,
         Primitive.cext_wrap(block_args.first),
         data,
@@ -1917,7 +1921,7 @@ def rb_exec_recursive(func, obj, arg)
 
   def rb_catch_obj(tag, func, data)
     catch tag do |caught|
-      Primitive.cext_unwrap(Primitive.call_with_c_mutex(RB_BLOCK_CALL_FUNC_WRAPPER, [
+      Primitive.cext_unwrap(Primitive.call_with_cext_lock(RB_BLOCK_CALL_FUNC_WRAPPER, [
         func,
         Primitive.cext_wrap(caught),
         Primitive.cext_wrap(data),
@@ -2003,12 +2007,12 @@ def rb_time_interval_acceptable(time_val)
 
   def rb_thread_create(fn, args)
     Thread.new do
-      Primitive.call_with_c_mutex_and_frame(POINTER_TO_POINTER_WRAPPER, [fn, args], Primitive.caller_special_variables_if_available, nil)
+      Primitive.call_with_cext_lock_and_frame(POINTER_TO_POINTER_WRAPPER, [fn, args], Primitive.caller_special_variables_if_available, nil)
     end
   end
 
   def rb_thread_call_with_gvl(function, data)
-    Primitive.call_with_c_mutex(POINTER_TO_POINTER_WRAPPER, [function, data])
+    Primitive.call_with_cext_lock(POINTER_TO_POINTER_WRAPPER, [function, data])
   end
 
   def rb_thread_call_without_gvl(function, data1, unblock, data2)
@@ -2033,7 +2037,7 @@ def rb_thread_call_without_gvl(function, data1, unblock, data2)
   def rb_iterate(iteration, iterated_object, callback, callback_arg)
     block = rb_block_proc
     wrapped_callback = proc do |block_arg|
-      Primitive.call_with_c_mutex_and_frame_and_unwrap(RB_BLOCK_CALL_FUNC_WRAPPER, [
+      Primitive.call_with_cext_lock_and_frame_and_unwrap(RB_BLOCK_CALL_FUNC_WRAPPER, [
         callback,
         Primitive.cext_wrap(block_arg),
         Primitive.cext_wrap(callback_arg),
@@ -2043,7 +2047,7 @@ def rb_iterate(iteration, iterated_object, callback, callback_arg)
       ], Primitive.cext_special_variables_from_stack, block)
     end
     Primitive.cext_unwrap(
-      Primitive.call_with_c_mutex_and_frame(POINTER_TO_POINTER_WRAPPER, [
+      Primitive.call_with_cext_lock_and_frame(POINTER_TO_POINTER_WRAPPER, [
         iteration,
         Primitive.cext_wrap(iterated_object)
       ], Primitive.cext_special_variables_from_stack, wrapped_callback))
@@ -2145,15 +2149,15 @@ def rb_define_hooked_variable(name, gvar, getter, setter)
     id = name.to_sym
 
     getter_proc = -> {
-      Primitive.call_with_c_mutex_and_frame_and_unwrap(
+      Primitive.call_with_cext_lock_and_frame_and_unwrap(
         POINTER2_TO_POINTER_WRAPPER,
         [getter, Primitive.cext_wrap(id), gvar],
         Primitive.caller_special_variables_if_available,
         nil)
     }
 
     setter_proc = -> _, value {
-      Primitive.call_with_c_mutex_and_frame(
+      Primitive.call_with_cext_lock_and_frame(
         POINTER3_TO_VOID_WRAPPER,
         [setter, Primitive.cext_wrap(value), Primitive.cext_wrap(id), gvar],
         Primitive.caller_special_variables_if_available,
@@ -2282,7 +2286,7 @@ def rb_fiber_current
 
   def rb_fiber_new(function, value)
     Fiber.new do |*args|
-      Primitive.call_with_c_mutex_and_frame_and_unwrap(RB_BLOCK_CALL_FUNC_WRAPPER, [
+      Primitive.call_with_cext_lock_and_frame_and_unwrap(RB_BLOCK_CALL_FUNC_WRAPPER, [
         function,
         Primitive.cext_wrap(args.first), # yieldarg
         nil, # procarg,

lib/truffle/truffle/cext_ruby.rb

@@ -21,6 +21,7 @@ def rb_define_method(mod, name, function, argc)
     end
 
     wrapper = RB_DEFINE_METHOD_WRAPPERS[argc]
+    thread_safe = Primitive.cext_thread_safe?
     method_body = Truffle::Graal.copy_captured_locals -> *args, &block do
       if argc == -1 # (int argc, VALUE *argv, VALUE obj)
         args = [function, args.size, Truffle::CExt.RARRAY_PTR(args), Primitive.cext_wrap(self)]
@@ -35,7 +36,11 @@ def rb_define_method(mod, name, function, argc)
 
       # We must set block argument if given here so that the
       # `rb_block_*` functions will be able to find it by walking the stack.
-      Primitive.call_with_c_mutex_and_frame_and_unwrap(wrapper, args, Primitive.caller_special_variables_if_available, block)
+      if thread_safe
+        Primitive.call_with_frame_and_unwrap(wrapper, args, Primitive.caller_special_variables_if_available, block)
+      else
+        Primitive.call_with_cext_lock_and_frame_and_unwrap(wrapper, args, Primitive.caller_special_variables_if_available, block)
+      end
     end
 
     # Even if the argc is -2, the arity number

spec/truffle/capi/cext_lock_spec.rb

@@ -1,3 +1,5 @@
+# truffleruby_primitives: true
+
 # Copyright (c) 2021, 2025 Oracle and/or its affiliates. All rights reserved. This
 # code is released under a tri EPL/GPL/LGPL license. You can use it,
 # redistribute it and/or modify it under the terms of the:
@@ -16,7 +18,7 @@
   end
 
   it "is not acquired in Ruby code" do
-    Truffle::CExt.cext_lock_owned?.should == false
+    Primitive.cext_lock_owned?.should == false
   end
 
   guard -> { Truffle::Boot.get_option 'cexts-lock' } do
@@ -32,4 +34,9 @@
   it "is released inside rb_funcall" do
     @t.has_lock_in_rb_funcall?.should == false
   end
+
+  it "is not acquired for methods defined in rb_ext_ractor_safe(true) extensions" do
+    @t.has_lock_for_rb_define_method_after_rb_ext_ractor_safe?.should == false
+    @t.has_lock_for_rb_define_method_after_rb_ext_ractor_safe_false?.should == true
+  end
 end

spec/truffle/capi/ext/truffleruby_lock_spec.c

@@ -30,7 +30,15 @@ static VALUE has_lock_in_call_without_gvl(VALUE self) {
 }
 
 static VALUE has_lock_in_rb_funcall(VALUE self) {
-  return rb_funcall(truffleCExt, rb_intern("cext_lock_owned?"), 0);
+  return rb_funcall(truffleCExt, rb_intern("rb_tr_cext_lock_owned_p"), 0);
+}
+
+static VALUE has_lock_for_rb_define_method_after_rb_ext_ractor_safe(VALUE self) {
+  return rb_tr_cext_lock_owned_p();
+}
+
+static VALUE has_lock_for_rb_define_method_after_rb_ext_ractor_safe_false(VALUE self) {
+  return rb_tr_cext_lock_owned_p();
 }
 
 void Init_truffleruby_lock_spec(void) {
@@ -39,6 +47,11 @@ void Init_truffleruby_lock_spec(void) {
   rb_define_method(cls, "has_lock?", has_lock, 0);
   rb_define_method(cls, "has_lock_in_call_without_gvl?", has_lock_in_call_without_gvl, 0);
   rb_define_method(cls, "has_lock_in_rb_funcall?", has_lock_in_rb_funcall, 0);
+
+  rb_ext_ractor_safe(true);
+  rb_define_method(cls, "has_lock_for_rb_define_method_after_rb_ext_ractor_safe?", has_lock_for_rb_define_method_after_rb_ext_ractor_safe, 0);
+  rb_ext_ractor_safe(false);
+  rb_define_method(cls, "has_lock_for_rb_define_method_after_rb_ext_ractor_safe_false?", has_lock_for_rb_define_method_after_rb_ext_ractor_safe_false, 0);
 }
 
 #ifdef __cplusplus

src/main/c/cext/ractor.c

@@ -12,12 +12,12 @@
 
 // Ractor, rb_ractor_*
 
-// Because of a mix of #if HAVE_RB_EXT_RACTOR_SAFE and #ifdef HAVE_RB_EXT_RACTOR_SAFE,
-// we cannot just leave HAVE_RB_EXT_RACTOR_SAFE undefined or defined to 0 without getting
-// -Wundef warnings & errors. So we let it defined to 1 but rb_ext_ractor_safe() has no effect.
-// Also rb_ext_ractor_safe() is sometimes called directly instead of RB_EXT_RACTOR_SAFE().
 void rb_ext_ractor_safe(bool flag) {
-  // No-op
+  rb_ext_thread_safe(flag);
+}
+
+void rb_ext_thread_safe(bool flag) {
+  polyglot_invoke(RUBY_CEXT, "set_thread_safe", flag);
 }
 
 // Simplified to main Ractor only

src/main/c/cext/truffleruby.c

@@ -39,7 +39,7 @@ VALUE rb_tr_zlib_crc_table(void) {
 }
 
 VALUE rb_tr_cext_lock_owned_p(void) {
-  return RUBY_CEXT_INVOKE("cext_lock_owned?");
+  return RUBY_CEXT_INVOKE("rb_tr_cext_lock_owned_p?");
 }
 
 // Used for internal testing