You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: doc/user/compatibility.md
+9
Original file line number
Diff line number
Diff line change
@@ -194,6 +194,15 @@ To help alleviate this problem, backtraces are automatically disabled in cases w
194
194
195
195
## C Extension Compatibility
196
196
197
+
### Global Extension Lock
198
+
199
+
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).
200
+
201
+
Extensions can mark themselves as thread-safe either by using `rb_ext_ractor_safe()` or `rb_ext_thread_safe()`.
202
+
Such extensions are then run by TruffleRuby without a global extension lock, i.e. in parallel.
203
+
204
+
See [Thread-Safe Extensions](thread-safe-extensions.md) for how to mark extensions as Ractor-safe or thread-safe.
205
+
197
206
### Identifiers may be macros or functions
198
207
199
208
Identifiers which are normally macros may be functions, functions may be macros, and global variables may be macros.
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).
10
+
11
+
Extensions can mark themselves as thread-safe either by using `rb_ext_ractor_safe()` or `rb_ext_thread_safe()` (TruffleRuby-specific).
12
+
Such extensions are then run by TruffleRuby without a global extension lock, i.e. in parallel.
13
+
14
+
Here is an example of an extension marking itself as Ractor-safe.
15
+
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-).
16
+
```c
17
+
voidInit_my_extension(void) {
18
+
#ifdef HAVE_RB_EXT_RACTOR_SAFE
19
+
rb_ext_ractor_safe(true);
20
+
#endif
21
+
22
+
rb_define_method(myClass, "foo", foo_impl, 0); // The C function foo_impl can be called from multiple threads in parallel
23
+
}
24
+
```
25
+
26
+
Here is an example of an extension marking itself as thread-safe:
27
+
```c
28
+
void Init_my_extension(void) {
29
+
#ifdef HAVE_RB_EXT_THREAD_SAFE
30
+
rb_ext_thread_safe(true);
31
+
#endif
32
+
33
+
rb_define_method(myClass, "foo", foo_impl, 0); // The C function foo_impl can be called from multiple threads in parallel
34
+
}
35
+
```
36
+
37
+
The conditions for an extension to be thread-safe are the following.
38
+
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.
39
+
1. The extension should make it clear in its documentation which objects are safe to share between threads and which are not.
40
+
This already needs to be done on CRuby with the GVL, as threads run concurrently.
41
+
It helps gem users to avoid sharing objects between threads incorrectly.
42
+
2. The extension's own code must be thread-safe, e.g. not mutate state shared between threads without synchronization.
43
+
For example accesses to a `struct` shared between threads should typically be synchronized if it's not immutable.
44
+
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).
45
+
4. Ruby C API functions/macros (like `rb_*()`) are generally thread-safe on TruffleRuby, because most of them end up calling some Ruby method.
46
+
47
+
These are the differences in comparison to Ractor-safe:
48
+
* 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.
49
+
* There is no need to mark objects as Ractor-shareable.
50
+
51
+
Another way to look at this is to reason about the guarantees that a global extension lock provides:
52
+
* 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.
53
+
* 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".
54
+
* 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.
0 commit comments