class Cassandra::Future

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.

Public Class Methods

all(*futures) click to toggle source

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
    # File lib/cassandra/future.rb
263 def self.all(*futures)
264   @@factory.all(*futures)
265 end
error(error) click to toggle source

Returns a future resolved to a given error @param error [Exception] error for the future @return [Cassandra::Future<Exception>] a future error

    # File lib/cassandra/future.rb
251 def self.error(error)
252   @@factory.error(error)
253 end
new(signal) click to toggle source

@private

    # File lib/cassandra/future.rb
273 def initialize(signal)
274   @signal = signal
275 end
promise() click to toggle source

Returns a new promise instance

    # File lib/cassandra/future.rb
268 def self.promise
269   @@factory.promise
270 end
value(value) click to toggle source

Returns a future resolved to a given value @param value [Object] value for the future @return [Cassandra::Future<Object>] a future value

    # File lib/cassandra/future.rb
244 def self.value(value)
245   @@factory.value(value)
246 end

Public Instance Methods

add_listener(listener) click to toggle source

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]

    # File lib/cassandra/future.rb
328 def add_listener(listener)
329   unless listener.respond_to?(:success) && listener.respond_to?(:failure)
330     raise ::ArgumentError, 'listener must respond to both #success and #failure'
331   end
332 
333   @signal.add_listener(listener)
334   self
335 end
fallback(&block) click to toggle source

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

    # File lib/cassandra/future.rb
383 def fallback(&block)
384   raise ::ArgumentError, 'no block given' unless block_given?
385   @signal.fallback(&block)
386 end
get(timeout = nil) click to toggle source

Returns future value or raises future error

@note This method blocks until a future is resolved or a times out

@param timeout [nil, Numeric] a maximum number of seconds to block

current thread for while waiting for this future to resolve. Will
wait indefinitely if passed `nil`.

@raise [Errors::TimeoutError] raised when wait time exceeds the timeout @raise [Exception] raises when the future has been resolved with an

error. The original exception will be raised.

@return [Object] the value that the future has been resolved with

    # File lib/cassandra/future.rb
401 def get(timeout = nil)
402   @signal.get(timeout)
403 end
Also aliased as: join
join(timeout = nil)
Alias for: get
on_complete(&block) click to toggle source

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]

    # File lib/cassandra/future.rb
313 def on_complete(&block)
314   raise ::ArgumentError, 'no block given' unless block_given?
315   @signal.on_complete(&block)
316   self
317 end
on_failure(&block) click to toggle source

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]

    # File lib/cassandra/future.rb
297 def on_failure(&block)
298   raise ::ArgumentError, 'no block given' unless block_given?
299   @signal.on_failure(&block)
300   self
301 end
on_success(&block) click to toggle source

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]

    # File lib/cassandra/future.rb
284 def on_success(&block)
285   raise ::ArgumentError, 'no block given' unless block_given?
286   @signal.on_success(&block)
287   self
288 end
then(&block) click to toggle source

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

    # File lib/cassandra/future.rb
357 def then(&block)
358   raise ::ArgumentError, 'no block given' unless block_given?
359   @signal.then(&block)
360 end