cassandra-driver 0.1.0.alpha1 → 1.0.0.beta.1

data/lib/cassandra/errors.rb

@@ -0,0 +1,79 @@
+# encoding: utf-8
+
+#--
+# Copyright 2013-2014 DataStax, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#++
+
+module Cassandra
+  # Base class for all Errors raised by the driver 
+  # @see Cassandra::Errors
+  class Error < StandardError
+  end
+
+  module Errors
+    # @!parse class IoError < StandardError; end
+    # @private
+    IoError = Ione::IoError
+
+    # This error type represents errors sent by the server, the `code` attribute
+    # can be used to find the exact type, and `cql` contains the request's CQL,
+    # if any. `message` contains the human readable error message sent by the
+    # server.
+    class QueryError < Error
+      # @return [Integer] error code
+      attr_reader :code
+      # @return [String] original CQL used
+      attr_reader :cql
+      # @return [Hash{Symbol => String, Integer}] various error details
+      attr_reader :details
+
+      # @private
+      def initialize(code, message, cql=nil, details=nil)
+        super(message)
+        @code = code
+        @cql = cql
+        @details = details
+      end
+    end
+
+    # This error is thrown when not hosts could be reached during connection or query execution.
+    class NoHostsAvailable < Error
+      # @return [Hash{Cassandra::Host => Exception}] a map of hosts to underlying exceptions
+      attr_reader :errors
+
+      # @private
+      def initialize(errors = {})
+        super("no hosts available, check #errors property for details")
+
+        @errors = errors
+      end
+    end
+
+    # Client error represents bad driver state or configuration
+    #
+    # @see Cassandra::Errors::AuthenticationError
+    class ClientError < Error
+    end
+
+    # Raised when cannot authenticate to Cassandra
+    class AuthenticationError < ClientError
+    end
+
+    # @private
+    NotConnectedError = Class.new(Error)
+    # @private
+    NotPreparedError = Class.new(Error)
+  end
+end

data/lib/cassandra/execution/info.rb

@@ -0,0 +1,51 @@
+# encoding: utf-8
+
+#--
+# Copyright 2013-2014 DataStax, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#++
+
+module Cassandra
+  module Execution
+    class Info
+      # @return [String] keyspace used for the query
+      attr_reader :keyspace
+      # @return [Cassandra::Statement] original statement
+      attr_reader :statement
+      # @return [Cassandra::Execution::Options] original execution options
+      attr_reader :options
+      # @return [Array<Cassandra::Host>] a list of attempted hosts
+      attr_reader :hosts
+      # Actual consistency used, it can differ from consistency in {Cassandra::Execution::Info#options} if a retry policy modified it.
+      # @return [Symbol] one of {Cassandra::CONSISTENCIES}
+      attr_reader :consistency
+      # @return [Integer] number of retries
+      attr_reader :retries
+      # Returns {Cassandra::Execution::Trace} if `trace: true` was passed to {Cassandra::Session#execute} or {Cassandra::Session#execute_async}
+      # @return [Cassandra::Execution::Trace, nil] a Trace if it has been enabled for request
+      attr_reader :trace
+
+      # @private
+      def initialize(keyspace, statement, options, hosts, consistency, retries, trace)
+        @keyspace    = keyspace
+        @statement   = statement
+        @options     = options
+        @hosts       = hosts
+        @consistency = consistency
+        @retries     = retries
+        @trace       = trace
+      end
+    end
+  end
+end

data/lib/cassandra/execution/options.rb

