Doc updates

Author: pitr-ch

README.md

@@ -227,10 +227,10 @@ be obeyed though. Features developed in `concurrent-ruby-edge` are expected to m
 *   [Promises::Channel](http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/Promises/Channel.html)
     A first in first out channel that accepts messages with push family of methods and returns
     messages with pop family of methods.
-    Pop and push operations can be represented as futures, see {#pop_op} and {#push_op}.
-    The capacity of the channel can be limited to support back pressure, use capacity option in {#initialize}.
-    {#pop} method blocks ans {#pop_op} returns pending future if there is no message in the channel.
-    If the capacity is limited the {#push} method blocks and {#push_op} returns pending future.
+    Pop and push operations can be represented as futures, see `#pop_op` and `#push_op`.
+    The capacity of the channel can be limited to support back pressure, use capacity option in `#initialize`.
+    `#pop` method blocks ans `#pop_op` returns pending future if there is no message in the channel.
+    If the capacity is limited the `#push` method blocks and `#push_op` returns pending future.
 *   [Cancellation](http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/Cancellation.html)
     The Cancellation abstraction provides cooperative cancellation.
 

docs-source/channel.in.md

@@ -31,7 +31,7 @@ one will be blocked until new messages is pushed.
 ```ruby
 threads = Array.new(3) { |i| Thread.new { ch.pop } } #
 sleep 0.01 # let the threads run
-threads
+threads 
 ch.push message: 3
 threads.map(&:value)
 ```

docs-source/channel.out.md

@@ -16,14 +16,14 @@ threads = Array.new(3) { |i| Thread.new { ch.push message: i } }
 sleep 0.01 # let the threads run
 threads
 # => [#<Thread:[email protected]:14 dead>,
-#     #<Thread:[email protected]:14 dead>,
-#     #<Thread:[email protected]:14 sleep_forever>]
+#     #<Thread:[email protected]:14 sleep_forever>,
+#     #<Thread:[email protected]:14 dead>]
 ```
 
 When message is popped the last thread continues and finishes as well.
 
 ```ruby
-ch.pop                                   # => {:message=>0}
+ch.pop                                   # => {:message=>2}
 threads.map(&:join)
 # => [#<Thread:[email protected]:14 dead>,
 #     #<Thread:[email protected]:14 dead>,
@@ -38,14 +38,11 @@ one will be blocked until new messages is pushed.
 ```ruby
 threads = Array.new(3) { |i| Thread.new { ch.pop } } 
 sleep 0.01 # let the threads run
-threads
-# => [#<Thread:[email protected]:32 dead>,
-#     #<Thread:[email protected]:32 dead>,
-#     #<Thread:[email protected]:32 sleep_forever>]
+threads.map(&:status)                    # => [false, false, "sleep"]
 ch.push message: 3
 # => #<Concurrent::Promises::Channel:0x000002 capacity taken 0 of 2>
 threads.map(&:value)
-# => [{:message=>1}, {:message=>2}, {:message=>3}]
+# => [{:message=>0}, {:message=>1}, {:message=>3}]
 ```
 
 ### Promises integration
@@ -55,11 +52,11 @@ therefore all operations can be represented as futures.
 
 ```ruby
 ch = Concurrent::Promises::Channel.new 2
-# => #<Concurrent::Promises::Channel:0x000009 capacity taken 0 of 2>
+# => #<Concurrent::Promises::Channel:0x000006 capacity taken 0 of 2>
 push_operations = Array.new(3) { |i| ch.push_op message: i }
-# => [#<Concurrent::Promises::Future:0x00000a fulfilled with #<Concurrent::Promises::Channel:0x000009 capacity taken 2 of 2>>,
-#     #<Concurrent::Promises::Future:0x00000b fulfilled with #<Concurrent::Promises::Channel:0x000009 capacity taken 2 of 2>>,
-#     #<Concurrent::Promises::ResolvableFuture:0x00000c pending>]
+# => [#<Concurrent::Promises::Future:0x000007 fulfilled with #<Concurrent::Promises::Channel:0x000006 capacity taken 2 of 2>>,
+#     #<Concurrent::Promises::Future:0x000008 fulfilled with #<Concurrent::Promises::Channel:0x000006 capacity taken 2 of 2>>,
+#     #<Concurrent::Promises::ResolvableFuture:0x000009 pending>]
 ```
 
 > We do not have to sleep here letting the futures execute as Threads.
@@ -73,14 +70,14 @@ making a space for a new message.
 ```ruby
 ch.pop_op.value!                         # => {:message=>0}
 push_operations.map(&:value!)
-# => [#<Concurrent::Promises::Channel:0x000009 capacity taken 2 of 2>,
-#     #<Concurrent::Promises::Channel:0x000009 capacity taken 2 of 2>,
-#     #<Concurrent::Promises::Channel:0x000009 capacity taken 2 of 2>]
+# => [#<Concurrent::Promises::Channel:0x000006 capacity taken 2 of 2>,
+#     #<Concurrent::Promises::Channel:0x000006 capacity taken 2 of 2>,
+#     #<Concurrent::Promises::Channel:0x000006 capacity taken 2 of 2>]
 
 pop_operations = Array.new(3) { |i| ch.pop_op }
-# => [#<Concurrent::Promises::ResolvableFuture:0x00000d fulfilled with {:message=>1}>,
-#     #<Concurrent::Promises::ResolvableFuture:0x00000e fulfilled with {:message=>2}>,
-#     #<Concurrent::Promises::ResolvableFuture:0x00000f pending>]
+# => [#<Concurrent::Promises::ResolvableFuture:0x00000a fulfilled with {:message=>1}>,
+#     #<Concurrent::Promises::ResolvableFuture:0x00000b fulfilled with {:message=>2}>,
+#     #<Concurrent::Promises::ResolvableFuture:0x00000c pending>]
 ch.push message: 3 # (push|pop) can be freely mixed with (push_o|pop_op)
 pop_operations.map(&:value) 
 # => [{:message=>1}, {:message=>2}, {:message=>3}]
@@ -94,21 +91,21 @@ returns a pair to be able to find out which channel had the message available.
 
 ```ruby
 ch1    = Concurrent::Promises::Channel.new 2
-# => #<Concurrent::Promises::Channel:0x000010 capacity taken 0 of 2>
+# => #<Concurrent::Promises::Channel:0x00000d capacity taken 0 of 2>
 ch2    = Concurrent::Promises::Channel.new 2
-# => #<Concurrent::Promises::Channel:0x000011 capacity taken 0 of 2>
+# => #<Concurrent::Promises::Channel:0x00000e capacity taken 0 of 2>
 ch1.push 1 
-# => #<Concurrent::Promises::Channel:0x000010 capacity taken 1 of 2>
+# => #<Concurrent::Promises::Channel:0x00000d capacity taken 1 of 2>
 ch2.push 2 
-# => #<Concurrent::Promises::Channel:0x000011 capacity taken 1 of 2>
+# => #<Concurrent::Promises::Channel:0x00000e capacity taken 1 of 2>
 
 Concurrent::Promises::Channel.select([ch1, ch2])
-# => [#<Concurrent::Promises::Channel:0x000010 capacity taken 0 of 2>, 1]
+# => [#<Concurrent::Promises::Channel:0x00000d capacity taken 0 of 2>, 1]
 ch1.select(ch2)
-# => [#<Concurrent::Promises::Channel:0x000011 capacity taken 0 of 2>, 2]
+# => [#<Concurrent::Promises::Channel:0x00000e capacity taken 0 of 2>, 2]
 
 Concurrent::Promises.future { 3 + 4 }.then_channel_push(ch1)
-# => #<Concurrent::Promises::Future:0x000012 pending>
+# => #<Concurrent::Promises::Future:0x00000f pending>
 Concurrent::Promises::Channel. 
     # or `ch1.select_op(ch2)` would be equivalent
     select_op([ch1, ch2]).
@@ -125,7 +122,7 @@ They always return immediately and indicate either success or failure.
 
 ```ruby
 ch
-# => #<Concurrent::Promises::Channel:0x000009 capacity taken 0 of 2>
+# => #<Concurrent::Promises::Channel:0x000006 capacity taken 0 of 2>
 ch.try_push 1                            # => true
 ch.try_push 2                            # => true
 ch.try_push 3                            # => false
@@ -142,7 +139,7 @@ when the timeout option is used.
 
 ```ruby
 ch
-# => #<Concurrent::Promises::Channel:0x000009 capacity taken 0 of 2>
+# => #<Concurrent::Promises::Channel:0x000006 capacity taken 0 of 2>
 ch.push 1, 0.01                          # => true
 ch.push 2, 0.01                          # => true
 ch.push 3, 0.01                          # => false
@@ -159,7 +156,7 @@ if the consumers are not keeping up.
 
 ```ruby
 channel = Concurrent::Promises::Channel.new 2
-# => #<Concurrent::Promises::Channel:0x000013 capacity taken 0 of 2>
+# => #<Concurrent::Promises::Channel:0x000010 capacity taken 0 of 2>
 log     = Concurrent::Array.new          # => []
 
 producers = Array.new 2 do |i|
@@ -170,8 +167,8 @@ producers = Array.new 2 do |i|
     end
   end
 end
-# => [#<Thread:0x000014@channel.in.md:133 run>,
-#     #<Thread:0x000015@channel.in.md:133 run>]
+# => [#<Thread:0x000011@channel.in.md:133 run>,
+#     #<Thread:0x000012@channel.in.md:133 run>]
 
 consumers = Array.new 4 do |i|
   Thread.new(i) do |consumer|
@@ -183,22 +180,22 @@ consumers = Array.new 4 do |i|
     end
   end
 end
-# => [#<Thread:0x000016@channel.in.md:142 run>,
-#     #<Thread:0x000017@channel.in.md:142 run>,
-#     #<Thread:0x000018@channel.in.md:142 run>,
-#     #<Thread:0x000019@channel.in.md:142 run>]
+# => [#<Thread:0x000013@channel.in.md:142 run>,
+#     #<Thread:0x000014@channel.in.md:142 run>,
+#     #<Thread:0x000015@channel.in.md:142 run>,
+#     #<Thread:0x000016@channel.in.md:142 run>]
 
 # wait for all to finish
 producers.map(&:join)
-# => [#<Thread:0x000014@channel.in.md:133 dead>,
-#     #<Thread:0x000015@channel.in.md:133 dead>]
+# => [#<Thread:0x000011@channel.in.md:133 dead>,
+#     #<Thread:0x000012@channel.in.md:133 dead>]
 consumers.map(&:join)
-# => [#<Thread:0x000016@channel.in.md:142 dead>,
-#     #<Thread:0x000017@channel.in.md:142 dead>,
-#     #<Thread:0x000018@channel.in.md:142 dead>,
-#     #<Thread:0x000019@channel.in.md:142 dead>]
+# => [#<Thread:0x000013@channel.in.md:142 dead>,
+#     #<Thread:0x000014@channel.in.md:142 dead>,
+#     #<Thread:0x000015@channel.in.md:142 dead>,
+#     #<Thread:0x000016@channel.in.md:142 dead>]
 # investigate log
-log
+log 
 # => ["producer 0 pushing 0",
 #     "producer 0 pushing 1",
 #     "producer 0 pushing 2",
@@ -229,7 +226,7 @@ that run a thread pool.
 
 ```ruby
 channel = Concurrent::Promises::Channel.new 2
-# => #<Concurrent::Promises::Channel:0x00001a capacity taken 0 of 2>
+# => #<Concurrent::Promises::Channel:0x000017 capacity taken 0 of 2>
 log     = Concurrent::Array.new          # => []
 
 def produce(channel, log, producer, i)
@@ -251,22 +248,22 @@ end                                      # => :consume
 producers = Array.new 2 do |i|
   Concurrent::Promises.future(channel, log, i) { |*args| produce *args, 0 }.run
 end
-# => [#<Concurrent::Promises::Future:0x00001b pending>,
-#     #<Concurrent::Promises::Future:0x00001c pending>]
+# => [#<Concurrent::Promises::Future:0x000018 pending>,
+#     #<Concurrent::Promises::Future:0x000019 pending>]
 
 consumers = Array.new 4 do |i|
   Concurrent::Promises.future(channel, log, i) { |*args| consume *args, 0 }.run
 end
-# => [#<Concurrent::Promises::Future:0x00001d pending>,
-#     #<Concurrent::Promises::Future:0x00001e pending>,
-#     #<Concurrent::Promises::Future:0x00001f pending>,
-#     #<Concurrent::Promises::Future:0x000020 pending>]
+# => [#<Concurrent::Promises::Future:0x00001a pending>,
+#     #<Concurrent::Promises::Future:0x00001b pending>,
+#     #<Concurrent::Promises::Future:0x00001c pending>,
+#     #<Concurrent::Promises::Future:0x00001d pending>]
 
 # wait for all to finish
 producers.map(&:value!)                  # => [:done, :done]
 consumers.map(&:value!)                  # => [:done, :done, :done, :done]
 # investigate log
-log
+log 
 # => ["producer 0 pushing 0",
 #     "producer 1 pushing 0",
 #     "consumer 1 got 0. payload 0 from producer 1",
@@ -295,19 +292,19 @@ The operations have to be paired to succeed.
 
 ```ruby
 channel = Concurrent::Promises::Channel.new 0
-# => #<Concurrent::Promises::Channel:0x000021 capacity taken 0 of 0>
+# => #<Concurrent::Promises::Channel:0x00001e capacity taken 0 of 0>
 thread = Thread.new { channel.pop }; sleep 0.01 
 # allow the thread to go to sleep
 thread
-# => #<Thread:0x000022@channel.in.md:214 sleep_forever>
+# => #<Thread:0x00001f@channel.in.md:246 sleep_forever>
 # succeeds because there is matching pop operation waiting in the thread 
 channel.try_push(:v1)                    # => true
 # remains pending, since there is no matching operation 
 push = channel.push_op(:v2)
-# => #<Concurrent::Promises::ResolvableFuture:0x000023 pending>
+# => #<Concurrent::Promises::ResolvableFuture:0x000020 pending>
 thread.value                             # => :v1
 # the push operation resolves as a pairing pop is called
 channel.pop                              # => :v2
 push
-# => #<Concurrent::Promises::ResolvableFuture:0x000023 fulfilled with #<Concurrent::Promises::Channel:0x000021 capacity taken 0 of 0>>
+# => #<Concurrent::Promises::ResolvableFuture:0x000020 fulfilled with #<Concurrent::Promises::Channel:0x00001e capacity taken 0 of 0>>
 ```