Merge pull request #830 from petrblaho/wrapping-executor

Adds WrappingExecutor with docs

Author: pitr-ch

README.md

@@ -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
 

docs-source/channel.out.md

@@ -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.
@@ -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
@@ -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"]
 ```
 
@@ -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"]
 ```
 

docs-source/erlang_actor.out.md

@@ -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
 ```
 

docs-source/medium-example.out.rb

@@ -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();
@@ -287,6 +297,7 @@ $(document).ready(function() {
   constantSummaryToggle();
   generateTOC();
   mainFocus();
+  navigationChange();
 });
 
 })();

docs/js/app.js

@@ -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>

docs/master/Concurrent.html

@@ -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>
@@ -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>
@@ -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>
@@ -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>
@@ -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>
@@ -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>
@@ -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>
@@ -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>
@@ -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>
@@ -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>

docs/master/Concurrent/Actor.html

@@ -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>

docs/master/Concurrent/Actor/Reference.html

@@ -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>