Add documentation for zipping of failures

Author: pitr-ch

examples/edge_futures.in.rb

@@ -35,6 +35,11 @@
 Concurrent.future { Object.new }.then(&:succ).rescue { 1 }.then(&:succ).value
 Concurrent.future { 1 }.then(&:succ).rescue { |e| e.message }.then(&:succ).value
 
+failing_zip = Concurrent.completed_future(1) & Concurrent.future { raise 'boom' }
+failing_zip.result
+failing_zip.then { |v| 'never happens' }.result
+failing_zip.rescue { |a, b| (a || b).message }.value
+failing_zip.chain { |success, values, reasons| [success, values.compact, reasons.compactß] }.value
 
 ### Delay
 

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:0x7fd41a956d70 pending blocks:[]>
+    # => <#Concurrent::Edge::Future:0x7fc6218f2318 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:0x7fd41a946c18 failed blocks:[]>
+    # => <#Concurrent::Edge::Future:0x7fc6218eae38 pending blocks:[]>
 future.value                                       # => nil
 future.value! rescue $!                            # => #<RuntimeError: Boom>
 future.reason                                      # => #<RuntimeError: Boom>
@@ -41,26 +41,34 @@
 Concurrent.future { 1 }.then(&:succ).rescue { |e| e.message }.then(&:succ).value
     # => 3
 
+failing_zip = Concurrent.completed_future(1) & Concurrent.future { raise 'boom' }
+    # => <#Concurrent::Edge::Future:0x7fc6218b0f08 pending blocks:[]>
+failing_zip.result                                 # => [false, [1, nil], [nil, #<RuntimeError: boom>]]
+failing_zip.then { |v| 'never happens' }.result    # => [false, [1, nil], [nil, #<RuntimeError: boom>]]
+failing_zip.rescue { |a, b| (a || b).message }.value
+    # => "boom"
+failing_zip.chain { |success, values, reasons| [success, values.compact, reasons.compactß] }.value
+    # => nil
 
 ### Delay
 
 # will not evaluate until asked by #value or other method requiring completion
 future = Concurrent.delay { 'lazy' }
-    # => <#Concurrent::Edge::Future:0x7fd41a8f6ec0 pending blocks:[]>
+    # => <#Concurrent::Edge::Future:0x7fc6218a37e0 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:0x7fd41a8ee1a8 pending blocks:[]>
+    # => <#Concurrent::Edge::Future:0x7fc6218a0720 pending blocks:[]>
 branch1 = head.then(&:succ)
-    # => <#Concurrent::Edge::Future:0x7fd41a8ed438 pending blocks:[]>
+    # => <#Concurrent::Edge::Future:0x7fc6212c7b50 pending blocks:[]>
 branch2 = head.delay.then(&:succ)
-    # => <#Concurrent::Edge::Future:0x7fd41a8e7588 pending blocks:[]>
+    # => <#Concurrent::Edge::Future:0x7fc6212c6098 pending blocks:[]>
 join    = branch1 & branch2
-    # => <#Concurrent::Edge::Future:0x7fd41a8e4ec8 pending blocks:[]>
+    # => <#Concurrent::Edge::Future:0x7fc6212c4f40 pending blocks:[]>
 
 sleep 0.1 # nothing will complete                  # => 0
 [head, branch1, branch2, join].map(&:completed?)   # => [false, false, false, false]
@@ -88,14 +96,14 @@
 ### Schedule
 
 scheduled = Concurrent.schedule(0.1) { 1 }
-    # => <#Concurrent::Edge::Future:0x7fd41a8a4468 pending blocks:[]>
+    # => <#Concurrent::Edge::Future:0x7fc62128c550 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:0x7fd41a895828 pending blocks:[]>
+    # => <#Concurrent::Edge::Future:0x7fc6228bcdc0 pending blocks:[]>
 # will not be scheduled until value is requested
 sleep 0.1 
 scheduled.value # returns after another 0.1sec     # => 2
@@ -104,36 +112,36 @@
 ### Completable Future and Event
 
 future = Concurrent.future
-    # => <#Concurrent::Edge::CompletableFuture:0x7fd41a87c648 pending blocks:[]>
+    # => <#Concurrent::Edge::CompletableFuture:0x7fc623083720 pending blocks:[]>
 event  = Concurrent.event
-    # => <#Concurrent::Edge::CompletableEvent:0x7fd41a8770d0 pending blocks:[]>
+    # => <#Concurrent::Edge::CompletableEvent:0x7fc623081100 pending blocks:[]>
 # Don't forget to keep the reference, `Concurrent.future.then { |v| v }` is incompletable
 
 # will be blocked until completed
 t1     = Thread.new { future.value } 
 t2     = Thread.new { event.wait } 
 
 future.success 1
-    # => <#Concurrent::Edge::CompletableFuture:0x7fd41a87c648 success blocks:[]>
+    # => <#Concurrent::Edge::CompletableFuture:0x7fc623083720 success blocks:[]>
 future.success 1 rescue $!
     # => #<Concurrent::MultipleAssignmentError: Future can be completed only once. Current result is [true, 1, nil], trying to set [true, 1, nil]>
 future.try_success 2                               # => false
 event.complete
-    # => <#Concurrent::Edge::CompletableEvent:0x7fd41a8770d0 completed blocks:[]>
+    # => <#Concurrent::Edge::CompletableEvent:0x7fc623081100 completed blocks:[]>
 
 [t1, t2].each &:join 
 
 
 ### Callbacks
 
