Documentation update

Author: pitr-ch

README.md

@@ -106,6 +106,13 @@ be obeyed though. Features developed in `concurrent-ruby-edge` are expected to m
   Communicating Sequential Processes (CSP).
 * [Exchanger](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Exchanger.html)
 * [LazyRegister](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/LazyRegister.html)
+* [New Future Promise Framework](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Edge.html) - new 
+  unified implementation of Futures and Promises which combines Features of previous `Future`,
+  `Promise`, `IVar`, `Probe`, `dataflow`, `Delay`, `TimerTask` into single framework. It uses extensively
+  new synchronization layer to make all the paths lock-free with exception of blocking threads on `#wait`.
+  It offers better performance and does not block threads (exception being `#wait` and similar methods where it's
+  intended).
+
 
 ## Usage
 

examples/edge_futures.in.rb

@@ -23,7 +23,9 @@
 branch1 = head.then(&:succ) #
 branch2 = head.then(&:succ).then(&:succ) #
 branch1.zip(branch2).value
-(branch1 & branch2).then { |(a, b)| a + b }.value
+(branch1 & branch2).then { |a, b| a + b }.value!
+(branch1 & branch2).then(&:+).value!
+Concurrent.zip(branch1, branch2, branch1).then { |*values| values.reduce &:+ }.value!
 # pick only first completed
 (branch1 | branch2).value
 
@@ -170,7 +172,7 @@
 
 def schedule_job
   Concurrent.schedule(1) { do_stuff }.
-      rescue { |e| report_error e }.
+      rescue { |e| StandardError === e ? report_error(e) : raise(e) }.
       then { schedule_job unless @end }
 end
 
@@ -214,7 +216,7 @@ def work(message)
   end
 end
 
-data = Array.new(10) { |i| '*' * i }
+data      = Array.new(10) { |i| '*' * i }
 pool_size = 5
 
 DB_POOL = Concurrent::Actor::Utils::Pool.spawn!('DB-pool', pool_size) do |balancer, index|

examples/edge_futures.out.rb

@@ -1,7 +1,7 @@
 ### Simple asynchronous task
 
 future = Concurrent.future { sleep 0.1; 1 + 1 } # evaluation starts immediately
-    # => <#Concurrent::Edge::Future:0x7fad9ca186e0 pending blocks:[]>
+    # => <#Concurrent::Edge::Future:0x7f9f549266e8 pending blocks:[]>
 future.completed?                                  # => false
 # block until evaluated
 future.value                                       # => 2
@@ -11,7 +11,7 @@
 ### Failing asynchronous task
 
 future = Concurrent.future { raise 'Boom' }
-    # => <#Concurrent::Edge::Future:0x7fad9c9f95b0 pending blocks:[]>
+    # => <#Concurrent::Edge::Future:0x7f9f548dd3f8 pending blocks:[]>
 future.value                                       # => nil
 future.value! rescue $!                            # => #<RuntimeError: Boom>
 future.reason                                      # => #<RuntimeError: Boom>
@@ -23,10 +23,13 @@
 
 head    = Concurrent.future { 1 } 
 branch1 = head.then(&:succ) 
-branch2 = head.then(&:succ).then(&:succ) 
+branch2 = head.then(&:succ).then(&:succ)
+# zipping futures
 branch1.zip(branch2).value                         # => [2, 3]
-(branch1 & branch2).then { |(a, b)| a + b }.value
-    # => nil
+(branch1 & branch2).then { |a, b| a + b }.value!   # => 5
+(branch1 & branch2).then(&:+).value!               # => 5
+Concurrent.zip(branch1, branch2, branch1).then { |*values| values.reduce &:+ }.value!
+    # => 7
 # pick only first completed
 (branch1 | branch2).value                          # => 2
 
@@ -45,21 +48,21 @@
 
 # will not evaluate until asked by #value or other method requiring completion
 future = Concurrent.delay { 'lazy' }
