deferrable_gratification 0.1.0 → 0.2.0

data/README.markdown

@@ -1,64 +1,361 @@
 # Deferrable Gratification #
 
-## Purpose ##
+Deferrable Gratification (DG) facilitates asynchronous programming in Ruby, by
+helping create abstractions around complex operations built up from simpler
+ones.  It helps make asynchronous code less error-prone and easier to compose.
+It also provides some enhancements to the
+[`Deferrable`](http://eventmachine.rubyforge.org/EventMachine/Deferrable.html)
+API.
 
-Deferrable Gratification (DG) makes evented code less error-prone and easier to
-compose, and thus easier to create higher-level abstractions around.  It also
-enhances the API offered by Ruby Deferrables to make them more pleasant to work
-with.
+## Motivation ##
 
-## Documentation ##
+Asynchronous programming, as supported in Ruby by
+[EventMachine](http://rubyeventmachine.com/), offers the benefits of (limited)
+concurrency without the complexity of threads.  However, it requires a style of
+code that fits awkwardly into Ruby's synchronous semantics.
 
-* [API](http://samstokes.github.com/deferrable_gratification/doc/frames.html)
-* [Behaviour specs](http://samstokes.github.com/deferrable_gratification/doc/spec/index.html)
-  (generated from RSpec code examples)
+A method that performs an asynchronous operation cannot simply return a result:
+instead it must take a callback, which it calls with the eventual result of the
+operation.  That method's caller must also now take a callback, and so on up
+the call chain.  This means replacing a synchronous library such as
+[Net::HTTP](http://ruby-doc.org/stdlib-1.8.7/libdoc/net/http/rdoc/index.html)
+with an asynchronous library such as
+[em-http-request](https://github.com/igrigorik/em-http-request) can require
+rewriting a surprisingly large part of a codebase.
 
-## Components ##
+Ruby's block syntax initially seems to support this callback-passing style
+well.
 
-It currently consists of the following components:
+    asynchronously_fetch_page do |page|
+      # do something with 'page'...
+    end
 
- * [`DG::Fluent`](#fluent): fluent (aka chainable) syntax for registering
-   multiple callbacks and errbacks to the same Deferrable.
+The first problem is that, unlike regular method parameters, Ruby doesn't check
+that the caller remembered to provide a block, making it easy to create bugs by
+forgetting a callback.
 
- * [`DG::Bothback`](#bothback): a `#bothback` method for registering code to
-   run on either success or failure.
+    page = asynchronously_fetch_page
+    # returns immediately with no error.  'page' is probably nil.
 
- * [`DG::Combinators`](#combinators): a combinator library for building up
-   complex asynchronous operations out of simpler ones.
+Similarly the method implementer may forget to pass the callback down to nested
+calls, which can render the whole chain of asynchronous methods unable to
+return a result.  (The asynchronous operation might itself check that a
+callback was given, but asynchronous libraries will often not require a
+callback, in case they were invoked only for their side-effects.)
 
+    def first_thing(&callback)
+      second_thing(&callback)
+    end
+    def second_thing(&callback)
+      third_thing    # oops! no error though.
+    end
+    def third_thing(&callback)
+      compute_answer
+      yield 42 if block_given?
+    end
 
-<h3 id="fluent"><tt>DG::Fluent</tt></h3>
+    first_thing {|answer| puts answer }     # never runs
 
-Use JQuery-style fluent syntax for registering several callbacks and
-errbacks on the same Deferrable.  e.g.
+This is a symptom of a more general problem: only the outermost caller really
+cares about the callback being run, yet every method in the chain must be aware
+of it, which is poor encapsulation.
 
-     DeferrableMonkeyShaver.new(monkey).
-       callback { puts "Monkey is shaved" }.
-       callback { monkey.entertain! }.
-       errback {|e| puts "Unable to shave monkey! #{e}" }.
-       errback {|_| monkey.terminate! }.
-       shave
+This style also breaks down when the asynchronous operation needs to
+communicate failure: we want to pass in some code to be called on error, but
+Ruby's syntax only allows passing a single block to a method, so callers now
+need to pass in `lambda`s or hashes of `Proc`s, the syntax becomes inconsistent
+and noisy, and readability and maintainability suffer:
 
-<h3 id="bothback"><tt>DG::Bothback</tt></h3>
+    def first_thing(errback, &callback)
+      do_something
+      yield if block_given? # as declared, callback is implicitly optional
+    rescue => e
+      errback.call(e)       # as declared, errback is mandatory
+    end
 
-Register code to run on either success or failure: shorthand for calling both
-`#callback` and `#errback` with the same code block.
+    # Excessive punctuation alert!
+    first_thing(lambda {|error| handle_error }) {|result| use_result(result) }
 
-<h3 id="combinators"><tt>DG::Combinators</tt></h3>
+EventMachine offers the
+[Deferrable](http://eventmachine.rubyforge.org/EventMachine/Deferrable.html)
+pattern to communicate results of asynchronous operations in an object-oriented
+style more natural to Ruby.  Rather than taking a callback which it must
+remember to call, the method simply returns a `Deferrable` object which
+encapsulates the status of the operation, and promises to update that object at
+a later date.  Callers can register callbacks and errbacks on the Deferrable,
+which takes care of calling them when the operation succeeds or fails.
+Intermediate methods in the chain can simply pass the Deferrable on, and only
+code which cares about callbacks need know about them.
 
-Allows building up higher-level asynchronous abstractions by composing simpler
-asynchronous operations, without having to manually wire callbacks together
-and remember to propagate errors correctly.
+However, asynchronous programming with Deferrables still suffers from two key
+problems: it is difficult to compose multiple operations, and to build up
+complex operations from simpler ones.  Below is a method which performs three
+synchronous operations in sequence, each depending on the result of the
+previous, and returns the result of the last operation to the caller:
 
-Motivating example: assume we have an asynchronous database API `DB.query`
-which returns a Deferrable to communicate when the query finishes.  (See
-the [API docs for `DG::Combinators`](DeferrableGratification/Combinators.html)
-for more detail.)
+    def complex_operation
+      first_result = do_first_thing
+      second_result = do_second_thing(first_result)
+      third_result = do_third_thing(second_result)
+      third_result
+    rescue => e
+      # ...
+    end
 
-    def product_names_for_username(username)
-      DB.query('SELECT id FROM users WHERE username = ?', username).bind! do |user_id|
-        DB.query('SELECT name FROM products WHERE user_id = ?', user_id)
-      end.map do |product_names|
-        product_names.join(', ')
+When the operations are asynchronous, the same sequence is typically
+implemented using nested callbacks:
+
+    def complex_operation
+      result = EM::DefaultDeferrable.new
+      first_deferrable = do_first_thing
+      first_deferrable.callback do |first_result|
+        second_deferrable = do_second_thing(first_result)
+        second_deferrable.callback do |second_result|
+          third_deferrable = do_third_thing(second_result)
+          third_deferrable.callback do |third_result|
+            result.succeed(third_result)
+          end
+          third_deferrable.errback do |third_error|
+            result.fail(third_error)
+          end
+        end
+        second_deferrable.errback do |second_error|
+          result.fail(second_error)
+        end
+      end
+      first_deferrable.errback do |first_error|
+        result.fail(first_error)
       end
+      result
+    end
+
+Like the synchronous version, this method abstracts the multiple operations
+away from the caller and presents only the result the caller was interested in
+(or details of what went wrong).  However, the line count has tripled.  Worse,
+the program flow is confusing: the logic of 'do these operations in sequence'
+is obscured; the errbacks read in reverse order; and the way the final result
+makes its way back to the caller is almost invisible.  There are also a lot of
+opportunities to create bugs: all of the callbacks must be manually and
+repetitively "wired together", or the method will not work.
+
+Deferrable Gratification aims to solve these problems by providing a library of
+composition operators - combinators - which abstract away the boilerplate
+callback wiring and reveal the logic of the code.
+
+## Examples ##
+
+### [Fluent callback syntax](http://samstokes.github.com/deferrable_gratification/doc/DeferrableGratification/Fluent.html): because it feels right ###
+
+The return value of
+[`Deferrable#callback`](http://eventmachine.rubyforge.org/EventMachine/Deferrable.html#M000264)
+isn't useful, which means if you want to set a callback on a Deferrable and
+then return it, you have to name the Deferrable first, so you can return it
+explicitly.  You also have to mention the name again to set another callback,
+which leads to a lot of noisy repetition:
+
+    def google_homepage
+      request = EM::HttpRequest.new('http://google.com').get(:redirects => 1)
+      request.callback {|http| puts http.response }
+      request.callback { $call_count = ($call_count || 0) + 1 }
+      request.errback { puts "Oh noes!" }
+      request
+    end
+    EM.run { r = google_homepage; r.callback { EM.stop }; r.errback { EM.stop } }
+    # prints a lot of HTML
+
+DG lets you chain callbacks and errbacks using "fluent syntax" familiar from
+JQuery:
+
+    DG.enhance! EM::HttpClient
+
+    def google_homepage
+      EM::HttpRequest.new('http://google.com').get(:redirects => 1).
+        callback {|http| puts http.response }.
+        callback { $call_count = ($call_count || 0) + 1 }.
+        errback { puts "Oh noes!" }
+    end
+    EM.run { google_homepage.callback { EM.stop }.errback { EM.stop } }
+    # prints a lot of HTML
+
+### [`bothback`](http://samstokes.github.com/deferrable\_gratification/doc/DeferrableGratification/Bothback.html#bothback-instance\_method): when you absolutely, positively got to... ###
+
+Sometimes you need to do something after an asynchronous action completes,
+whether it succeeded or failed: e.g. release a lock, or as in the example
+above, call `EM.stop` to break out of the `EM.run` block.  It's annoying to
+have to write that code twice, to make sure it's called both on success and
+failure.
+
+`bothback` to the rescue:
+
+    EM.run { google_homepage.bothback { EM.stop } }
+    # prints a lot of HTML
+
+### [`transform`](http://samstokes.github.com/deferrable\_gratification/doc/DeferrableGratification/Combinators.html#transform-instance\_method): receive the callbacks that make sense for you ###
+
+The [em-http-request](https://github.com/igrigorik/em-http-request) library is
+great, but it's a bit fiddly to use, because it passes the whole
+[`EM::HttpClient`](http://rdoc.info/github/igrigorik/em-http-request/master/EventMachine/HttpClient)
+instance to its callbacks and errbacks.  That means your callbacks can check
+the response code and headers, but it also makes it harder if you just want
+quick access to the response body.
+
+    EM.run do
+      request = EM::HttpRequest.new('http://google.com').get(:redirects => 1)
+      request.
+        callback do |http|
+          # Have to write this code once for each different request
+          if http.response_header.status == 200
+            puts http.response
+          else
+            request.fail(http)   # triggers the errback as if the request had failed
+          end
+        end.errback {|http| handle_error(http) }.
+        bothback { EM.stop }
+    end
+    # prints lots of HTML
+
+Wouldn't it be great if we could encapsulate the logic of "just give me the
+response if the request was successful", and have callbacks that just act on
+the response body?
+
+    def fetch_page(url)
+      request = EM::HttpRequest.new(url).get(:redirects => 1)
+      request.transform do |http|
+        if http.response_header.status == 200
+          http.response
+        else
+          request.fail(http)
+        end
+      end
+    end
+
+    EM.run do
+      fetch_page('http://google.com').
+        callback {|html| puts html }.
+        errback {|http| puts "Oh dear!" }.
+        bothback { EM.stop }
     end
+    # prints lots of HTML
+
+That looks a lot cleaner.  It would be even cooler if instead of passing the
+raw HTML to callbacks, we could parse the HTML using
+[Hpricot](http://hpricot.com) and pass the parsed document instead.  No
+problem:
+
+    require 'hpricot'
+
+    def fetchpricot(url)
+      fetch_page(url).transform {|html| Hpricot(html) }
+    end
+
+    EM.run do
+      fetchpricot('http://google.com').
+        callback {|doc| puts doc.at(:title) }.
+        errback {|http| puts "Oh dear!" }.
+        bothback { EM.stop }
+    end
+    # prints <title>Google</title>
+
+### [`transform_error`](http://samstokes.github.com/deferrable\_gratification/doc/DeferrableGratification/Combinators.html#transform_error-instance\_method): receive the errbacks that make sense to you ###
+
+That's cool, but it's a bit annoying that those errbacks receive a `HttpClient`
+object - we have to turn that into a useful error message every time.  Let's
+encapsulate that too:
+
+    def fetchpricot2(url)
+      fetchpricot(url).transform_error do |http|
+        if http.response_header.status > 0
+          "Unexpected response code: #{http.response_header.status}"
+        else
+          "Unknown error!"
+        end
+      end
+    end
+
+    EM.run do
+      fetchpricot2('http://google.com/page_that_probably_does_not_exist').
+        callback {|doc| puts doc.at(:title) }.
+        errback {|error| puts "Error: #{error}" }.
+        bothback { EM.stop }
+    end
+    # prints "Error: Unexpected response code: 404"
+
+### [`bind!`](http://samstokes.github.com/deferrable\_gratification/doc/DeferrableGratification/Combinators.html#bind!-instance\_method): for when one thing leads to another ###
+
+Say we want to do a simple web crawling task: find the first search result for
+'deferrable_gratification', follow that link (which should be its Github page),
+and pull down the project website listed on that page.  Normally this would
+require some messy nesting of callbacks and errbacks:
+
+    EM.run do
+      fetchpricot2('http://google.com/search?q=deferrable_gratification').callback do |doc1|
+        fetchpricot2((doc1 / 'ol' / 'li' / 'a')[0][:href]).callback do |doc2|
+          fetchpricot2((doc2 / '#repository_homepage').at(:a)[:href]).callback do |doc3|
+            puts doc3.at(:title).inner_text
+            # I could also have mistyped 'doc3' as 'doc2' and got the wrong
+            # behaviour, but no exception to flag it
+          end.errback do |error|
+            puts "Error finding homepage link: #{error}"
+          end.bothback { EM.stop }
+        end.errback do |error|
+          puts "Error loading first search result: #{error}"
+          EM.stop
+        end
+      end.errback do |error|
+        puts "Error retrieving search results: #{error}"
+        EM.stop
+      end
+    end
+    # prints "Deferrable Gratification"
+
+With `Deferrable#bind!` we can remove the nesting and write something that
+looks more like the straight-line sequential flow:
+
+    EM.run do
+      fetchpricot2('http://google.com/search?q=deferrable_gratification').bind! do |doc|
+        fetchpricot2((doc / 'ol' / 'li' / 'a')[0][:href])
+      end.bind! do |doc|
+        fetchpricot2((doc / '#repository_homepage').at(:a)[:href])
+      end.callback do |doc|
+        puts doc.at(:title).inner_text
+        # now the previous 'doc's aren't in scope, so I can't accidentally
+        # refer to them
+      end.errback do |error|
+        puts "Error: #{error}"
+      end.bothback { EM.stop }
+    end
+    # prints "Deferrable Gratification"
+
+`bind!` also wires up the errbacks so we can just write a single errback that
+will fire if any step in the sequence fails; similarly we don't have to write
+`EM.stop` three times.
+
+## Getting started ##
+
+Install the gem:
+
+    gem install deferrable_gratification
+
+In your code:
+
+    require 'eventmachine'
+    require 'deferrable_gratification'
+    DG.enhance_all_deferrables!
+
+Make sure that the call to
+[`DG.enhance_all_deferrables!`](http://samstokes.github.com/deferrable_gratification/doc/DeferrableGratification.html#enhance_all_deferrables%21-class_method)
+comes *before* you require any library that uses `Deferrable` (e.g.
+[em-http-request](https://github.com/igrigorik/em-http-request)).
+
+### Temporary workaround because `enhance_all_deferrables!` is broken ###
+
+You actually need to call
+[`DG.enhance!`](http://samstokes.github.com/deferrable_gratification/doc/DeferrableGratification.html#enhance%21-class_method)
+on each Deferrable class you'll be dealing with. This call needs to come
+*after* that class is defined.
+
+## Documentation ##
+
+* [API](http://samstokes.github.com/deferrable_gratification/doc/frames.html)
+* [Behaviour specs](http://samstokes.github.com/deferrable_gratification/doc/spec/index.html)
+  (generated from RSpec code examples)

data/lib/deferrable_gratification/combinators.rb

@@ -12,7 +12,7 @@ module DeferrableGratification
   #   def product_names_for_username(username)
   #     DB.query('SELECT id FROM users WHERE username = ?', username).bind! do |user_id|
   #       DB.query('SELECT name FROM products WHERE user_id = ?', user_id)
-  #     end.map do |product_names|
+  #     end.transform do |product_names|
   #       product_names.join(', ')
   #     end
   #   end
@@ -131,17 +131,39 @@ module DeferrableGratification
     # Deferrable will also fail.
     #
     # @param &block block that transforms the expected result of this
-    # operation in some way.
+    #   operation in some way.
     #
     # @return [Deferrable] Deferrable that will succeed if this operation did,
     #   after transforming its result.
     #
     # @example Retrieve a web page and call back with its title.
-    #   HTTP.request(url).map {|page| Hpricot(page).at(:title).inner_html }
-    def map(&block)
+    #   HTTP.request(url).transform {|page| Hpricot(page).at(:title).inner_html }
+    def transform(&block)
       bind!(&block)
     end
 
+    # Transform the value passed to the errback of this Deferrable by invoking
+    # +block+.  If this operation succeeds, the returned Deferrable will
+    # succeed with the same value.  If this operation fails, the returned
+    # Deferrable will fail with the transformed error value.
+    #
+    # @param &block block that transforms the expected error value of this
+    #   operation in some way.
+    #
+    # @return [Deferrable] Deferrable that will succeed if this operation did,
+    #   otherwise fail after transforming the error value with which this
+    #   operation failed.
+    def transform_error(&block)
+      errback do |*err|
+        self.fail(
+          begin
+            yield(*err)
+          rescue => e
+            e
+          end)
+      end
+    end
+
 
     # Boilerplate hook to extend {ClassMethods}.
     def self.included(base)
@@ -167,6 +189,93 @@ module DeferrableGratification
       def chain(*actions)
         actions.inject(DG.const(nil), &:>>)
       end
+
+      # Combinator that waits for all of the supplied asynchronous operations
+      # to succeed or fail, then succeeds with the results of all those
+      # operations that were successful.
+      #
+      # This Deferrable will never fail.  It may also never succeed, if _any_
+      # of the supplied operations does not either succeed or fail.
+      #
+      # The successful results are guaranteed to be in the same order as the
+      # operations were passed in (which may _not_ be the same as the
+      # chronological order in which they succeeded).
+      #
+      # @param [*Deferrable] *operations deferred statuses of asynchronous
+      #   operations to wait for.
+      #
+      # @return [Deferrable] a deferred status that will succeed after all the
+      #   +operations+ have either succeeded or failed; its callbacks will be
+      #   passed an +Enumerable+ containing the results of those operations
+      #   that succeeded.
+      def join_successes(*operations)
+        Join::Successes.setup!(*operations)
+      end
+
+      # Combinator that waits for any of the supplied asynchronous operations
+      # to succeed, and succeeds with the result of the first (chronologically)
+      # to do so.
+      #
+      # This Deferrable will fail if all the operations fail.  It may never
+      # succeed or fail, if one of the operations also does not.
+      #
+      # @param (see #join_successes)
+      #
+      # @return [Deferrable] a deferred status that will succeed as soon as any
+      #   of the +operations+ succeeds; its callbacks will be passed the result
+      #   of that operation.
+      def join_first_success(*operations)
+        Join::FirstSuccess.setup!(*operations)
+      end
+
+      # Combinator that repeatedly executes the supplied block until it
+      # succeeds, then succeeds itself with the eventual result.
+      #
+      # This Deferrable may never succeed, if the operation never succeeds.
+      # It will fail if an iteration raises an exception.
+      #
+      # @note this combinator is intended for use inside EventMachine.  It will
+      #   still work outside of EventMachine, _provided_ that the operation is
+      #   synchronous (although a simple +while+ loop might be preferable in
+      #   this case!).
+      #
+      # @param loop_deferrable for internal use only, always omit this.
+      # @param &block operation to execute until it succeeds.
+      #
+      # @yieldreturn [Deferrable] deferred status of the operation.  If it
+      #   fails, the operation will be retried.  If it succeeds, the combinator
+      #   will succeed with the result.
+      #
+      # @return [Deferrable] a deferred status that will succeed once the
+      #   supplied operation eventually succeeds.
+      def loop_until_success(loop_deferrable = DefaultDeferrable.new, &block)
+        if EM.reactor_running?
+          EM.next_tick do
+            begin
+              attempt = yield
+            rescue => e
+              loop_deferrable.fail(e)
+            else
+              attempt.callback(&loop_deferrable.method(:succeed))
+              attempt.errback { loop_until_success(loop_deferrable, &block) }
+            end
+          end
+        else
+          # In the synchronous case, we could simply use the same
+          # implementation as in EM, but without the next_tick; unfortunately
+          # that means direct recursion, so risks stack overflow.  Instead we
+          # just reimplement as a loop.
+          results = []
+          begin
+            yield.callback {|*values| results << values } while results.empty?
+          rescue => e
+            loop_deferrable.fail(e)
+          else
+            loop_deferrable.succeed(*results[0])
+          end
+        end
+        loop_deferrable
+      end
     end
   end
 end

data/lib/deferrable_gratification/combinators/bind.rb

@@ -31,7 +31,7 @@ module DeferrableGratification
     # However, because Ruby doesn't actually type-check blocks, we can't
     # enforce that the block really does return a second Deferrable.  This
     # therefore also supports (reasonably) arbitrary blocks.  However, it's
-    # probably clearer (though equivalent) to use {#map} for this case.
+    # probably clearer (though equivalent) to use {#transform} for this case.
     class Bind < DefaultDeferrable
       # Prepare to bind +block+ to +first+, and create the Deferrable that
       # will represent the bind.
@@ -84,7 +84,7 @@ module DeferrableGratification
             second.errback {|*error| self.fail(*error) }
           else
             # Not a Deferrable, so we need to "behave sensibly" as alluded to
-            # above.  Just behaving like #map is sensible enough.
+            # above.  Just behaving like #transform is sensible enough.
             self.succeed(second)
           end
         end

data/lib/deferrable_gratification/combinators/join.rb

@@ -0,0 +1,129 @@
+require File.join(File.dirname(__FILE__), *%w[.. default_deferrable])
+
+module DeferrableGratification
+  module Combinators
+    # Abstract base class for combinators that depend on a number of
+    # asynchronous operations (potentially executing in parallel).
+    #
+    # @abstract Subclasses should override {#done?} to define whether they wait
+    #   for some or all of the operations to complete, and {#finish} to define
+    #   what they do when {#done?} returns true.
+    class Join < DefaultDeferrable
+      # Prepare to wait for the completion of +operations+.
+      #
+      # Does not actually set up any callbacks or errbacks: call {#setup!} for
+      # that.
+      #
+      # @param [*Deferrable] *operations deferred statuses of asynchronous
+      #   operations to wait for.
+      def initialize(*operations)
+        @operations = operations
+        @successes = Array.new(@operations.size, Sentinel.new)
+        @failures = Array.new(@operations.size, Sentinel.new)
+      end
+
+      # Register callbacks and errbacks on the supplied operations to notify
+      # this {Join} of completion.
+      def setup!
+        finish if done?
+
+        @operations.each_with_index do |op, index|
+          op.callback do |result|
+            @successes[index] = result
+            finish if done?
+          end
+          op.errback do |error|
+            @failures[index] = error
+            finish if done?
+          end
+        end
+      end
+
+      # Create a {Join} and register the callbacks.
+      #
+      # @param (see #initialize)
+      #
+      # @return [Join] Deferrable representing the join operation.
+      def self.setup!(*operations)
+        new(*operations).tap(&:setup!)
+      end
+
+
+      # Combinator that waits for all of the supplied asynchronous operations
+      # to succeed or fail, then succeeds with the results of all those
+      # operations that were successful.
+      #
+      # This Deferrable will never fail.  It may also never succeed, if _any_
+      # of the supplied operations does not either succeed or fail.
+      #
+      # The successful results are guaranteed to be in the same order as the
+      # operations were passed in (which may _not_ be the same as the
+      # chronological order in which they succeeded).
+      #
+      # You probably want to call {ClassMethods#join_successes} rather than
+      # using this class directly.
+      class Successes < Join
+        private
+        def done?
+          all_completed?
+        end
+
+        def finish
+          succeed(successes)
+        end
+      end
+
+
+      # Combinator that waits for any of the supplied asynchronous operations
+      # to succeed, and succeeds with the result of the first (chronologically)
+      # to do so.
+      #
+      # This Deferrable will fail if all the operations fail.  It may never
+      # succeed or fail, if one of the operations also does not.
+      #
+      # You probably want to call {ClassMethods#join_first_success} rather than
+      # using this class directly.
+      class FirstSuccess < Join
+        private
+        def done?
+          successes.length > 0
+        end
+
+        def finish
+          succeed(successes.first)
+        end
+      end
+
+
+      private
+      def successes
+        without_sentinels(@successes)
+      end
+
+      def failures
+        without_sentinels(@failures)
+      end
+
+      def all_completed?
+        successes.length + failures.length >= @operations.length
+      end
+
+      def done?
+        raise NotImplementedError, 'subclasses should override this'
+      end
+
+      def finish
+        raise NotImplementedError, 'subclasses should override this'
+      end
+
+      def without_sentinels(ary)
+        ary.reject {|item| item.instance_of? Sentinel }
+      end
+
+      # @private
+      # Used internally to distinguish between the absence of a response and
+      # a response with the value +nil+.
+      class Sentinel; end
+    end
+  end
+end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: deferrable_gratification
 version: !ruby/object:Gem::Version 
-  hash: 27
+  hash: 23
   prerelease: false
   segments: 
   - 0
-  - 1
+  - 2
   - 0
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors: 
 - Sam Stokes
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-01-15 00:00:00 -08:00
+date: 2011-01-21 00:00:00 -08:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -91,9 +91,9 @@ dependencies:
   type: :development
   version_requirements: *id005
 description: |
-  Deferrable Gratification (DG) makes evented code less error-prone and easier to compose, and thus easier to create higher-level abstractions around.  It also enhances the API offered by Ruby Deferrables to make them more pleasant to work with.
+  Deferrable Gratification (DG) facilitates asynchronous programming in Ruby, by helping create abstractions around complex operations built up from simpler ones.  It helps make asynchronous code less error-prone and easier to compose.  It also provides some enhancements to the Deferrable API.
   
-  Currently consists of the following components:
+  Features include:
   
    * fluent (aka chainable) syntax for registering multiple callbacks and errbacks to the same Deferrable.
   
@@ -113,6 +113,7 @@ files:
 - lib/deferrable_gratification.rb
 - lib/deferrable_gratification/default_deferrable.rb
 - lib/deferrable_gratification/combinators/bind.rb
+- lib/deferrable_gratification/combinators/join.rb
 - lib/deferrable_gratification/combinators.rb
 - lib/deferrable_gratification/bothback.rb
 - lib/deferrable_gratification/fluent.rb