Skip to content

Adds WrappingExecutor with docs #830

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Jan 19, 2020
Merged

Adds WrappingExecutor with docs #830

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
b6dd12d
Adds WrappingExecutor class
petrblaho Oct 6, 2019
0d4da5e
Generates docs for WrappingExecutor
petrblaho Oct 6, 2019
7ed73c8
Update documentation
pitr-ch Nov 17, 2019
03b75fd
Move to edge
pitr-ch Dec 27, 2019
d794b95
Load WrappingExecutor only on newer Ruby
pitr-ch Dec 27, 2019
69e6f5d
Add link to readme
pitr-ch Jan 19, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -253,6 +253,9 @@ be obeyed though. Features developed in `concurrent-ruby-edge` are expected to m
* [ErlangActor](http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/ErlangActor.html)
Actor implementation which precisely matches Erlang actor behaviour.
Requires at least Ruby 2.1 otherwise it's not loaded.
* [WrappingExecutor](http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/WrappingExecutor.html)
A delegating executor which modifies each task before the task is given to
the target executor it delegates to.

## Supported Ruby versions

Expand Down
30 changes: 15 additions & 15 deletions docs-source/channel.out.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,8 +16,8 @@ threads = Array.new(3) { |i| Thread.new { ch.push message: i } }
sleep 0.01 # let the threads run
threads
# => [#<Thread:0x000003@channel.in.md:14 dead>,
# #<Thread:0x000004@channel.in.md:14 dead>,
# #<Thread:0x000005@channel.in.md:14 sleep_forever>]
# #<Thread:0x000004@channel.in.md:14 sleep_forever>,
# #<Thread:0x000005@channel.in.md:14 dead>]
```

When message is popped the last thread continues and finishes as well.
Expand Down Expand Up @@ -45,7 +45,7 @@ threads
ch.push message: 3
# => #<Concurrent::Promises::Channel:0x000002 capacity taken 0 of 2>
threads.map(&:value)
# => [{:message=>1}, {:message=>2}, {:message=>3}]
# => [{:message=>2}, {:message=>1}, {:message=>3}]
```

### Promises integration
Expand Down Expand Up @@ -204,16 +204,16 @@ log
# "producer 0 pushing 2",
# "producer 1 pushing 0",
# "consumer 0 got 0. payload 0 from producer 0",
# "producer 0 pushing 3",
# "consumer 1 got 0. payload 1 from producer 0",
# "producer 1 pushing 1",
# "consumer 2 got 0. payload 2 from producer 0",
# "consumer 3 got 0. payload 0 from producer 1",
# "producer 0 pushing 3",
# "producer 1 pushing 1",
# "producer 1 pushing 2",
# "consumer 0 got 1. payload 3 from producer 0",
# "consumer 1 got 1. payload 1 from producer 1",
# "consumer 3 got 1. payload 2 from producer 1",
# "producer 1 pushing 3",
# "consumer 3 got 1. payload 1 from producer 1",
# "consumer 1 got 1. payload 2 from producer 1",
# "consumer 2 got 1. payload 3 from producer 1"]
```

Expand Down Expand Up @@ -268,20 +268,20 @@ consumers.map(&:value!) # => [:done, :done, :done, :done]
# investigate log
log
# => ["producer 0 pushing 0",
# "producer 1 pushing 0",
# "producer 0 pushing 1",
# "producer 1 pushing 0",
# "consumer 1 got 0. payload 1 from producer 0",
# "producer 0 pushing 2",
# "producer 0 pushing 3",
# "producer 1 pushing 1",
# "consumer 0 got 0. payload 0 from producer 0",
# "consumer 1 got 0. payload 0 from producer 1",
# "consumer 2 got 0. payload 1 from producer 0",
# "producer 0 pushing 2",
# "consumer 3 got 0. payload 1 from producer 1",
# "consumer 2 got 0. payload 0 from producer 1",
# "producer 1 pushing 2",
# "producer 0 pushing 3",
# "consumer 3 got 0. payload 2 from producer 0",
# "producer 1 pushing 3",
# "consumer 0 got 1. payload 2 from producer 0",
# "consumer 2 got 1. payload 2 from producer 1",
# "consumer 1 got 1. payload 3 from producer 0",
# "consumer 0 got 1. payload 1 from producer 1",
# "consumer 2 got 1. payload 2 from producer 1",
# "consumer 3 got 1. payload 3 from producer 1"]
```