-    # => <#Concurrent::Edge::Future:0x7fad9c8fb3e8 pending blocks:[]>
+    # => <#Concurrent::Edge::Future:0x7f9f53a57b58 pending blocks:[]>
 sleep 0.1 
 future.completed?                                  # => false
 future.value                                       # => "lazy"
 
 # propagates trough chain allowing whole or partial lazy chains
 
 head    = Concurrent.delay { 1 }
-    # => <#Concurrent::Edge::Future:0x7fad9b158bf0 pending blocks:[]>
+    # => <#Concurrent::Edge::Future:0x7f9f53a35508 pending blocks:[]>
 branch1 = head.then(&:succ)
-    # => <#Concurrent::Edge::Future:0x7fad9b149ba0 pending blocks:[]>
+    # => <#Concurrent::Edge::Future:0x7f9f53a17328 pending blocks:[]>
 branch2 = head.delay.then(&:succ)
-    # => <#Concurrent::Edge::Future:0x7fad9b12a020 pending blocks:[]>
+    # => <#Concurrent::Edge::Future:0x7f9f5590d868 pending blocks:[]>
 join    = branch1 & branch2
-    # => <#Concurrent::Edge::ArrayFuture:0x7fad9b8a0778 pending blocks:[]>
+    # => <#Concurrent::Edge::ArrayFuture:0x7f9f558fd7d8 pending blocks:[]>
 
 sleep 0.1 # nothing will complete                  # => 0
 [head, branch1, branch2, join].map(&:completed?)   # => [false, false, false, false]
@@ -87,14 +90,14 @@
 ### Schedule
 
 scheduled = Concurrent.schedule(0.1) { 1 }
-    # => <#Concurrent::Edge::Future:0x7fad9a941e08 pending blocks:[]>
+    # => <#Concurrent::Edge::Future:0x7f9f5581ed30 pending blocks:[]>
 
 scheduled.completed?                               # => false
 scheduled.value # available after 0.1sec           # => 1
 
 # and in chain
 scheduled = Concurrent.delay { 1 }.schedule(0.1).then(&:succ)
-    # => <#Concurrent::Edge::Future:0x7fad9b0aa7d0 pending blocks:[]>
+    # => <#Concurrent::Edge::Future:0x7f9f548494c8 pending blocks:[]>
 # will not be scheduled until value is requested
 sleep 0.1 
 scheduled.value # returns after another 0.1sec     # => 2
@@ -103,35 +106,35 @@
 ### Completable Future and Event
 
 future = Concurrent.future
-    # => <#Concurrent::Edge::CompletableFuture:0x7fad9a87b6e0 pending blocks:[]>
+    # => <#Concurrent::Edge::CompletableFuture:0x7f9f5385bcf0 pending blocks:[]>
 event  = Concurrent.event
-    # => <#Concurrent::Edge::CompletableEvent:0x7fad9a86ba88 pending blocks:[]>
+    # => <#Concurrent::Edge::CompletableEvent:0x7f9f53858ca8 pending blocks:[]>
 
 # will be blocked until completed
 t1     = Thread.new { future.value } 
 t2     = Thread.new { event.wait } 
 
 future.success 1
-    # => <#Concurrent::Edge::CompletableFuture:0x7fad9a87b6e0 success blocks:[]>
+    # => <#Concurrent::Edge::CompletableFuture:0x7f9f5385bcf0 success blocks:[]>
 future.success 1 rescue $!
     # => #<Concurrent::MultipleAssignmentError: multiple assignment>
 future.try_success 2                               # => false
 event.complete
-    # => <#Concurrent::Edge::CompletableEvent:0x7fad9a86ba88 completed blocks:[]>
+    # => <#Concurrent::Edge::CompletableEvent:0x7f9f53858ca8 completed blocks:[]>
 
 [t1, t2].each &:join 
 
 
 ### Callbacks
 
-queue  = Queue.new                                 # => #<Thread::Queue:0x007fad9a862320>
+queue  = Queue.new                                 # => #<Thread::Queue:0x007f9f53861b50>
 future = Concurrent.delay { 1 + 1 }
-    # => <#Concurrent::Edge::Future:0x7fad9a853960 pending blocks:[]>
+    # => <#Concurrent::Edge::Future:0x7f9f54853d10 pending blocks:[]>
 
 future.on_success { queue << 1 } # evaluated asynchronously