-queue  = Queue.new                                 # => #<Thread::Queue:0x007fd41b0543e8>
+queue  = Queue.new                                 # => #<Thread::Queue:0x007fc62127df00>
 future = Concurrent.delay { 1 + 1 }
-    # => <#Concurrent::Edge::Future:0x7fd41b04f028 pending blocks:[]>
+    # => <#Concurrent::Edge::Future:0x7fc62127c060 pending blocks:[]>
 
 future.on_success { queue << 1 } # evaluated asynchronously
-    # => <#Concurrent::Edge::Future:0x7fd41b04f028 pending blocks:[]>
+    # => <#Concurrent::Edge::Future:0x7fc62127c060 pending blocks:[]>
 future.on_success! { queue << 2 } # evaluated on completing thread
-    # => <#Concurrent::Edge::Future:0x7fd41b04f028 pending blocks:[]>
+    # => <#Concurrent::Edge::Future:0x7fc62127c060 pending blocks:[]>
 
 queue.empty?                                       # => true
 future.value                                       # => 2
@@ -144,15 +152,15 @@
 ### Thread-pools
 
 Concurrent.future(:fast) { 2 }.then(:io) { File.read __FILE__ }.wait
-    # => <#Concurrent::Edge::Future:0x7fd41a857550 success blocks:[]>
+    # => <#Concurrent::Edge::Future:0x7fc62125d9a8 success blocks:[]>
 
 
 ### Interoperability with actors
 
 actor = Concurrent::Actor::Utils::AdHoc.spawn :square do
   -> v { v ** 2 }
 end
-    # => #<Concurrent::Actor::Reference:0x7fd41c03b5b8 /square (Concurrent::Actor::Utils::AdHoc)>
+    # => #<Concurrent::Actor::Reference:0x7fc621234a30 /square (Concurrent::Actor::Utils::AdHoc)>
 
 Concurrent.
     future { 2 }.
@@ -165,32 +173,32 @@
 
 ### Interoperability with channels
 
-ch1 = Concurrent::Edge::Channel.new                # => #<Concurrent::Edge::Channel:0x007fd41a297458>
-ch2 = Concurrent::Edge::Channel.new                # => #<Concurrent::Edge::Channel:0x007fd41a296940>
+ch1 = Concurrent::Edge::Channel.new                # => #<Concurrent::Edge::Channel:0x007fc621205460>
+ch2 = Concurrent::Edge::Channel.new                # => #<Concurrent::Edge::Channel:0x007fc6212041c8>
 
 result = Concurrent.select(ch1, ch2)
-    # => <#Concurrent::Edge::CompletableFuture:0x7fd41a295c98 pending blocks:[]>
+    # => <#Concurrent::Edge::CompletableFuture:0x7fc6211fe5c0 pending blocks:[]>
 ch1.push 1                                         # => nil
 result.value!
-    # => [1, #<Concurrent::Edge::Channel:0x007fd41a297458>]
+    # => [1, #<Concurrent::Edge::Channel:0x007fc621205460>]
 
 Concurrent.
     future { 1+1 }.
     then_push(ch1)
-    # => <#Concurrent::Edge::Future:0x7fd41a284010 pending blocks:[]>
+    # => <#Concurrent::Edge::Future:0x7fc6211f7338 pending blocks:[]>
 result = Concurrent.
     future { '%02d' }.
     then_select(ch1, ch2).
     then { |format, (value, channel)| format format, value }
-    # => <#Concurrent::Edge::Future:0x7fd41a25d938 pending blocks:[]>
+    # => <#Concurrent::Edge::Future:0x7fc6211ec668 pending blocks:[]>
 result.value!                                      # => "02"
 
 
 ### Common use-cases Examples
 
 # simple background processing
 Concurrent.future { do_stuff }
-    # => <#Concurrent::Edge::Future:0x7fd41a23d520 pending blocks:[]>
+    # => <#Concurrent::Edge::Future:0x7fc6211df170 pending blocks:[]>
 
 # parallel background processing
 jobs = 10.times.map { |i| Concurrent.future { i } } 
@@ -207,7 +215,7 @@ def schedule_job
 end                                                # => :schedule_job
 
 schedule_job
-    # => <#Concurrent::Edge::Future:0x7fd41a2245e8 pending blocks:[]>
+    # => <#Concurrent::Edge::Future:0x7fc62119c140 pending blocks:[]>
 @end = true                                        # => true
 
 
@@ -220,7 +228,7 @@ def schedule_job
     data[message]
   end
 end
-    # => #<Concurrent::Actor::Reference:0x7fd41a206228 /db (Concurrent::Actor::Utils::AdHoc)>
+    # => #<Concurrent::Actor::Reference:0x7fc62117f568 /db (Concurrent::Actor::Utils::AdHoc)>
 
 concurrent_jobs = 11.times.map do |v|
   Concurrent.
@@ -250,7 +258,7 @@ def schedule_job
     end
   end
 end
-    # => #<Concurrent::Actor::Reference:0x7fd41a0530c0 /DB-pool (Concurrent::Actor::Utils::Pool)>
+    # => #<Concurrent::Actor::Reference:0x7fc6218969f0 /DB-pool (Concurrent::Actor::Utils::Pool)>
 
 concurrent_jobs = 11.times.map do |v|
   Concurrent.