Expand Down
2 changes: 1 addition & 1 deletion docs-source/erlang_actor.out.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ Although, `Promises.future { 1 + 1 }` is better suited for that purpose.

```ruby
actor = Concurrent::ErlangActor.spawn(type: :on_thread, name: 'addition') { 1 + 1 }
# => #<Concurrent::ErlangActor::Pid:0x000002 addition terminated normally with 2>
# => #<Concurrent::ErlangActor::Pid:0x000002 addition running>
actor.terminated.value! # => 2
```

Expand Down
869 changes: 507 additions & 362 deletions docs-source/medium-example.out.rb
View file
Open in desktop

Large diffs are not rendered by default.

11 changes: 11 additions & 0 deletions docs/js/app.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -275,6 +275,16 @@ function mainFocus() {
setTimeout(function() { $('#main').focus(); }, 10);
}

function navigationChange() {
// This works around the broken anchor navigation with the YARD template.
window.onpopstate = function() {
var hash = window.location.hash;
if (hash !== '' && $(hash)[0]) {
$(hash)[0].scrollIntoView();
}
};
}

$(document).ready(function() {
navResizer();
navExpander();
Expand All @@ -287,6 +297,7 @@ $(document).ready(function() {
constantSummaryToggle();
generateTOC();
mainFocus();
navigationChange();
});

})();
20 changes: 10 additions & 10 deletions docs/master/Concurrent.html
View file
Open in desktop

Large diffs are not rendered by default.

4 changes: 1 addition & 3 deletions docs/master/Concurrent/Actor.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -218,9 +218,7 @@ <h2>Sending messages</h2>
Sends the message asynchronously to the actor and immediately returns
<code>self</code> (the reference) allowing to chain message telling.</li>
<li> <span class='object_link'><a href="Actor/Reference.html#ask-instance_method" title="Concurrent::Actor::Reference#ask (method)">Reference#ask</a></span>
testing and when it returns very shortly. It can lead to deadlock if all threads in
global_io_executor will block on while asking. It&#39;s fine to use it form outside of actors and
global_io_executor.</li>
</li>
<li> <span class='object_link'><a href="Actor/Reference.html#ask!-instance_method" title="Concurrent::Actor::Reference#ask! (method)">Reference#ask!</a></span>
Sends the message synchronously and blocks until the message
is processed. Raises on error.</li>
Expand Down
74 changes: 33 additions & 41 deletions docs/master/Concurrent/Actor/Reference.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -177,7 +177,7 @@ <h2>



<span class="summary_desc"><div class='inline'><p>testing and when it returns very shortly.</p>
<span class="summary_desc"><div class='inline'><p>Supplied future.</p>
</div></span>

</li>
Expand Down Expand Up @@ -687,12 +687,12 @@ <h3 class="signature first" id="==-instance_method">
<pre class="lines">


100
101
102</pre>
95
96
97</pre>
</td>
<td>
<pre class="code"><span class="info file"># File 'lib-edge/concurrent/actor/reference.rb', line 100</span>
<pre class="code"><span class="info file"># File 'lib-edge/concurrent/actor/reference.rb', line 95</span>

<span class='kw'>def</span> <span class='op'>==</span><span class='lparen'>(</span><span class='id identifier rubyid_other'>other</span><span class='rparen'>)</span>
<span class='id identifier rubyid_Type?'>Type?</span> <span class='id identifier rubyid_other'>other</span><span class='comma'>,</span> <span class='kw'>self</span><span class='period'>.</span><span class='id identifier rubyid_class'>class</span> <span class='kw'>and</span> <span class='id identifier rubyid_other'>other</span><span class='period'>.</span><span class='id identifier rubyid_send'>send</span><span class='lparen'>(</span><span class='symbol'>:core</span><span class='rparen'>)</span> <span class='op'>==</span> <span class='id identifier rubyid_core'>core</span>
Expand Down Expand Up @@ -720,22 +720,14 @@ <h3 class="signature " id="ask-instance_method">

<div class="note notetag">
<strong>Note:</strong>
<div class='inline'><p>it&#39;s a good practice to use tell whenever possible. Ask should be used only for</p>
</div>
</div>

