diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/extension.rdoc | 39 |
1 files changed, 18 insertions, 21 deletions
diff --git a/doc/extension.rdoc b/doc/extension.rdoc index 837e35b369..b4b34b86de 100644 --- a/doc/extension.rdoc +++ b/doc/extension.rdoc @@ -2127,24 +2127,20 @@ keyword in C. RB_GC_GUARD has the following advantages: == Appendix F. Ractor support -Ractor is parallel execution mechanism introduced from Ruby 3.0. All -ractrors can run in parallel by different OS thread (underlying system -provided thread), so the C extension should be thread-safe. Now we call -the property that C extension can run in multiple ractors "Ractor-safe". +Ractor(s) are the parallel execution mechanism introduced in Ruby 3.0. All +ractors can run in parallel on a different OS thread (using an underlying system +provided thread), so the C extension should be thread-safe. A C extension that +can run in multiple ractors is called "Ractor-safe". -By default, all C extensions are recognized as Ractor-unsafe. If C -extension becomes Ractor-safe, the extension should call -rb_ext_ractor_safe(true) at the Init_ function and all defined method -marked as Ractor-safe. Ractor-unsafe C-methods only been called from -main-ractor. If non-main ractor calls it, then Ractor::UnsafeError is -raised. +Ractor safety around C extensions has the following properties: +1. By default, all C extensions are recognized as Ractor-unsafe. +2. Ractor-unsafe C-methods may only be called from the main Ractor. If invoked + by a non-main Ractor, then a Ractor::UnsafeError is raised. +3. If an extension desires to be marked as Ractor-safe the extension should + call rb_ext_ractor_safe(true) at the Init_ function for the extension, and + all defined methods will be marked as Ractor-safe. -BTW non-"Ractor-safe" extensions raises an error on non-main ractors, so -that it is "safe" because unsafe operations are not allowed. -"Ractor-safe" property means "multi-Ractor-ready" or "safe on -multi-ractors execution". "Ractor-safe" term comes from "Thread-safe". - -To make "Ractor-safe" C extension, we need to check the following points: +To make a "Ractor-safe" C extension, we need to check the following points: (1) Do not share unshareable objects between ractors @@ -2187,10 +2183,10 @@ or the receiver are isolated by Ractor's boundary, it is easy to make thread-safe code than usual thread-programming in general. For example, we don't need to lock an array object to access the element of it. -(3) Check the thread-safety of using library +(3) Check the thread-safety of any used library -If an extension relies on the external library libfoo and the function -foo(), the function foo() should be thread safe. +If the extension relies on an external library, such as a function foo() from +a library libfoo, the function libfoo foo() should be thread safe. (4) Make an object shareable @@ -2205,8 +2201,9 @@ is frozen, the mutation of wrapped data is not allowed. (5) Others -Maybe there are more points which should be considered to make -Ractor-safe extension, so this document will be extended. +There are possibly other points or requirements which must be considered in the +making of a Ractor-safe extension. This document will be extended as they are +discovered. :enddoc: Local variables: :enddoc: fill-column: 70 |