ione 1.2.0.pre9 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 269fc51bb786b26f473b2eec82fb37495832842e
-  data.tar.gz: 7c709b42991c6879f9a0cd1df579e31b158a0d32
+  metadata.gz: 7b16fd5d35a6cd0dd75c20ea9a3febd681f5a37b
+  data.tar.gz: 5aff84c71ae8a849858789063b528ed59b45c87c
 SHA512:
-  metadata.gz: 5e984ed67e16f8dcbcd10671e3033f911b17af68eb5cb2e11231c01dd4dd83fdaff70681e928100226dafbd7fb027ebe64bc20d178a3e216945ce7bd7134a9a2
-  data.tar.gz: 37dc89c4553b85de563ea94caffc8d07f555e622c1ab3d00170be9dfb6c47ae0d7c754ce6eac09a586eaff3040ad065db6a05e61eca35201737f6ab397a0b96c
+  metadata.gz: b6e57d6dc85d7b329353e8d7ff2cb8ba606ff2431377fb7f1e7ca1badf6e0b1ccc7e3971d03cf28387798b307c85cbb32de4c0dbc2851664e096447b190b7215
+  data.tar.gz: c6825f4358471a8c344f39f3473dc6c11d8f3367886d25953de255c84ebf53f214098f3deeb46471a323ef1a5b628c72e271a910d6930db5d146bba885ba29e6

data/README.md