<div class="note notetag">
<strong>Note:</strong>
<div class='inline'><p>it&#39;s a good practice to use <span class='object_link'><a href="#tell-instance_method" title="Concurrent::Actor::Reference#tell (method)">#tell</a></span> whenever possible. Results can be send back with other messages.
<div class='inline'><p>it&#39;s a good practice to use <span class='object_link'><a href="#tell-instance_method" title="Concurrent::Actor::Reference#tell (method)">#tell</a></span> whenever possible. Results can be sent back with other messages.
Ask should be used only for testing and when it returns very shortly. It can lead to deadlock if all threads in
global_io_executor will block on while asking. It&#39;s fine to use it form outside of actors and
global_io_executor.</p>
</div>
</div>

<p>testing and when it returns very shortly. It can lead to deadlock if all threads in
global_io_executor will block on while asking. It&#39;s fine to use it form outside of actors and
global_io_executor.</p>
<p>Returns supplied future</p>


</div>
Expand Down Expand Up @@ -808,12 +800,12 @@ <h3 class="signature " id="ask-instance_method">
<pre class="lines">


54
55
56</pre>
49
50
51</pre>
</td>
<td>
<pre class="code"><span class="info file"># File 'lib-edge/concurrent/actor/reference.rb', line 54</span>
<pre class="code"><span class="info file"># File 'lib-edge/concurrent/actor/reference.rb', line 49</span>

<span class='kw'>def</span> <span class='id identifier rubyid_ask'>ask</span><span class='lparen'>(</span><span class='id identifier rubyid_message'>message</span><span class='comma'>,</span> <span class='id identifier rubyid_future'>future</span> <span class='op'>=</span> <span class='const'><span class='object_link'><a href="../../Concurrent.html" title="Concurrent (module)">Concurrent</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="../Promises.html" title="Concurrent::Promises (module)">Promises</a></span></span><span class='period'>.</span><span class='id identifier rubyid_resolvable_future'><span class='object_link'><a href="../Promises/FactoryMethods.html#resolvable_future-instance_method" title="Concurrent::Promises::FactoryMethods#resolvable_future (method)">resolvable_future</a></span></span><span class='rparen'>)</span>
<span class='id identifier rubyid_message'>message</span> <span class='id identifier rubyid_message'>message</span><span class='comma'>,</span> <span class='id identifier rubyid_future'>future</span>
Expand All @@ -837,7 +829,7 @@ <h3 class="signature " id="ask!-instance_method">

<div class="note notetag">
<strong>Note:</strong>
<div class='inline'><p>it&#39;s a good practice to use <span class='object_link'><a href="#tell-instance_method" title="Concurrent::Actor::Reference#tell (method)">#tell</a></span> whenever possible. Results can be send back with other messages.
<div class='inline'><p>it&#39;s a good practice to use <span class='object_link'><a href="#tell-instance_method" title="Concurrent::Actor::Reference#tell (method)">#tell</a></span> whenever possible. Results can be sent back with other messages.
Ask should be used only for testing and when it returns very shortly. It can lead to deadlock if all threads in
global_io_executor will block on while asking. It&#39;s fine to use it form outside of actors and
global_io_executor.</p>
Expand Down Expand Up @@ -934,12 +926,12 @@ <h3 class="signature " id="ask!-instance_method">
<pre class="lines">


75
76
77</pre>
70
71
72</pre>
</td>
<td>
<pre class="code"><span class="info file"># File 'lib-edge/concurrent/actor/reference.rb', line 75</span>
<pre class="code"><span class="info file"># File 'lib-edge/concurrent/actor/reference.rb', line 70</span>

<span class='kw'>def</span> <span class='id identifier rubyid_ask!'>ask!</span><span class='lparen'>(</span><span class='id identifier rubyid_message'>message</span><span class='comma'>,</span> <span class='id identifier rubyid_future'>future</span> <span class='op'>=</span> <span class='const'><span class='object_link'><a href="../../Concurrent.html" title="Concurrent (module)">Concurrent</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="../Promises.html" title="Concurrent::Promises (module)">Promises</a></span></span><span class='period'>.</span><span class='id identifier rubyid_resolvable_future'><span class='object_link'><a href="../Promises/FactoryMethods.html#resolvable_future-instance_method" title="Concurrent::Promises::FactoryMethods#resolvable_future (method)">resolvable_future</a></span></span><span class='rparen'>)</span>
<span class='id identifier rubyid_ask'>ask</span><span class='lparen'>(</span><span class='id identifier rubyid_message'>message</span><span class='comma'>,</span> <span class='id identifier rubyid_future'>future</span><span class='rparen'>)</span><span class='period'>.</span><span class='id identifier rubyid_value!'>value!</span>
Expand Down Expand Up @@ -980,12 +972,12 @@ <h3 class="signature " id="dead_letter_routing-instance_method">
<pre class="lines">


