Clarify ractor documentation meaning and formatting.

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