[GR-27379] Run C extensions marked as rb_ext_ractor_safe()/rb_ext_thread_safe() without the C extension lock (#2136)

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,75 @@
+---
+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()` (the latter is 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
+}
+```
+
+It is possible to mark individual methods as Ractor/Thread-safe by using `rb_ext_ractor_safe/rb_ext_thread_safe(true/false)` around them (these functions actually set a Fiber-local flag):
+```c
+void Init_my_extension(void) {
+    #ifdef HAVE_RB_EXT_RACTOR_SAFE
+    rb_ext_ractor_safe(true);
+    #endif
+    rb_define_method(myClass, "ractor_safe_method", foo_impl, 0); // The C function foo_impl can be called from multiple threads in parallel
+    // more Ractor-safe methods
+
+    #ifdef HAVE_RB_EXT_RACTOR_SAFE
+    rb_ext_ractor_safe(false);
+    #endif
+    rb_define_method(myClass, "ractor_unsafe_method", bar_impl, 0); // The C function bar_impl needs a global extension lock for correctness
+    // more Ractor-unsafe methods
+}
+```
+
+Other Ruby C API functions taking a C function like `rb_proc_new()` do not use the global extension lock if:
+* Called inside the `Init_my_extension` and `rb_ext_ractor_safe(true)` / `rb_ext_thread_safe(true)` are used.
+* Called outside the `Init_my_extension` and the calling function does not hold the global extension lock.
+
+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/cext/include/truffleruby/truffleruby-abi-version.h

@@ -20,6 +20,6 @@
 // $RUBY_VERSION must be the same as TruffleRuby.LANGUAGE_VERSION.
 // $ABI_NUMBER starts at 1 and is incremented for every ABI-incompatible change.
 
-#define TRUFFLERUBY_ABI_VERSION "3.3.7.2"
+#define TRUFFLERUBY_ABI_VERSION "3.3.7.3"
 
 #endif