90
91
92</pre>
85
86
87</pre>
</td>
<td>
<pre class="code"><span class="info file"># File 'lib-edge/concurrent/actor/reference.rb', line 90</span>
<pre class="code"><span class="info file"># File 'lib-edge/concurrent/actor/reference.rb', line 85</span>

<span class='kw'>def</span> <span class='id identifier rubyid_dead_letter_routing'>dead_letter_routing</span>
<span class='id identifier rubyid_core'>core</span><span class='period'>.</span><span class='id identifier rubyid_dead_letter_routing'>dead_letter_routing</span>
Expand Down Expand Up @@ -1019,12 +1011,12 @@ <h3 class="signature " id="map-instance_method">
<pre class="lines">


79
80
81</pre>
74
75
76</pre>
</td>
<td>
<pre class="code"><span class="info file"># File 'lib-edge/concurrent/actor/reference.rb', line 79</span>
<pre class="code"><span class="info file"># File 'lib-edge/concurrent/actor/reference.rb', line 74</span>

<span class='kw'>def</span> <span class='id identifier rubyid_map'>map</span><span class='lparen'>(</span><span class='id identifier rubyid_messages'>messages</span><span class='rparen'>)</span>
<span class='id identifier rubyid_messages'>messages</span><span class='period'>.</span><span class='id identifier rubyid_map'>map</span> <span class='lbrace'>{</span> <span class='op'>|</span><span class='id identifier rubyid_m'>m</span><span class='op'>|</span> <span class='kw'>self</span><span class='period'>.</span><span class='id identifier rubyid_ask'>ask</span><span class='lparen'>(</span><span class='id identifier rubyid_m'>m</span><span class='rparen'>)</span> <span class='rbrace'>}</span>
Expand Down Expand Up @@ -1059,13 +1051,13 @@ <h3 class="signature " id="message-instance_method">
<pre class="lines">


84
85
86
87</pre>
79
80
81
82</pre>
</td>
<td>
<pre class="code"><span class="info file"># File 'lib-edge/concurrent/actor/reference.rb', line 84</span>
<pre class="code"><span class="info file"># File 'lib-edge/concurrent/actor/reference.rb', line 79</span>

<span class='kw'>def</span> <span class='id identifier rubyid_message'>message</span><span class='lparen'>(</span><span class='id identifier rubyid_message'>message</span><span class='comma'>,</span> <span class='id identifier rubyid_future'>future</span> <span class='op'>=</span> <span class='kw'>nil</span><span class='rparen'>)</span>
<span class='id identifier rubyid_core'>core</span><span class='period'>.</span><span class='id identifier rubyid_on_envelope'>on_envelope</span> <span class='const'><span class='object_link'><a href="Envelope.html" title="Concurrent::Actor::Envelope (class)">Envelope</a></span></span><span class='period'>.</span><span class='id identifier rubyid_new'><span class='object_link'><a href="Envelope.html#initialize-instance_method" title="Concurrent::Actor::Envelope#initialize (method)">new</a></span></span><span class='lparen'>(</span><span class='id identifier rubyid_message'>message</span><span class='comma'>,</span> <span class='id identifier rubyid_future'>future</span><span class='comma'>,</span> <span class='const'><span class='object_link'><a href="../Actor.html" title="Concurrent::Actor (module)">Actor</a></span></span><span class='period'>.</span><span class='id identifier rubyid_current'><span class='object_link'><a href="../Actor.html#current-class_method" title="Concurrent::Actor.current (method)">current</a></span></span> <span class='op'>||</span> <span class='const'>Thread</span><span class='period'>.</span><span class='id identifier rubyid_current'>current</span><span class='comma'>,</span> <span class='kw'>self</span><span class='rparen'>)</span>
Expand Down Expand Up @@ -1192,12 +1184,12 @@ <h3 class="signature " id="to_s-instance_method">
<pre class="lines">