@@ -4,7 +4,7 @@
 [![Coverage Status](https://coveralls.io/repos/iconara/ione/badge.png)](https://coveralls.io/r/iconara/ione)
 [![Blog](http://b.repl.ca/v1/blog-ione-ff69b4.png)](http://architecturalatrocities.com/tagged/ione)
 
-_If you're reading this on GitHub, please note that this is the readme for the development version and that some features described here might not yet have been released. You can find the readme for a specific version either through [rubydoc.info](http://rubydoc.info/find/gems?q=ione) or via the release tags ([here is an example](https://github.com/iconara/ione/tree/v1.0.0.pre0))._
+_If you're reading this on GitHub, please note that this is the readme for the development version and that some features described here might not yet have been released. You can find the readme for a specific version either through [rubydoc.info](http://rubydoc.info/find/gems?q=ione) or via the release tags ([here is an example](https://github.com/iconara/ione/tree/v1.2.0))._
 
 Ione is a framework for reactive programming in Ruby. It is based on the reactive core of [cql-rb](http://github.com/iconara/cql-rb), the Ruby driver for Cassandra.
 
@@ -29,6 +29,7 @@ The [examples](https://github.com/iconara/ione/tree/master/examples) directory h
 * [redis_client](https://github.com/iconara/ione/tree/master/examples/redis_client) is a more or less full featured Redis client that uses most of Ione's features.
 * [http_client](https://github.com/iconara/ione/tree/master/examples/http_client) is a simplistic HTTP client that uses Ione and [http_parser.rb](http://rubygems.org/gems/http_parser.rb) to make HTTP GET request.
 * [cql-rb](https://github.com/iconara/cql-rb) is a high performance Cassandra driver and where Ione was originally developed.
+* [cassandra-driver](https://github.com/datastax/ruby-driver) is the successor to cql-rb.
 * [ione-rpc](https://github.com/iconara/ione-rpc) is a RPC framework built on Ione. It makes it reasonably easy to build networked applications without having to reinvent the wheel.
 
 # How to contribute

data/lib/ione/future.rb

@@ -79,362 +79,475 @@ module Ione
     end
   end
 
-  module FutureFactories
-    # Combines multiple futures into a new future which resolves when all
-    # constituent futures complete, or fails when one or more of them fails.
-    #
-    # The value of the combined future is an array of the values of the
-    # constituent futures.
-    #
-    # @param [Array<Ione::Future>] futures the futures to combine (this argument
-    #   can be a splatted array or a regular array passed as sole argument)
-    # @return [Ione::Future<Array>] an array of the values of the constituent
-    #   futures
-    def all(*futures)
-      if futures.size == 1 && (fs = futures.first).is_a?(Enumerable)
-        futures = fs
-      end
-      if futures.count == 0
-        resolved([])
-      else
-        CombinedFuture.new(futures)
+  # A future represents the value of a process that may not yet have completed.
+  #
+  # A future is either pending or completed and there are two ways to complete a
+  # future: either by resolving it to a value, or by failing it.
+  #
+  # A future is usually created by first creating a {Promise} and returning that
+  # promise's future to the caller. The promise can then be _fulfilled_ which
+  # resolves the future – see below for an example of thi.
+  #
+  # The key thing about futures is that they _compose_. If you have a future
+  # you can transform it and combine without waiting for its value to be
+  # available. This means that you can model a series of asynchronous operations
+  # without worrying about which order they will complete in, or what happens
+  # if any of them fail. You can describe the steps you want to happen if all
+  # goes well, and add a handler at the end to capture errors, like you can
+  # with synchronous code and exception handlers. You can also add steps that
+  # recover from failures. See below, and the docs for {Combinators} for examples
+  # on how to compose asynchronous operations.
+  #
+  # The mixins {Combinators}, {Callbacks} and {Factories} contain most of the
+  # method you would use to work with futures, and can be used for creating bridges
+  # to other futures implementations.
+  #
+  # @example Creating a future for a blocking operation
+  #   def find_my_ip
+  #     promise = Promse.new
+  #     Thread.start do
+  #       begin
+  #         data = JSON.load(open('http://jsonip.org/').read)
+  #         promise.fulfill(data['ip'])
+  #       rescue => e
+  #         promise.fail(e)
+  #       end
+  #     end
+  #     promise.future
+  #   end
+  #
+  # @example Transforming futures
+  #   # find_my_ip is the method from the example above
+  #   ip_future = find_my_ip
+  #   # Future#map returns a new future that resolves to the value returned by the
+  #   # block, but the block is not called immediately, but when the receiving
+  #   # future resolves – this means that we can descrbe the processing steps that
+  #   # should be performed without having to worry about when the value becomes
+  #   # available.
+  #   ipaddr_future = ip_future.map { |ip| IPAddr.new(ip) }
+  #
+  # @example Composing asynchronous operations
+  #   # find_my_ip is the method from the example above
+  #   ip_future = find_my_ip
+  #   # Future#flat_map is a way of chaining asynchronous operations, the future
+  #   # it returns will resolve to the value of the future returned by the block,
+  #   # but the block is not called until the receiver future resolves
+  #   location_future = ip_future.flat_map do |ip|
+  #     # assuming resolve_geoip is a method returning a future
+  #     resolve_geoip(ip)
+  #   end
+  #   # scheduler here could be an instance of Ione::Io::IoReactor
+  #   timer_future = scheduler.schedule_timer(5)
+  #   # Future.first returns a future that will resolve to the value of the
+  #   # first of its children that completes, so you can use it in combination
+  #   # with a scheduler to make sure you don't wait forever
+  #   location_or_timeout_future = Future.first(location_future, timer_future)
+  #   location_or_timeout_future.on_value do |location|
+  #     if location
+  #       puts "My location is #{location}"
+  #     end
+  #   end
+  #
+  # @example Making requests in parallel and collecting the results
+  #   # assuming client is a client for a remote service and that #find returns
+  #   # a future, and that thing_ids is an array of IDs of things we want to load
+  #   futures = thing_idss.map { |id| client.find(id) }
+  #   # Future.all is a way to combine multiple futures into a future that resolves
+  #   # to an array of values, in other words, it takes an array of futures and
+  #   # resolves to an array of the values of those futures
+  #   future_of_all_things = Future.all(futures)
+  #   future_of_all_things.on_value do |things|
+  #     things.each do |thing|
+  #       puts "here's a thing: #{thing}"
+  #     end
+  #   end
+  #
+  # @example Another way of making requests in parallel and collecting the results
+  #   # the last example can be simplified by using Future.traverse, which combines
+  #   # Array#map with Future.all – the block will be called once per item in
+  #   # the array, and the returned future resolves to an array of the values of
+  #   # the futures returned by the block
+  #   future_of_all_things = Future.traverse(thing_ids) { |id| client.find(id) }
+  #   future_of_all_things.on_value do |things|
+  #     things.each do |thing|
+  #       puts "here's a thing: #{thing}"
+  #     end
+  #   end
+  #
+  # @see Ione::Promise
+  # @see Ione::Future::FutureCallbacks
+  # @see Ione::Future::FutureCombinators
+  # @see Ione::Future::FutureFactories
+  class Future
+    module Factories
+      # Combines multiple futures into a new future which resolves when all
+      # constituent futures complete, or fails when one or more of them fails.
+      #
+      # The value of the combined future is an array of the values of the
+      # constituent futures.
+      #
+      # @example
+      #   ids = [1, 2, 3, 4]
+      #   futures = ids.map { |id| find_thing(id) }
+      #   future = Future.all(ids)
+      #   future.value # => [thing1, thing2, thing3, thing4]
+      #
+      # @param [Array<Ione::Future>] futures the futures to combine (this argument
+      #   can be a splatted array or a regular array passed as sole argument)
+      # @return [Ione::Future<Array>] an array of the values of the constituent
+      #   futures
+      def all(*futures)
+        if futures.size == 1 && (fs = futures.first).is_a?(Enumerable)
+          futures = fs
+        end
+        if futures.count == 0
+          resolved([])
+        else
+          CombinedFuture.new(futures)
+        end
       end
-    end
 
-    # Returns a future which will be resolved with the value of the first
-    # (resolved) of the specified futures. If all of the futures fail, the
-    # returned future will also fail (with the error of the last failed future).
-    #
-    # @param [Array<Ione::Future>] futures the futures to monitor (this argument
-    #   can be a splatted array or a regular array passed as sole argument)
-    # @return [Ione::Future] a future which represents the first completing future
-    def first(*futures)
-      if futures.size == 1 && (fs = futures.first).is_a?(Enumerable)
-        futures = fs
-      end
-      if futures.count == 0
-        resolved
-      else
-        FirstFuture.new(futures)
+      # Returns a future which will be resolved with the value of the first
+      # (resolved) of the specified futures. If all of the futures fail, the
+      # returned future will also fail (with the error of the last failed future).
+      #
+      # @example Speculative execution
+      #   # make a call to multiple services and use the value of the one that
+      #   # responds first – and discard the other results
+      #   f1 = service1.find_thing(id)
+      #   f2 = service2.find_thing(id)
+      #   f3 = service3.find_thing(id)
+      #   f = Future.first(f1, f2, f3)
+      #   f.value # => the value of the call that was quickest
+      #
+      # @param [Array<Ione::Future>] futures the futures to monitor (this argument
+      #   can be a splatted array or a regular array passed as sole argument)
+      # @return [Ione::Future] a future which represents the first completing future
+      def first(*futures)
+        if futures.size == 1 && (fs = futures.first).is_a?(Enumerable)
+          futures = fs
+        end
+        if futures.count == 0
+          resolved
+        else
+          FirstFuture.new(futures)
+        end
       end
-    end
-
-    # Takes calls the block once for each element in an array, expecting each
-    # invocation to return a future, and returns a future that resolves to
-    # an array of the values of those futures.
-    #
-    # @example
-    #   ids = [1, 2, 3]
-    #   future = Future.traverse(ids) { |id| load_thing(id) }
-    #   future.value # => [thing1, thing2, thing3]
-    #
-    # @param [Array<Object>] values an array whose elements will be passed to
-    #   the block, one by one
-    # @yieldparam [Object] value each element from the array
-    # @yieldreturn [Ione::Future] a future
-    # @return [Ione::Future] a future that will resolve to an array of the values
-    #   of the futures returned by the block
-    def traverse(values, &block)
-      all(values.map(&block))
-    rescue => e
-      failed(e)
-    end
 
-    # Returns a future that will resolve to a value which is the reduction of
-    # the values of a list of source futures.
-    #
-    # This is essentially a parallel, streaming version of {Enumerable#reduce},
-    # but for futures. Use this method for example when you want to do a number
-    # of asynchronous operations in parallel and then merge the results together
-    # when all are done.
-    #
-    # The block will not be called concurrently, which means that unless you're
-    # handling the initial value or other values in the scope of the block you
-    # don't need (and shouldn't) do any locking to ensure that the accumulator
-    # passed to the block is safe to modify. It is, of course, even better if
-    # you don't modify the accumulator, but return a new, immutable value on
-    # each invocation.
-    #
-    # @example Merging the results of multipe asynchronous calls
-    #   futures = ... # a list of futures that will resolve to hashes
-    #   merged_future = Future.reduce(futures, {}) do |accumulator, value|
-    #     accumulator.merge(value)
-    #   end
-    #
-    # @example Reducing with an associative and commutative function, like addition
-    #   futures = ... # a list of futures that will resolve to numbers
-    #   sum_future = Future.reduce(futures, 0, ordered: false) do |accumulator, value|
-    #     accumulator + value
-    #   end
-    #
-    # @param [Array<Ione::Future>] futures an array of futures whose values
-    #   should be reduced
-    # @param [Object] initial_value the initial value of the accumulator
-    # @param [Hash] options
-    # @option options [Boolean] :ordered (true) whether or not to respect the
-    #   order of the input when reducing – when true the block will be called
-    #   with the values of the source futures in the order they have in the
-    #   given list, when false the block will be called in the order that the
-    #   futures resolve (which means that your reducer function needs to be
-    #   associative and commutative).
-    # @yieldparam [Object] accumulator the value of the last invocation of the
-    #   block, or the initial value if this is the first invocation
-    # @yieldparam [Object] value the value of one of the source futures
-    # @yieldreturn [Object] the value to pass as accumulator to the next
-    #   invocation of the block
-    # @return [Ione::Future] a future that will resolve to the value returned
-    #   from the last invocation of the block, or nil when the list of futures
-    #   is empty.
-    def reduce(futures, initial_value=nil, options=nil, &reducer)
-      if options && options[:ordered] == false
-        UnorderedReducingFuture.new(futures, initial_value, reducer)
-      else
-        OrderedReducingFuture.new(futures, initial_value, reducer)
+      # Takes calls the block once for each element in an array, expecting each
+      # invocation to return a future, and returns a future that resolves to
+      # an array of the values of those futures.
+      #
+      # @example
+      #   ids = [1, 2, 3]
+      #   future = Future.traverse(ids) { |id| find_thing(id) }
+      #   future.value # => [thing1, thing2, thing3]
+      #
+      # @param [Array<Object>] values an array whose elements will be passed to
+      #   the block, one by one
+      # @yieldparam [Object] value each element from the array
+      # @yieldreturn [Ione::Future] a future
+      # @return [Ione::Future] a future that will resolve to an array of the values
+      #   of the futures returned by the block
+      def traverse(values, &block)
+        all(values.map(&block))
+      rescue => e
+        failed(e)
       end
-    end
-
-    # Creates a new pre-resolved future.
-    #
-    # @param [Object, nil] value the value of the created future
-    # @return [Ione::Future] a resolved future
-    def resolved(value=nil)
-      return ResolvedFuture::NIL if value.nil?
-      ResolvedFuture.new(value)
-    end
-
-    # Creates a new pre-failed future.
-    #
-    # @param [Error] error the error of the created future
-    # @return [Ione::Future] a failed future
-    def failed(error)
-      FailedFuture.new(error)
-    end
-  end
 
-  module FutureCombinators
-    # Returns a new future representing a transformation of this future's value.
-    #
-    # @example
-    #   future2 = future1.map { |value| value * 2 }
-    #
-    # @param [Object] value the value of this future (when no block is given)
-    # @yieldparam [Object] value the value of this future
-    # @yieldreturn [Object] the transformed value
-    # @return [Ione::Future] a new future representing the transformed value
-    def map(value=nil, &block)
-      f = CompletableFuture.new
-      on_complete do |v, e|
-        if e
-          f.fail(e)
+      # Returns a future that will resolve to a value which is the reduction of
+      # the values of a list of source futures.
+      #
+      # This is essentially a parallel, streaming version of `Enumerable#reduce`,
+      # but for futures. Use this method for example when you want to do a number
+      # of asynchronous operations in parallel and then merge the results together
+      # when all are done.
+      #
+      # The block will not be called concurrently, which means that unless you're
+      # handling the initial value or other values in the scope of the block you
+      # don't need (and shouldn't) do any locking to ensure that the accumulator
+      # passed to the block is safe to modify. It is, of course, even better if
+      # you don't modify the accumulator, but return a new, immutable value on
+      # each invocation.
+      #
+      # @example Merging the results of multipe asynchronous calls
+      #   futures = ... # a list of futures that will resolve to hashes
+      #   merged_future = Future.reduce(futures, {}) do |accumulator, value|
+      #     accumulator.merge(value)
+      #   end
+      #   merged_future.value # => the result of {}.merge(hash1).merge(hash2), etc.
+      #
+      # @example Reducing with an associative and commutative function, like addition
+      #   futures = ... # a list of futures that will resolve to numbers
+      #   sum_future = Future.reduce(futures, 0, ordered: false) do |accumulator, value|
+      #     accumulator + value
+      #   end
+      #   sum_future.value # => the sum of all values
+      #
+      # @param [Array<Ione::Future>] futures an array of futures whose values
+      #   should be reduced
+      # @param [Object] initial_value the initial value of the accumulator
+      # @param [Hash] options
+      # @option options [Boolean] :ordered (true) whether or not to respect the
+      #   order of the input when reducing – when true the block will be called
+      #   with the values of the source futures in the order they have in the
+      #   given list, when false the block will be called in the order that the
+      #   futures resolve (which means that your reducer function needs to be
+      #   associative and commutative).
+      # @yieldparam [Object] accumulator the value of the last invocation of the
+      #   block, or the initial value if this is the first invocation
+      # @yieldparam [Object] value the value of one of the source futures
+      # @yieldreturn [Object] the value to pass as accumulator to the next
+      #   invocation of the block
+      # @return [Ione::Future] a future that will resolve to the value returned
+      #   from the last invocation of the block, or nil when the list of futures
+      #   is empty.
+      def reduce(futures, initial_value=nil, options=nil, &reducer)
+        if options && options[:ordered] == false
+          UnorderedReducingFuture.new(futures, initial_value, reducer)
         else
-          begin
-            f.resolve(block ? block.call(v) : value)
-          rescue => e
-            f.fail(e)
-          end
+          OrderedReducingFuture.new(futures, initial_value, reducer)
         end
       end
-      f
+
+      # Creates a new pre-resolved future.
+      #
+      # @param [Object, nil] value the value of the created future
+      # @return [Ione::Future] a resolved future
+      def resolved(value=nil)
+        return ResolvedFuture::NIL if value.nil?
+        ResolvedFuture.new(value)
+      end
+
+      # Creates a new pre-failed future.
+      #
+      # @param [Error] error the error of the created future
+      # @return [Ione::Future] a failed future
+      def failed(error)
+        FailedFuture.new(error)
+      end
     end
 
-    # Returns a new future representing a transformation of this future's value,
-    # but where the transformation itself may be asynchronous.
-    #
-    # @example
-    #   future2 = future1.flat_map { |value| method_returning_a_future(value) }
-    #
-    # This method is useful when you want to chain asynchronous operations.
-    #
-    # @yieldparam [Object] value the value of this future
-    # @yieldreturn [Ione::Future] a future representing the transformed value
-    # @return [Ione::Future] a new future representing the transformed value
-    def flat_map(&block)
-      f = CompletableFuture.new
-      on_complete do |v, e|
-        if e
-          f.fail(e)
-        else
-          begin
-            ff = block.call(v)
-            ff.on_complete do |vv, ee|
-              if ee
-                f.fail(ee)
-              else
-                f.resolve(vv)
-              end
-            end
-          rescue => e
+    module Combinators
+      # Returns a new future representing a transformation of this future's value.
+      #
+      # @example
+      #   future2 = future1.map { |value| value * 2 }
+      #
+      # @param [Object] value the value of this future (when no block is given)
+      # @yieldparam [Object] value the value of this future
+      # @yieldreturn [Object] the transformed value
+      # @return [Ione::Future] a new future representing the transformed value
+      def map(value=nil, &block)
+        f = CompletableFuture.new
+        on_complete do |v, e|
+          if e
             f.fail(e)
+          else
+            begin
+              f.resolve(block ? block.call(v) : value)
+            rescue => e
+              f.fail(e)
+            end
           end
         end
+        f
       end
-      f
-    end
 
-    # Returns a new future representing a transformation of this future's value,
-    # similarily to {#map}, but acts as {#flat_map} when the block returns a
-    # {Future}.
-    #
-    # This method is useful when you want to transform the value of a future,
-    # but whether or not it can be done synchronously or require an asynchronous
-    # operation depends on the value of the future.
-    #
-    # @example
-    #   future1 = load_something
-    #   future2 = future1.then do |result|
-    #     if result.empty?
-    #       # make a new async call to load fallback value
-    #       load_something_else
-    #     else
-    #       result
-    #     end
-    #   end
-    #
-    # @yieldparam [Object] value the value of this future
-    # @yieldreturn [Object, Ione::Future] the transformed value, or a future
-    #   that will resolve to the transformed value.
-    # @return [Ione::Future] a new future representing the transformed value
-    def then(&block)
-      f = CompletableFuture.new
-      on_complete do |v, e|
-        if e
-          f.fail(e)
-        else
-          begin
-            fv = block.call(v)
-            if fv.respond_to?(:on_complete)
-              fv.on_complete do |vv, ee|
+      # Returns a new future representing a transformation of this future's value,
+      # but where the transformation itself may be asynchronous.
+      #
+      # @example
+      #   future2 = future1.flat_map { |value| method_returning_a_future(value) }
+      #
+      # This method is useful when you want to chain asynchronous operations.
+      #
+      # @yieldparam [Object] value the value of this future
+      # @yieldreturn [Ione::Future] a future representing the transformed value
+      # @return [Ione::Future] a new future representing the transformed value
+      def flat_map(&block)
+        f = CompletableFuture.new
+        on_complete do |v, e|
+          if e
+            f.fail(e)
+          else
+            begin
+              ff = block.call(v)
+              ff.on_complete do |vv, ee|
                 if ee
                   f.fail(ee)
                 else
                   f.resolve(vv)
                 end
               end
-            else
-              f.resolve(fv)
+            rescue => e
+              f.fail(e)
             end
-          rescue => e
-            f.fail(e)
           end
         end
+        f
       end
-      f
-    end
 
-    # Returns a new future which represents either the value of the original
-    # future, or the result of the given block, if the original future fails.
-    #
-    # This method is similar to {#map}, but is triggered by a failure. You can
-    # also think of it as a `rescue` block for asynchronous operations.
-    #
-    # If the block raises an error a failed future with that error will be
-    # returned (this can be used to transform an error into another error,
-    # instead of tranforming an error into a value).
-    #
-    # @example
-    #   future2 = future1.recover { |error| 'foo' }
-    #   future1.fail(error)
-    #   future2.value # => 'foo'
-    #
-    # @param [Object] value the value when no block is given
-    # @yieldparam [Object] error the error from the original future
-    # @yieldreturn [Object] the value of the new future
-    # @return [Ione::Future] a new future representing a value recovered from the error
-    def recover(value=nil, &block)
-      f = CompletableFuture.new
-      on_complete do |v, e|
-        if e
-          begin
-            f.resolve(block ? block.call(e) : value)
-          rescue => e
+      # Returns a new future representing a transformation of this future's value,
+      # similarily to {#map}, but acts as {#flat_map} when the block returns a
+      # {Future}.
+      #
+      # This method is useful when you want to transform the value of a future,
+      # but whether or not it can be done synchronously or require an asynchronous
+      # operation depends on the value of the future.
+      #
+      # @example
+      #   future1 = load_something
+      #   future2 = future1.then do |result|
+      #     if result.empty?
+      #       # make a new async call to load fallback value
+      #       load_something_else
+      #     else
+      #       result
+      #     end
+      #   end
+      #
+      # @yieldparam [Object] value the value of this future
+      # @yieldreturn [Object, Ione::Future] the transformed value, or a future
+      #   that will resolve to the transformed value.
+      # @return [Ione::Future] a new future representing the transformed value
+      def then(&block)
+        f = CompletableFuture.new
+        on_complete do |v, e|
+          if e
             f.fail(e)
+          else
+            begin
+              fv = block.call(v)
+              if fv.respond_to?(:on_complete)
+                fv.on_complete do |vv, ee|
+                  if ee
+                    f.fail(ee)
+                  else
+                    f.resolve(vv)
+                  end
+                end
+              else
+                f.resolve(fv)
+              end
+            rescue => e
+              f.fail(e)
+            end
           end
-        else
-          f.resolve(v)
         end
+        f
       end
-      f
-    end
 
-    # Returns a new future which represents either the value of the original
-    # future, or the value of the future returned by the given block.
-    #
-    # This is like {#recover} but for cases when the handling of an error is
-    # itself asynchronous. In other words, {#fallback} is to {#recover} what
-    # {#flat_map} is to {#map}.
-    #
-    # If the block raises an error a failed future with that error will be
-    # returned (this can be used to transform an error into another error,
-    # instead of tranforming an error into a value).
-    #
-    # @example
-    #   result = http_get('/foo/bar').fallback do |error|
-    #     http_get('/baz')
-    #   end
-    #   result.value # either the response to /foo/bar, or if that failed
-    #                # the response to /baz
-    #
-    # @yieldparam [Object] error the error from the original future
-    # @yieldreturn [Object] the value of the new future
-    # @return [Ione::Future] a new future representing a value recovered from the
-    #   error
-    def fallback(&block)
-      f = CompletableFuture.new
-      on_complete do |v, e|
-        if e
-          begin
-            ff = block.call(e)
-            ff.on_complete do |vv, ee|
-              if ee
-                f.fail(ee)
-              else
-                f.resolve(vv)
+      # Returns a new future which represents either the value of the original
+      # future, or the result of the given block, if the original future fails.
+      #
+      # This method is similar to {#map}, but is triggered by a failure. You can
+      # also think of it as a `rescue` block for asynchronous operations.
+      #
+      # If the block raises an error a failed future with that error will be
+      # returned (this can be used to transform an error into another error,
+      # instead of tranforming an error into a value).
+      #
+      # @example
+      #   future2 = future1.recover { |error| 'foo' }
+      #   future1.fail(error)
+      #   future2.value # => 'foo'
+      #
+      # @param [Object] value the value when no block is given
+      # @yieldparam [Object] error the error from the original future
+      # @yieldreturn [Object] the value of the new future
+      # @return [Ione::Future] a new future representing a value recovered from the error
+      def recover(value=nil, &block)
+        f = CompletableFuture.new
+        on_complete do |v, e|
+          if e
+            begin
+              f.resolve(block ? block.call(e) : value)
+            rescue => e
+              f.fail(e)
+            end
+          else
+            f.resolve(v)
+          end
+        end
+        f
+      end
+
+      # Returns a new future which represents either the value of the original
+      # future, or the value of the future returned by the given block.
+      #
+      # This is like {#recover} but for cases when the handling of an error is
+      # itself asynchronous. In other words, {#fallback} is to {#recover} what
+      # {#flat_map} is to {#map}.
+      #
+      # If the block raises an error a failed future with that error will be
+      # returned (this can be used to transform an error into another error,
+      # instead of tranforming an error into a value).
+      #
+      # @example
+      #   result = http_get('/foo/bar').fallback do |error|
+      #     http_get('/baz')
+      #   end
+      #   result.value # either the response to /foo/bar, or if that failed
+      #                # the response to /baz
+      #
+      # @yieldparam [Object] error the error from the original future
+      # @yieldreturn [Object] the value of the new future
+      # @return [Ione::Future] a new future representing a value recovered from the
+      #   error
+      def fallback(&block)
+        f = CompletableFuture.new
+        on_complete do |v, e|
+          if e
+            begin
+              ff = block.call(e)
+              ff.on_complete do |vv, ee|
+                if ee
+                  f.fail(ee)
+                else
+                  f.resolve(vv)
+                end
               end
+            rescue => e
+              f.fail(e)
             end
-          rescue => e
-            f.fail(e)
+          else
+            f.resolve(v)
           end
-        else
-          f.resolve(v)
         end
+        f
       end
-      f
     end
-  end
 
-  module FutureCallbacks
-    # Registers a listener that will be called when this future becomes
-    # resolved. The listener will be called with the value of the future as
-    # sole argument.
-    #
-    # @yieldparam [Object] value the value of the resolved future
-    def on_value(&listener)
-      on_complete do |value, error|
-        listener.call(value) unless error
+    module Callbacks
+      # Registers a listener that will be called when this future becomes
+      # resolved. The listener will be called with the value of the future as
+      # sole argument.
+      #
+      # @yieldparam [Object] value the value of the resolved future
+      def on_value(&listener)
+        on_complete do |value, error|
+          listener.call(value) unless error
+        end
+        nil
       end
-      nil
-    end
 
-    # Registers a listener that will be called when this future fails. The
-    # lisener will be called with the error that failed the future as sole
-    # argument.
-    #
-    # @yieldparam [Error] error the error that failed the future
-    def on_failure(&listener)
-      on_complete do |_, error|
-        listener.call(error) if error
+      # Registers a listener that will be called when this future fails. The
+      # lisener will be called with the error that failed the future as sole
+      # argument.
+      #
+      # @yieldparam [Error] error the error that failed the future
+      def on_failure(&listener)
+        on_complete do |_, error|
+          listener.call(error) if error
+        end
+        nil
       end
-      nil
     end
-  end
 
-  # A future represents the value of a process that may not yet have completed.
-  #
-  # @see Ione::Promise
-  class Future
-    extend FutureFactories
-    include FutureCombinators
-    include FutureCallbacks
+    extend Factories
+    include Combinators
+    include Callbacks
 
     def initialize
       @lock = Mutex.new
@@ -444,9 +557,42 @@ module Ione
 
     # Registers a listener that will be called when this future completes,
     # i.e. resolves or fails. The listener will be called with the future as
-    # solve argument
-    #
-    # @yieldparam [Ione::Future] future the future
+    # solve argument.
+    #
+    # The order in which listeners are called is not defined and implementation
+    # dependent. The thread the listener will be called on is also not defined
+    # and implementation dependent. The default implementation calls listeners
+    # registered before completion on the thread that completed the future, and
+    # listeners registered after completions on the thread that registers the
+    # listener – but this may change in the future, and may be different in
+    # special circumstances.
+    #
+    # When a listener raises an error it will be swallowed and not re-raised.
+    # The reason for this is that the processing of the callback may be done
+    # in a context that does not expect, nor can recover from, errors. Not
+    # swallowing errors would stop other listeners from being called. If it
+    # appears as if a listener is not called, first make sure it is not raising
+    # any errors (even a syntax error or a spelling mistake in a method or
+    # variable name will not be hidden).
+    #
+    # @note
+    #   Depending on the arity of the listener it will be passed different
+    #   arguments. When the listener takes one argument it will receive the
+    #   future itself as argument (this is backwards compatible with the pre
+    #   v1.2 behaviour), with two arguments the value and error are given,
+    #   with three arguments the value, error and the future itself will be
+    #   given. The listener can also take no arguments. See the tests to find
+    #   out the nitty-gritty details, for example the behaviour with different
+    #   combinations of variable arguments and default values.
+    #
+    #   Most of the time you will use {#on_value} and {#on_failure}, and not
+    #   instead of this method.
+    #
+    # @yieldparam [Object] value the value that the future resolves to
+    # @yieldparam [Error] error the error that failed this future
+    # @yieldparam [Ione::Future] future the future itself
+    # @see Callbacks#on_value
+    # @see Callbacks#on_failure
     def on_complete(&listener)
       run_immediately = false
       if @state != :pending
@@ -475,7 +621,18 @@ module Ione
     # If the future fails this method will raise the error that failed the
     # future.
     #
+    # @note
+    #   This is a blocking operation and should be used with caution. You should
+    #   never call this method in a block given to any of the other methods
+    #   on {Future}. Prefer using combinator methods like {#map} and {#flat_map}
+    #   to compose operations asynchronously, or use {#on_value}, {#on_failure}
+    #   or {#on_complete} to listen for values and/or failures.
+    #
+    # @raise [Error] the error that failed this future
     # @return [Object] the value of this future
+    # @see Callbacks#on_value
+    # @see Callbacks#on_failure
+    # @see Callbacks#on_complete
     def value
       raise @error if @state == :failed
       return @value if @state == :resolved
@@ -556,6 +713,18 @@ module Ione
     end
   end
 
+  # @private
+  # @deprecated
+  FutureCallbacks = Future::Callbacks
+
+  # @private
+  # @deprecated
+  FutureCombinators = Future::Combinators
+
+  # @private
+  # @deprecated
+  FutureFactories = Future::Factories
+
   # @private
   class CompletableFuture < Future
     def resolve(v=nil)

data/lib/ione/io/io_reactor.rb

@@ -163,11 +163,11 @@ module Ione
       #
       # @param host [String] the host to connect to
       # @param port [Integer] the port to connect to
-      # @param options_or_timeout [Hash, Numeric] a hash of options (see below)
+      # @param options [Hash, Numeric] a hash of options (see below)
       #   or the connection timeout (equivalent to using the `:timeout` option).
-      # @option options_or_timeout [Numeric] :timeout (5) the number of seconds
+      # @option options [Numeric] :timeout (5) the number of seconds
       #   to wait for a connection before failing
-      # @option options_or_timeout [Boolean, OpenSSL::SSL::SSLContext] :ssl (false)
+      # @option options [Boolean, OpenSSL::SSL::SSLContext] :ssl (false)
       #   pass an `OpenSSL::SSL::SSLContext` to upgrade the connection to SSL,
       #   or true to upgrade the connection and create a new context.
       # @yieldparam [Ione::Io::Connection] connection the newly opened connection

data/lib/ione/version.rb

@@ -1,5 +1,5 @@
 # encoding: utf-8
 
 module Ione
-  VERSION = '1.2.0.pre9'.freeze
+  VERSION = '1.2.0'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ione
 version: !ruby/object:Gem::Version
-  version: 1.2.0.pre9
+  version: 1.2.0
 platform: ruby
 authors:
 - Theo Hultberg
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-10-28 00:00:00.000000000 Z
+date: 2014-10-31 00:00:00.000000000 Z
 dependencies: []
 description: Reactive programming framework for Ruby, painless evented IO, futures
   and an efficient byte buffer
@@ -65,9 +65,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: 1.9.3
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubyforge_project: 
 rubygems_version: 2.2.2