kotovalexarian-likes-github/ruby--ruby
1
0
Fork 0
mirror of https://github.com/ruby/ruby.git synced 2022-11-09 12:17:21 -05:00
Code Releases 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
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
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