1berry/ruby
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Clarify ractor documentation meaning and formatting.

Browse Source
This commit is contained in:
Trey Evans 2022-01-09 14:16:02 -05:00 committed by Benoit Daloze
parent 7b5d49a082
commit b4d0d07e2c
Notes: git 2022-01-10 21:04:59 +09:00 
Merged: https://github.com/ruby/ruby/pull/5421
1 changed files with 18 additions and 21 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

39
doc/extension.rdoc
View File

@ -2127,24 +2127,20 @@ keyword in C. RB_GC_GUARD has the following advantages:
== Appendix F. Ractor support == Appendix F. Ractor support
Ractor is parallel execution mechanism introduced from Ruby 3.0. All Ractor(s) are the parallel execution mechanism introduced in Ruby 3.0. All
ractrors can run in parallel by different OS thread (underlying system ractors can run in parallel on a different OS thread (using an underlying system
provided thread), so the C extension should be thread-safe. Now we call provided thread), so the C extension should be thread-safe. A C extension that
the property that C extension can run in multiple ractors "Ractor-safe". can run in multiple ractors is called "Ractor-safe".
By default, all C extensions are recognized as Ractor-unsafe. If C Ractor safety around C extensions has the following properties:
extension becomes Ractor-safe, the extension should call 1. By default, all C extensions are recognized as Ractor-unsafe.
rb_ext_ractor_safe(true) at the Init_ function and all defined method 2. Ractor-unsafe C-methods may only be called from the main Ractor. If invoked
marked as Ractor-safe. Ractor-unsafe C-methods only been called from by a non-main Ractor, then a Ractor::UnsafeError is raised.
main-ractor. If non-main ractor calls it, then Ractor::UnsafeError is 3. If an extension desires to be marked as Ractor-safe the extension should
raised. 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 To make a "Ractor-safe" C extension, we need to check the following points:
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:
(1) Do not share unshareable objects between ractors (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, 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. 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 If the extension relies on an external library, such as a function foo() from
foo(), the function foo() should be thread safe. a library libfoo, the function libfoo foo() should be thread safe.
(4) Make an object shareable (4) Make an object shareable
@ -2205,8 +2201,9 @@ is frozen, the mutation of wrapped data is not allowed.
(5) Others (5) Others
Maybe there are more points which should be considered to make There are possibly other points or requirements which must be considered in the
Ractor-safe extension, so this document will be extended. making of a Ractor-safe extension. This document will be extended as they are
discovered.
:enddoc: Local variables: :enddoc: Local variables:
:enddoc: fill-column: 70 :enddoc: fill-column: 70