@@ -0,0 +1,77 @@
+# encoding: utf-8
+
+#--
+# Copyright 2013-2014 DataStax, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#++
+
+module Cassandra
+  module Execution
+    class Options
+      # @return [Symbol] consistency for request. Must be one of
+      #   {Cassandra::CONSISTENCIES}
+      attr_reader :consistency
+      # @return [Symbol] consistency for request with conditional updates
+      #   (lightweight - compare-and-set, CAS - transactions). Must be one of
+      #   {Cassandra::SERIAL_CONSISTENCIES}
+      attr_reader :serial_consistency
+      # @return [Integer] requested page size
+      attr_reader :page_size
+      # @return [Numeric] request timeout interval
+      attr_reader :timeout
+
+      # @private
+      def initialize(options)
+        consistency        = options[:consistency]
+        page_size          = options[:page_size]
+        trace              = options[:trace]
+        timeout            = options[:timeout]
+        serial_consistency = options[:serial_consistency]
+
+        raise ::ArgumentError, ":consistency must be one of #{CONSISTENCIES.inspect}, #{consistency.inspect} given" unless CONSISTENCIES.include?(consistency)
+        raise ::ArgumentError, ":serial_consistency must be one of #{SERIAL_CONSISTENCIES.inspect}, #{serial_consistency.inspect} given" if serial_consistency && !SERIAL_CONSISTENCIES.include?(serial_consistency)
+
+        page_size = page_size && Integer(page_size)
+        timeout   = timeout   && Integer(timeout)
+
+        @consistency        = consistency
+        @page_size          = page_size
+        @trace              = !!trace
+        @timeout            = timeout
+        @serial_consistency = serial_consistency
+      end
+
+      # @return [Boolean] whether request tracing was enabled
+      def trace?
+        @trace
+      end
+
+      # @private
+      def override(options)
+        Options.new(to_h.merge!(options))
+      end
+
+      # @private
+      def to_h
+        {
+          :consistency        => @consistency,
+          :page_size          => @page_size,
+          :trace              => @trace,
+          :timeout            => @timeout,
+          :serial_consistency => @serial_consistency
+        }
+      end
+    end
+  end
+end

data/lib/cassandra/execution/trace.rb

@@ -0,0 +1,152 @@
+# encoding: utf-8
+
+#--
+# Copyright 2013-2014 DataStax, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#++
+
+module Cassandra
+  module Execution
+    class Trace
+      class Event
+        # @return [Cassandra::Uuid] event uuid
+        attr_reader :id
+
+        # @return [String] description of activity
+        attr_reader :activity
+
+        attr_reader :source
+        attr_reader :source_elapsed
+        attr_reader :thread
+
+        # @private
+        def initialize(id, activity, source, source_elapsed, thread)
+          @id             = id
+          @activity       = activity
+          @source         = source
+          @source_elapsed = source_elapsed
+          @thread         = thread
+        end
+
+        def ==(other)
+          other == @id
+        end
+
+        alias :eql? :==
+      end
+
+      include MonitorMixin
+
+      # @return [Cassandra::Uuid] trace id
+      attr_reader :id
+
+      # @private
+      def initialize(id, client)
+        @id     = id
+        @client = client
+
+        mon_initialize
+      end
+
+      # Returns the ip of coordinator node. Typically the same as {Cassandra::Execution::Info#hosts}`.last`
+      #
+      # @return [IPAddr] ip of the coordinator node
+      def coordinator
+        load unless @coordinator
+
+        @coordinator
+      end
+
+      def duration
+        load unless @duration
+
+        @duration
+      end
+
+      def parameters
+        load unless @parameters
+
+        @parameters
+      end
+
+      def request
+        load unless @request
+
+        @request
+      end
+
+      def started_at
+        load unless @started_at
+
+        @started_at
+      end
+
+      # Returns all trace events
+      #
+      # @return [Array<Cassandra::Execution::Trace::Event>] events
+      def events
+        load_events unless @events
+
+        @events
+      end
+
+      def inspect
+        "#<#{self.class.name}:0x#{self.object_id.to_s(16)} @id=#{@id.inspect}>"
+      end
+
+      private
+
+      # @private
+      SELECT_SESSION = "SELECT * FROM system_traces.sessions WHERE session_id = ?"
+      # @private
+      SELECT_EVENTS  = "SELECT * FROM system_traces.events WHERE session_id = ?"
+
+      # @private
+      def load
+        synchronize do
+          return if @loaded
+
+          data = @client.query(Statements::Simple.new(SELECT_SESSION, @id), VOID_OPTIONS).get.first
+          raise ::RuntimeError, "unable to load trace #{@id}" if data.nil?
+
+          @coordinator = data['coordinator']
+          @duration    = data['duration']
+          @parameters  = data['parameters']
+          @request     = data['request']
+          @started_at  = data['started_at']
+          @loaded      = true
+        end
+
+        nil
+      end
+
+      # @private
+      def load_events
+        synchronize do
+          return if @loaded_events
+
+          @events = []
+
+          @client.query(Statements::Simple.new(SELECT_EVENTS, @id), VOID_OPTIONS).get.each do |row|
+            @events << Event.new(row['event_id'], row['activity'], row['source'], row['source_elapsed'], row['thread'])
+          end
+
+          @events.freeze
+
+          @loaded_events = true
+        end
+      end
+    end
+  end
+end

