|author||Trey Evans <firstname.lastname@example.org>||2022-01-09 14:16:02 -0500|
|committer||Benoit Daloze <email@example.com>||2022-01-10 13:04:31 +0100|
Clarify ractor documentation meaning and formatting.
Notes: Merged: https://github.com/ruby/ruby/pull/5421
Diffstat (limited to 'doc')
1 files changed, 18 insertions, 21 deletions
diff --git a/doc/extension.rdoc b/doc/extension.rdoc
index 837e35b369..b4b34b86de 100644
@@ -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
+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.
-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
:enddoc: Local variables:
:enddoc: fill-column: 70