ruby-changes:70802
From: Trey <ko1@a...>
Date: Mon, 10 Jan 2022 21:04:50 +0900 (JST)
Subject: [ruby-changes:70802] b4d0d07e2c (master): Clarify ractor documentation meaning and formatting.
https://git.ruby-lang.org/ruby.git/commit/?id=b4d0d07e2c From b4d0d07e2c1ad21297a286601dcc9ec2ab068b69 Mon Sep 17 00:00:00 2001 From: Trey Evans <lewis.r.evans@g...> Date: Sun, 9 Jan 2022 14:16:02 -0500 Subject: Clarify ractor documentation meaning and formatting. --- doc/extension.rdoc | 39 ++++++++++++++++++--------------------- 1 file changed, 18 insertions(+), 21 deletions(-) diff --git a/doc/extension.rdoc b/doc/extension.rdoc index 837e35b369e..b4b34b86de9 100644 --- a/doc/extension.rdoc +++ b/doc/extension.rdoc @@ -2127,24 +2127,20 @@ keyword in C. RB_GC_GUARD has the following advantages: https://github.com/ruby/ruby/blob/trunk/doc/extension.rdoc#L2127 == 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 https://github.com/ruby/ruby/blob/trunk/doc/extension.rdoc#L2183 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. https://github.com/ruby/ruby/blob/trunk/doc/extension.rdoc#L2201 (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 -- cgit v1.2.1 -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/