summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorKoichi Sasada <ko1@atdot.net>2020-12-24 10:59:27 +0900
committerKoichi Sasada <ko1@atdot.net>2020-12-24 14:28:47 +0900
commit6f29716f9ffb710af7f344839ec67ef2b8a48ab2 (patch)
tree296e34994f4670acfe02bca27e5a4864629a5248 /doc
parent1e215a66d26d56befab4fbb72e1d953879411955 (diff)
shareable_constant_value: experimental_copy
"experimental_everything" makes the assigned value, it means the assignment change the state of assigned value. "experimental_copy" tries to make a deep copy and make copyied object sharable.
Notes
Notes: Merged: https://github.com/ruby/ruby/pull/3989
Diffstat (limited to 'doc')
-rw-r--r--doc/syntax/comments.rdoc35
1 files changed, 30 insertions, 5 deletions
diff --git a/doc/syntax/comments.rdoc b/doc/syntax/comments.rdoc
index 6ce8fa1..a808ca8 100644
--- a/doc/syntax/comments.rdoc
+++ b/doc/syntax/comments.rdoc
@@ -125,6 +125,7 @@ The directive can specify special treatment for values assigned to constants:
* +none+: (default)
* +literal+: literals are implicitly frozen, others must be Ractor-shareable
* +experimental_everything+: all made shareable
+* +experimental_copy+: copy deeply and make it shareable
==== Mode +none+ (default)
@@ -168,22 +169,46 @@ The method Module#const_set is not affected.
In this mode, all values assigned to constants are made shareable.
# shareable_constant_value: experimental_everything
- FOO = Set.new[1, 2, {foo: []}] # => ok, since this is
- # same as `Set.new[1, 2, {foo: [].freeze}.freeze].freeze`
+ FOO = Set[1, 2, {foo: []}]
+ # same as FOO = Ractor.make_sharable(...)
+ # OR same as `FOO = Set[1, 2, {foo: [].freeze}.freeze].freeze`
var = [{foo: []}]
var.frozen? # => false (assignment was made to local variable)
X = var # => calls `Ractor.make_shareable(var)`
var.frozen? # => true
-This mode is "experimental", because it might be too error prone,
-for example by deep-freezing the constants of an external resource
-which could cause errors:
+This mode is "experimental", because it might be error prone, for
+example by deep-freezing the constants of an external resource which
+could cause errors:
# shareable_constant_value: experimental_everything
FOO = SomeGem::Something::FOO
# => deep freezes the gem's constant!
+We will revisit to consider removing "experimental_" or removing this
+mode by checking usages before Ruby 3.1.
+
+The method Module#const_set is not affected.
+
+==== Mode +experimental_copy+
+
+In this mode, all values assigned to constants are copyied deeply and
+made shareable. It is safer mode than +experimental_everything+.
+
+ # shareable_constant_value: experimental_everything
+ var = [{foo: []}]
+ var.frozen? # => false (assignment was made to local variable)
+ X = var # => calls `Ractor.make_shareable(var, copy: true)`
+ var.frozen? # => false
+ Ractor.shareable?(var) #=> false
+ Ractor.shareable?(X) #=> true
+ var.object_id == X.object_id #=> false
+
+This mode is "experimental", because it is not discussed enough.
+We will revisit to consider removing "experimental_" or removing this
+mode by checking usages before Ruby 3.1.
+
The method Module#const_set is not affected.
==== Scope