94
95
96</pre>
89
90
91</pre>
</td>
<td>
<pre class="code"><span class="info file"># File 'lib-edge/concurrent/actor/reference.rb', line 94</span>
<pre class="code"><span class="info file"># File 'lib-edge/concurrent/actor/reference.rb', line 89</span>

<span class='kw'>def</span> <span class='id identifier rubyid_to_s'>to_s</span>
<span class='id identifier rubyid_format'>format</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>%s %s (%s)&gt;</span><span class='tstring_end'>&#39;</span></span><span class='comma'>,</span> <span class='kw'>super</span><span class='lbracket'>[</span><span class='int'>0</span><span class='op'>..</span><span class='op'>-</span><span class='int'>2</span><span class='rbracket'>]</span><span class='comma'>,</span> <span class='id identifier rubyid_path'>path</span><span class='comma'>,</span> <span class='id identifier rubyid_actor_class'>actor_class</span>
Expand Down
13 changes: 6 additions & 7 deletions docs/master/Concurrent/Array.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -104,20 +104,19 @@ <h2>Overview</h2><div class="docstring">

<div class="note notetag">
<strong>Note:</strong>
<div class='inline'><p><code>a += b</code> is <strong>not</strong> a <strong>thread-safe</strong> operation on</p>
<div class='inline'><p><code>a += b</code> is <strong>not</strong> a <strong>thread-safe</strong> operation on
<code>Concurrent::Array</code>. It reads array <code>a</code>, then it creates new <code>Concurrent::Array</code>
which is concatenation of <code>a</code> and <code>b</code>, then it writes the concatenation to <code>a</code>.
The read and write are independent operations they do not form a single atomic
operation therefore when two <code>+=</code> operations are executed concurrently updates
may be lost. Use <code>#concat</code> instead.</p>
</div>
</div>

<p>A thread-safe subclass of Array. This version locks against the object
itself for every method call, ensuring only one thread can be reading
or writing at a time. This includes iteration methods like <code>#each</code>.</p>

<p><code>Concurrent::Array</code>. It reads array <code>a</code>, then it creates new <code>Concurrent::Array</code>
which is concatenation of <code>a</code> and <code>b</code>, then it writes the concatenation to <code>a</code>.
The read and write are independent operations they do not form a single atomic
operation therefore when two <code>+=</code> operations are executed concurrently updates
may be lost. Use <code>#concat</code> instead.</p>


</div>
</div>
Expand Down
2 changes: 1 addition & 1 deletion docs/master/Concurrent/ErlangActor.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -119,7 +119,7 @@ <h2>Overview</h2><div class="docstring">
Although, <code>Promises.future { 1 + 1 }</code> is better suited for that purpose.</p>

<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_actor'>actor</span> <span class='op'>=</span> <span class='const'><span class='object_link'><a href="../Concurrent.html" title="Concurrent (module)">Concurrent</a></span></span><span class='op'>::</span><span class='const'>ErlangActor</span><span class='period'>.</span><span class='id identifier rubyid_spawn'><span class='object_link'><a href="ErlangActor/FunctionShortcuts.html#spawn-instance_method" title="Concurrent::ErlangActor::FunctionShortcuts#spawn (method)">spawn</a></span></span><span class='lparen'>(</span><span class='label'>type:</span> <span class='symbol'>:on_thread</span><span class='comma'>,</span> <span class='label'>name:</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>addition</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span> <span class='lbrace'>{</span> <span class='int'>1</span> <span class='op'>+</span> <span class='int'>1</span> <span class='rbrace'>}</span>
<span class='comment'># =&gt; #&lt;Concurrent::ErlangActor::Pid:0x000002 addition terminated normally with 2&gt;
<span class='comment'># =&gt; #&lt;Concurrent::ErlangActor::Pid:0x000002 addition running&gt;
</span><span class='id identifier rubyid_actor'>actor</span><span class='period'>.</span><span class='id identifier rubyid_terminated'>terminated</span><span class='period'>.</span><span class='id identifier rubyid_value!'>value!</span> <span class='comment'># =&gt; 2
</span></code></pre>

Expand Down
Loading