data/lib/cassandra/future.rb

@@ -0,0 +1,675 @@
+# encoding: utf-8
+
+#--
+# Copyright 2013-2014 DataStax, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#++
+
+module Cassandra
+  # A Future represents a result of asynchronous execution. It can be used to
+  # block until a value is available or an error has happened, or register a
+  # listener to be notified whenever the execution is complete.
+  class Future
+    # a Future listener to be passed to {Cassandra::Future#add_listener}
+    #
+    # @note Listener methods can be called from application if a future has
+    #   been resolved or failed by the time the listener is registered; or from
+    #   background thread if it is resolved/failed after the listener has been
+    #   registered.
+    #
+    # @abstract Actual listeners passed to {Cassandra::Future#add_listener} don't
+    #   need to extend this class as long as they implement `#success` and
+    #   `#failure` methods
+    class Listener
+      # @param value [Object] actual value the future has been resolved with
+      # @return [void]
+      def success(value)
+      end
+
+      # @param error [Exception] an exception used to fail the future
+      # @return [void]
+      def failure(error)
+      end
+    end
+
+    # @private
+    class Error < Future
+      def initialize(error)
+        raise ::ArgumentError, "error must be an exception, #{error.inspect} given" unless error.is_a?(::Exception)
+
+        @error = error
+      end
+
+      def get
+        raise(@error, @error.message, @error.backtrace)
+      end
+
+      def on_success
+        raise ::ArgumentError, "no block given" unless block_given?
+        self
+      end
+
+      def on_failure
+        raise ::ArgumentError, "no block given" unless block_given?
+        yield(@error) rescue nil
+        self
+      end
+
+      def on_complete
+        raise ::ArgumentError, "no block given" unless block_given?
+        yield(nil, @error) rescue nil
+        self
+      end
+
+      def add_listener(listener)
+        unless (listener.respond_to?(:success) && listener.respond_to?(:failure))
+          raise ::ArgumentError, "listener must respond to both #success and #failure"
+        end
+
+        listener.failure(@error) rescue nil
+        self
+      end
+
+      def join
+        self
+      end
+
+      def then
+        raise ::ArgumentError, "no block given" unless block_given?
+        self
+      end
+
+      def fallback
+        raise ::ArgumentError, "no block given" unless block_given?
+
+        begin
+          result = yield(@error)
+          result = Value.new(result) unless result.is_a?(Future)
+          result
+        rescue => e
+          Error.new(e)
+        end
+      end
+    end
+
+    # @private
+    class Value < Future
+      def initialize(value)
+        @value = value
+      end
+
+      def get
+        @value
+      end
+
+      def on_success
+        raise ::ArgumentError, "no block given" unless block_given?
+        yield(@value) rescue nil
+        self
+      end
+
+      def on_failure
+        raise ::ArgumentError, "no block given" unless block_given?
+        self
+      end
+
+      def on_complete
+        raise ::ArgumentError, "no block given" unless block_given?
+        yield(@value, nil) rescue nil
+        self
+      end
+
+      def add_listener(listener)
+        unless (listener.respond_to?(:success) && listener.respond_to?(:failure))
+          raise ::ArgumentError, "listener must respond to both #success and #failure"
+        end
+
+        listener.success(@value) rescue nil
+        self
+      end
+
+      def join
+        self
+      end
+
+      def then
+        raise ::ArgumentError, "no block given" unless block_given?
+
+        begin
+          result = yield(@value)
+          result = Value.new(result) unless result.is_a?(Future)
+          result
+        rescue => e
+          Error.new(e)
+        end
+      end
+
+      def fallback
+        raise ::ArgumentError, "no block given" unless block_given?
+        self
+      end
+    end
+
+    # Returns a future resolved to a given value
+    # @param value [Object] value for the future
+    # @return [Cassandra::Future<Object>] a future value
+    def self.value(value)
+      Value.new(value)
+    end
+
+    # Returns a future resolved to a given error
+    # @param error [Exception] error for the future
+    # @return [Cassandra::Future<Exception>] a future error
+    def self.error(error)
+      Error.new(error)
+    end
+
+    # Returns a future that resolves with values of all futures
+    # @overload all(*futures)
+    #   @param *futures [Cassandra::Future] futures to combine
+    #   @return [Cassandra::Future<Array<Object>>] a combined future
+    # @overload all(futures)
+    #   @param futures [Enumerable<Cassandra::Future>] list of futures to
+    #     combine
+    #   @return [Cassandra::Future<Array<Object>>] a combined future
+    def self.all(*futures)
+      futures   = Array(futures.first) if futures.one?
+      monitor   = Monitor.new
+      promise   = Promise.new
+      remaining = futures.length
+      values    = Array.new(length)
+
+      futures.each_with_index do |future, i|
+        future.on_complete do |v, e|
+          if e
+            promise.break(e)
+          else
+            done = false
+            monitor.synchronize do
+              remaining -= 1
+              done = (remaining == 0)
+              values[i] = v
+            end
+            promise.fulfill(values) if done
+          end
+        end
+      end
+
+      promise.future
+    end
+
+    # @private
+    # Returns a new promise instance
+    def self.promise
+      Promise.new
+    end
+
+    # @private
+    def initialize(signal)
+      @signal = signal
+    end
+
+    # Returns future value or raises future error
+    # @note This method blocks until a future is resolved
+    # @raise [Exception] error used to resolve this future if any
+    # @return [Object] value used to resolve this future if any
+    def get
+      @signal.get
+    end
+
+    # Block until the future has been resolved
+    # @note This method blocks until a future is resolved
+    # @note This method won't raise any errors or return anything but the
+    #   future itself
+    # @return [self]
+    def join
+      @signal.join
+      self
+    end
+
+    # Run block when future resolves to a value
+    # @note The block can be called synchronously from current thread if the
+    #   future has already been resolved, or, asynchronously, from background
+    #   thread upon resolution.
+    # @yieldparam value [Object] a value
+    # @raise [ArgumentError] if no block given
+    # @return [self]
+    def on_success(&block)
+      raise ::ArgumentError, "no block given" unless block_given?
+      @signal.on_success(&block)
+      self
+    end
+
+    # Run block when future resolves to error
+    # @note The block can be called synchronously from current thread if the
+    #   future has already been resolved, or, asynchronously, from background
+    #   thread upon resolution.
+    # @yieldparam error [Exception] an error
+    # @raise [ArgumentError] if no block given
+    # @return [self]
+    def on_failure(&block)
+      raise ::ArgumentError, "no block given" unless block_given?
+      @signal.on_failure(&block)
+      self
+    end
+
+    # Run block when future resolves. The block will always be called with 2
+    #   arguments - value and error. In case a future resolves to an error, the
+    #   error argument will be non-nil.
+    # @note The block can be called synchronously from current thread if the
+    #   future has already been resolved, or, asynchronously, from background
+    #   thread upon resolution.
+    # @yieldparam value [Object, nil] a value or nil
+    # @yieldparam error [Exception, nil] an error or nil
+    # @raise [ArgumentError] if no block given
+    # @return [self]
+    def on_complete(&block)
+      raise ::ArgumentError, "no block given" unless block_given?
+      @signal.on_complete(&block)
+      self
+    end
+
+    # Add future listener
+    # @note The listener can be notified synchronously, from current thread, if
+    #   the future has already been resolved, or, asynchronously, from
+    #   background thread upon resolution.
+    # @note that provided listener doesn't have to extend
+    #   {Cassandra::Future::Listener}, only conform to the same interface
+    # @param listener [Cassandra::Future::Listener] an object that responds to
+    #   `#success` and `#failure`
+    # @return [self]
+    def add_listener(listener)
+      unless (listener.respond_to?(:success) && listener.respond_to?(:failure))
+        raise ::ArgumentError, "listener must respond to both #success and #failure"
+      end
+
+      @signal.add_listener(listener)
+      self
+    end
+
+    # Returns a new future that will resolve to the result of the block.
+    # Besides regular values, block can return other futures, which will be
+    # transparently unwrapped before resolving the future from this method.
+    #
+    # @example Block returns a value
+    #   future_users = session.execute_async('SELECT * FROM users WHERE user_name = ?', 'Sam')
+    #   future_user  = future_users.then {|users| users.first}
+    #
+    # @example Block returns a future
+    #   future_statement = session.prepare_async('SELECT * FROM users WHERE user_name = ?')
+    #   future_users     = future_statement.then {|statement| session.execute_async(statement, 'Sam')}
+    #
+    # @note The block can be called synchronously from current thread if the
+    #   future has already been resolved, or, asynchronously, from background
+    #   thread upon resolution.
+    # @yieldparam value [Object] a value
+    # @yieldreturn [Cassandra::Future, Object] a future or a value to be
+    #   wrapped in a future
+    # @raise [ArgumentError] if no block given
+    # @return [Cassandra::Future] a new future
+    def then(&block)
+      raise ::ArgumentError, "no block given" unless block_given?
+      @signal.then(&block)
+    end
+
+    # Returns a new future that will resolve to the result of the block in case
+    # of an error. Besides regular values, block can return other futures,
+    # which will be transparently unwrapped before resolving the future from
+    # this method.
+    #
+    # @example Recovering from errors
+    #   future_error = session.execute_async('SELECT * FROM invalid-table')
+    #   future       = future_error.fallback {|error| "Execution failed with #{error.class.name}: #{error.message}"}
+    #
+    # @example Executing something else on error
+    #   future_error = session.execute_async('SELECT * FROM invalid-table')
+    #   future       = future_error.fallback {|e| session.execute_async('SELECT * FROM another-table')}
+    #
+    # @note The block can be called synchronously from current thread if the
+    #   future has already been resolved, or, asynchronously, from background
+    #   thread upon resolution.
+    # @yieldparam error [Exception] an error
+    # @yieldreturn [Cassandra::Future, Object] a future or a value to be
+    #   wrapped in a future
+    # @raise [ArgumentError] if no block given
+    # @return [Cassandra::Future] a new future
+    def fallback(&block)
+      raise ::ArgumentError, "no block given" unless block_given?
+      @signal.fallback(&block)
+    end
+  end
+
+  # @private
+  class Promise
+    # @private
+    class Signal
+      # @private
+      module Listeners
+        class Success < Future::Listener
+          def initialize(&block)
+            @block = block
+          end
+
+          def success(value)
+            @block.call(value)
+          end
+
+          def failure(error)
+            nil
+          end
+        end
+
+        class Failure < Future::Listener
+          def initialize(&block)
+            @block = block
+          end
+
+          def success(value)
+            nil
+          end
+
+          def failure(error)
+            @block.call(error)
+          end
+        end
+
+        class Complete < Future::Listener
+          def initialize(&block)
+            @block = block
+          end
+
+          def success(value)
+            @block.call(nil, value)
+          end
+
+          def failure(error)
+            @block.call(error, nil)
+          end
+        end
+
+        class Then < Future::Listener
+          def initialize(promise, &block)
+            @promise = promise
+            @block   = block
+          end
+
+          def success(value)
+            result = @block.call(value)
+
+            if result.is_a?(Future)
+              @promise.observe(result)
+            else
+              @promise.fulfill(result)
+            end
+          rescue => e
+            @promise.break(e)
+          ensure
+            @promise = @block = nil
+          end
+
+          def failure(error)
+            @promise.break(error)
+          ensure
+            @promise = @block = nil
+          end
+        end
+
+        class Fallback < Future::Listener
+          def initialize(promise, &block)
+            @promise = promise
+            @block   = block
+          end
+
+          def success(value)
+            @promise.fulfill(value)
+          ensure
+            @promise = @block = nil
+          end
+
+          def failure(error)
+            result = @block.call(error)
+
+            if result.is_a?(Future)
+              @promise.observe(result)
+            else
+              @promise.fulfill(result)
+            end
+          rescue => e
+            @promise.break(e)
+          ensure
+            @promise = @block = nil
+          end
+        end
+      end
+
+      include MonitorMixin
+
+      def initialize
+        mon_initialize
+
+        @cond      = new_cond
+        @state     = :pending
+        @waiting   = 0
+        @error     = nil
+        @value     = nil
+        @listeners = []
+      end
+
+      def failure(error)
+        unless error.is_a?(::Exception)
+          raise ::ArgumentError, "error must be an exception, #{error.inspect} given"
+        end
+
+        return unless @state == :pending
+
+        listeners = nil
+
+        synchronize do
+          return unless @state == :pending
+
+          @error = error
+          @state = :broken
+
+          listeners, @listeners = @listeners, nil
+        end
+
+        listeners.each do |listener|
+          listener.failure(error) rescue nil
+        end
+
+        synchronize do
+          @cond.broadcast if @waiting > 0
+        end
+
+        self
+      end
+
+      def success(value)
+        return unless @state == :pending
+
+        listeners = nil
+
+        synchronize do
+          return unless @state == :pending
+
+          @value = value
+          @state = :fulfilled
+
+          listeners, @listeners = @listeners, nil
+        end
+
+        listeners.each do |listener|
+          listener.success(value) rescue nil
+        end
+
+        synchronize do
+          @cond.broadcast if @waiting > 0
+        end
+
+        self
+      end
+
+      def join
+        return unless @state == :pending
+
+        synchronize do
+          return unless @state == :pending
+
+          @waiting += 1
+          @cond.wait while @state == :pending
+          @waiting -= 1
+        end
+
+        nil
+      end
+
+      def get
+        join if @state == :pending
+
+        raise(@error, @error.message, @error.backtrace) if @state == :broken
+
+        @value
+      end
+
+      def add_listener(listener)
+        if @state == :pending
+          synchronize do
+            if @state == :pending
+              @listeners << listener
+
+              return self
+            end
+          end
+        end
+
+        listener.success(@value) rescue nil if @state == :fulfilled
+        listener.failure(@error) rescue nil if @state == :broken
+
+        self
+      end
+
+      def on_success(&block)
+        if @state == :pending
+          synchronize do
+            if @state == :pending
+              @listeners << Listeners::Success.new(&block)
+              return self
+            end
+          end
+        end
+
+        yield(@value) rescue nil if @state == :fulfilled
+
+        self
+      end
+
+      def on_failure(&block)
+        if @state == :pending
+          synchronize do
+            if @state == :pending
+              @listeners << Listeners::Failure.new(&block)
+              return self
+            end
+          end
+        end
+
+        yield(@error) rescue nil if @state == :broken
+
+        self
+      end
+
+      def on_complete(&block)
+        if @state == :pending
+          synchronize do
+            if @state == :pending
+              @listeners << Listeners::Complete.new(&block)
+              return self
+            end
+          end
+        end
+
+        yield(@value, @error) rescue nil
+
+        self
+      end
+
+      def then(&block)
+        if @state == :pending
+          synchronize do
+            if @state == :pending
+              promise  = Promise.new
+              listener = Listeners::Then.new(promise, &block)
+              @listeners << listener
+              return promise.future
+            end
+          end
+        end
+
+        return Future::Error.new(@error) if @state == :broken
+
+        begin
+          result = yield(@value)
+          result = Future::Value.new(result) unless result.is_a?(Future)
+          result
+        rescue => e
+          Future::Error.new(e)
+        end
+      end
+
+      def fallback(&block)
+        if @state == :pending
+          synchronize do
+            if @state == :pending
+              promise  = Promise.new
+              listener = Listeners::Fallback.new(promise, &block)
+              @listeners << listener
+              return promise.future
+            end
+          end
+        end
+
+        return Future::Value.new(@value) if @state == :fulfilled
+
+        begin
+          result = yield(@error)
+          result = Future::Value.new(result) unless result.is_a?(Future)
+          result
+        rescue => e
+          Future::Error.new(e)
+        end
+      end
+    end
+
+    attr_reader :future
+
+    def initialize
+      @signal = Signal.new
+      @future = Future.new(@signal)
+    end
+
+    def break(error)
+      @signal.failure(error)
+      self
+    end
+
+    def fulfill(value)
+      @signal.success(value)
+      self
+    end
+
+    def observe(future)
+      future.add_listener(@signal)
+    end
+  end
+end