-    # => <#Concurrent::Edge::Future:0x7fad9a853960 pending blocks:[]>
+    # => <#Concurrent::Edge::Future:0x7f9f54853d10 pending blocks:[]>
 future.on_success! { queue << 2 } # evaluated on completing thread
-    # => <#Concurrent::Edge::Future:0x7fad9a853960 pending blocks:[]>
+    # => <#Concurrent::Edge::Future:0x7f9f54853d10 pending blocks:[]>
 
 queue.empty?                                       # => true
 future.value                                       # => 2
@@ -142,7 +145,7 @@
 ### Thread-pools
 
 Concurrent.future(:fast) { 2 }.then(:io) { File.read __FILE__ }.wait
-    # => <#Concurrent::Edge::Future:0x7fad9a883958 success blocks:[]>
+    # => <#Concurrent::Edge::Future:0x7f9f539545f8 success blocks:[]>
 
 
 ### Interoperability with actors
@@ -163,32 +166,32 @@
 
 ### Interoperability with channels
 
-ch1 = Concurrent::Edge::Channel.new                # => #<Concurrent::Edge::Channel:0x007fad9c892ac8>
-ch2 = Concurrent::Edge::Channel.new                # => #<Concurrent::Edge::Channel:0x007fad9c8904a8>
+ch1 = Concurrent::Edge::Channel.new                # => #<Concurrent::Edge::Channel:0x007f9f558e5db8>
+ch2 = Concurrent::Edge::Channel.new                # => #<Concurrent::Edge::Channel:0x007f9f558e4f80>
 
 result = Concurrent.select(ch1, ch2)
-    # => <#Concurrent::Edge::CompletableFuture:0x7fad9b86aa88 pending blocks:[]>
+    # => <#Concurrent::Edge::CompletableFuture:0x7f9f53a4fe58 pending blocks:[]>
 ch1.push 1                                         # => nil
 result.value!
-    # => [1, #<Concurrent::Edge::Channel:0x007fad9c892ac8>]
+    # => [1, #<Concurrent::Edge::Channel:0x007f9f558e5db8>]
 
 Concurrent.
     future { 1+1 }.
     then_push(ch1)
-    # => <#Concurrent::Edge::Future:0x7fad9c898d88 pending blocks:[]>
+    # => <#Concurrent::Edge::Future:0x7f9f53a2e758 pending blocks:[]>
 result = Concurrent.
     future { '%02d' }.
     then_select(ch1, ch2).
     then { |format, (value, channel)| format format, value }
-    # => <#Concurrent::Edge::Future:0x7fad9b88b4e0 pending blocks:[]>
+    # => <#Concurrent::Edge::Future:0x7f9f55925f30 pending blocks:[]>
 result.value!                                      # => "02"
 
 
 ### Common use-cases Examples
 
 # simple background processing
 Concurrent.future { do_stuff }
-    # => <#Concurrent::Edge::Future:0x7fad9b151b98 pending blocks:[]>
+    # => <#Concurrent::Edge::Future:0x7f9f53a93e50 pending blocks:[]>
 
 # parallel background processing
 jobs = 10.times.map { |i| Concurrent.future { i } } 
@@ -200,12 +203,12 @@
 
 def schedule_job
   Concurrent.schedule(1) { do_stuff }.
-      rescue { |e| report_error e }.
+      rescue { |e| StandardError === e ? report_error(e) : raise(e) }.
       then { schedule_job unless @end }
 end                                                # => :schedule_job
 
 schedule_job
-    # => <#Concurrent::Edge::Future:0x7fad9c96a6a8 pending blocks:[]>
+    # => <#Concurrent::Edge::Future:0x7f9f548b01a0 pending blocks:[]>
 @end = true                                        # => true
 
 
@@ -247,7 +250,7 @@ def work(message)
   end
 end                                                # => :work
 
-data = Array.new(10) { |i| '*' * i }
+data      = Array.new(10) { |i| '*' * i }
     # => ["", "*", "**", "***", "****", "*****", "******", "*******", "********", "*********"]
 pool_size = 5                                      # => 5