1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>
Module: Concurrent::Synchronization
— Concurrent
</title>
<link rel="stylesheet" href="../css/style.css" type="text/css" charset="utf-8" />
<link rel="stylesheet" href="../css/common.css" type="text/css" charset="utf-8" />
<script type="text/javascript" charset="utf-8">
hasFrames = window.top.frames.main ? true : false;
relpath = '../';
framesUrl = "../frames.html#!Concurrent/Synchronization.html";
</script>
<script type="text/javascript" charset="utf-8" src="../js/jquery.js"></script>
<script type="text/javascript" charset="utf-8" src="../js/app.js"></script>
</head>
<body>
<div id="header">
<div id="menu">
<a href="../_index.html">Index (S)</a> »
<span class='title'><span class='object_link'><a href="../root/Concurrent.html" title="Concurrent (module)">Concurrent</a></span></span>
»
<span class="title">Synchronization</span>
<div class="noframes"><span class="title">(</span><a href="." target="_top">no frames</a><span class="title">)</span></div>
</div>
<div id="search">
<a class="full_list_link" id="class_list_link"
href="../class_list.html">
Class List
</a>
<a class="full_list_link" id="method_list_link"
href="../method_list.html">
Method List
</a>
<a class="full_list_link" id="file_list_link"
href="../file_list.html">
File List
</a>
</div>
<div class="clear"></div>
</div>
<iframe id="search_frame"></iframe>
<div id="content"><h1>Module: Concurrent::Synchronization
</h1>
<dl class="box">
<dt class="r1 last">Defined in:</dt>
<dd class="r1 last">lib/concurrent/synchronization.rb<span class="defines">,<br />
lib/concurrent/synchronization/lock.rb,<br /> lib/concurrent/synchronization/object.rb,<br /> lib/concurrent/synchronization/volatile.rb,<br /> lib/concurrent/synchronization/condition.rb,<br /> lib/concurrent/synchronization/mri_object.rb,<br /> lib/concurrent/synchronization/rbx_object.rb,<br /> lib/concurrent/synchronization/jruby_object.rb,<br /> lib/concurrent/synchronization/truffle_object.rb,<br /> lib/concurrent/synchronization/lockable_object.rb,<br /> lib/concurrent/synchronization/abstract_struct.rb,<br /> lib/concurrent/synchronization/abstract_object.rb,<br /> lib/concurrent/synchronization/rbx_lockable_object.rb,<br /> lib/concurrent/synchronization/mri_lockable_object.rb,<br /> lib/concurrent/synchronization/jruby_lockable_object.rb,<br /> lib/concurrent/synchronization/truffle_lockable_object.rb,<br /> lib/concurrent/synchronization/abstract_lockable_object.rb</span>
</dd>
</dl>
<div class="clear"></div>
<h2>Overview</h2><div class="docstring">
<div class="discussion">
<p><h1>Synchronization</h1>
<p><a href="https://docs.google.com/document/d/1pVzU8w_QF44YzUCCab990Q_WZOdhpKolCIHaiXG-sPw/edit?usp=sharing">This document</a>
is moved to Google documents. It will be moved here once final and stabilized.</p>
<h1>Concurrent Ruby Notes</h1>
<h2>Locks</h2>
<p>Concurrent Ruby also has an internal extension of <code>Object</code> called
<code>LockableObject</code>, which provides same synchronization primitives as Java's
Object: <code>synchronize(&block)</code>, <code>wait(timeout = nil)</code>,
<code>wait_until(timeout = nil, &condition)</code>, <code>signal</code>, <code>broadcast</code>. This class is
intended for internal use in <code>concurrent-ruby</code> only and it does not support
subclassing (since it cannot protect its lock from its children, for more
details see <a href="http://wiki.apidesign.org/wiki/Java_Monitor">this article</a>). It has
minimal interface to be able to use directly locking available on given
platforms.</p>
<p>For non-internal use there is <code>Lock</code> and <code>Condition</code> implementation in
<code>Synchronization</code> namespace, a condition can be obtained with <code>new_condition</code>
method on <code>Lock</code>. So far their implementation is naive and requires more work.
API is not expected to change.</p>
<h2>Method names conventions</h2>
<p>Methods starting with <code>ns_</code> are marking methods that are not using
synchronization by themselves, they have to be used inside synchronize block.
They are usually used in pairs to separate the synchronization from behavior and
to allow to call methods in the same object without double locking.</p>
<pre class="code ruby"><code class="ruby"><span class='kw'>class</span> <span class='const'>Node</span>
<span class='comment'># ...
</span> <span class='kw'>def</span> <span class='id identifier rubyid_left'>left</span>
<span class='id identifier rubyid_synchronize'>synchronize</span> <span class='lbrace'>{</span> <span class='id identifier rubyid_ns_left'>ns_left</span> <span class='rbrace'>}</span>
<span class='kw'>end</span>
<span class='kw'>def</span> <span class='id identifier rubyid_right'>right</span>
<span class='id identifier rubyid_synchronize'>synchronize</span> <span class='lbrace'>{</span> <span class='id identifier rubyid_ns_right'>ns_right</span> <span class='rbrace'>}</span>
<span class='kw'>end</span>
<span class='kw'>def</span> <span class='id identifier rubyid_to_a'>to_a</span>
<span class='comment'># avoids double locking
</span> <span class='id identifier rubyid_synchronize'>synchronize</span> <span class='lbrace'>{</span> <span class='lbracket'>[</span><span class='id identifier rubyid_ns_left'>ns_left</span><span class='comma'>,</span> <span class='id identifier rubyid_ns_right'>ns_right</span><span class='rbracket'>]</span> <span class='rbrace'>}</span>
<span class='kw'>end</span>
<span class='id identifier rubyid_private'>private</span>
<span class='kw'>def</span> <span class='id identifier rubyid_ns_left'>ns_left</span>
<span class='ivar'>@left</span>
<span class='kw'>end</span>
<span class='kw'>def</span> <span class='id identifier rubyid_ns_right'>ns_right</span>
<span class='ivar'>@right</span>
<span class='kw'>end</span>
<span class='comment'># ...
</span><span class='kw'>end</span>
</code></pre>
<h2>Piggybacking</h2>
<p>Any write executed before volatile write based on program-order is visible to
the volatile read as well, which allows
<a href="http://stackoverflow.com/questions/8769570/volatile-piggyback-is-this-enough-for-visiblity">piggybacking</a>.
Because it creates synchronizes-with (JMM term) order between volatile write
and read, which participates in creating happens-before order.</p>
<p>This trick is used in some of the abstractions, to avoid unnecessary
synchronization or volatile declarations.</p>
</p>
</div>
</div>
<div class="tags">
</div><h2>Defined Under Namespace</h2>
<p class="children">
<strong class="modules">Modules:</strong> <span class='object_link'><a href="Synchronization/JRubyAttrVolatile.html" title="Concurrent::Synchronization::JRubyAttrVolatile (module)">JRubyAttrVolatile</a></span>, <span class='object_link'><a href="Synchronization/MriAttrVolatile.html" title="Concurrent::Synchronization::MriAttrVolatile (module)">MriAttrVolatile</a></span>, <span class='object_link'><a href="Synchronization/RbxAttrVolatile.html" title="Concurrent::Synchronization::RbxAttrVolatile (module)">RbxAttrVolatile</a></span>, <span class='object_link'><a href="Synchronization/TruffleAttrVolatile.html" title="Concurrent::Synchronization::TruffleAttrVolatile (module)">TruffleAttrVolatile</a></span>
<strong class="classes">Classes:</strong> <span class='object_link'><a href="Synchronization/Condition.html" title="Concurrent::Synchronization::Condition (class)">Condition</a></span>, <span class='object_link'><a href="Synchronization/Lock.html" title="Concurrent::Synchronization::Lock (class)">Lock</a></span>, <span class='object_link'><a href="Synchronization/Object.html" title="Concurrent::Synchronization::Object (class)">Object</a></span>, <span class='object_link'><a href="Synchronization/TruffleLockableObject.html" title="Concurrent::Synchronization::TruffleLockableObject (class)">TruffleLockableObject</a></span>
</p>
<h2>Constant Summary</h2>
<dl class="constants">
<dt id="Volatile-constant" class="">Volatile =
<div class="docstring">
<div class="discussion">
<p>Volatile adds the attr_volatile class method when included.</p>
<p>foo = Foo.new
foo.bar
=> 1
foo.bar = 2
=> 2</p>
</div>
</div>
<div class="tags">
<div class="examples">
<p class="tag_title">Examples:</p>
<pre class="example code"><code><span class='kw'>class</span> <span class='const'>Foo</span>
<span class='id identifier rubyid_include'>include</span> <span class='const'>Concurrent</span><span class='op'>::</span><span class='const'>Synchronization</span><span class='op'>::</span><span class='const'>Volatile</span>
<span class='id identifier rubyid_attr_volatile'>attr_volatile</span> <span class='symbol'>:bar</span>
<span class='kw'>def</span> <span class='id identifier rubyid_initialize'>initialize</span>
<span class='kw'>self</span><span class='period'>.</span><span class='id identifier rubyid_bar'>bar</span> <span class='op'>=</span> <span class='int'>1</span>
<span class='kw'>end</span>
<span class='kw'>end</span></code></pre>
</div>
</div>
</dt>
<dd><pre class="code"><span class='kw'>case</span>
<span class='kw'>when</span> <span class='const'>Concurrent</span><span class='period'>.</span><span class='id identifier rubyid_on_cruby?'>on_cruby?</span>
<span class='const'>MriAttrVolatile</span>
<span class='kw'>when</span> <span class='const'>Concurrent</span><span class='period'>.</span><span class='id identifier rubyid_on_jruby?'>on_jruby?</span>
<span class='const'>JRubyAttrVolatile</span>
<span class='kw'>when</span> <span class='const'>Concurrent</span><span class='period'>.</span><span class='id identifier rubyid_on_rbx?'>on_rbx?</span> <span class='op'>||</span> <span class='const'>Concurrent</span><span class='period'>.</span><span class='id identifier rubyid_on_truffle?'>on_truffle?</span>
<span class='const'>RbxAttrVolatile</span>
<span class='kw'>else</span>
<span class='const'>MriAttrVolatile</span>
<span class='kw'>end</span></pre></dd>
</dl>
</div>
<div id="footer">
Generated on Wed Aug 15 13:38:40 2018 by
<a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
0.8.7.6 (ruby-2.4.3).
</div>
<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-57940973-1', 'auto');
ga('send', 'pageview');
</script>
</body>
</html>
|
