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.

Inherits

Object

Classes

Methods

self.

value

(value)

Returns a future resolved to a given value

Parameters:
Name Type Details
value Object value for the future
Returns:
Type Details
Future<Object> a future value
self.

error

(error)

Returns a future resolved to a given error

Parameters:
Name Type Details
error Exception error for the future
Returns:
Type Details
Future<Exception> a future error
self.

all

(*futures)

Returns a future that resolves with values of all futures

Overloads:
self.all(*futures)

Returns a combined future

Parameters:
Name Type Details
*futures Future futures to combine
Returns:
Type Details
Future<Array<Object>> a combined future
self.all(futures)

Returns a combined future

Parameters:
Name Type Details
futures Enumerable<Future> list of futures to combine
Returns:
Type Details
Future<Array<Object>> a combined future
Specifications:
Future.all succeeds when all futures succeed 
futures = 10.times.map {|i| Future.value(i)}
expect(Future.all(futures).get).to eq([0,1,2,3,4,5,6,7,8,9])
Future.all fails when any futures fail 
futures = 9.times.map {|i| Future.value(i)}
futures << Future.error(RuntimeError.new("something happened"))
expect { Future.all(futures).get }.to raise_error("something happened")
self.

promise

Returns a new promise instance

on_success

{|value| … }

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.
Yield Parameters:
Name Type Details
value Object a value
Returns:
Type Details
self
Raises:
Type Details
ArgumentError if no block given
Specifications:
Future#on_success raises if no block given 
expect { future.on_success }.to raise_error(::ArgumentError, "no block given")
Future#on_success delegates to signal 
expect(signal).to receive(:on_success).once
future.on_success {|value| nil}

on_failure

{|error| … }

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.
Yield Parameters:
Name Type Details
error Exception an error
Returns:
Type Details
self
Raises:
Type Details
ArgumentError if no block given
Specifications:
Future#on_failure raises if no block given 
expect { future.on_failure }.to raise_error(::ArgumentError, "no block given")
Future#on_failure delegates to signal 
expect(signal).to receive(:on_failure).once
future.on_failure {|error| nil}

on_complete

{|value, error| … }

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.
Yield Parameters:
Name Type Details
value (Object or nil) a value or nil
error (Exception or nil) an error or nil
Returns:
Type Details
self
Raises:
Type Details
ArgumentError if no block given
Specifications:
Future#on_complete raises if no block given 
expect { future.on_complete }.to raise_error(::ArgumentError, "no block given")
Future#on_complete delegates to signal 
expect(signal).to receive(:on_complete).once
future.on_complete {|error, value| nil}

add_listener

(listener)

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 Listener, only conform to the same interface
Parameters:
Name Type Details
listener Future::Listener an object that responds to #success and #failure
Returns:
Type Details
self
Specifications:
Future#add_listener raises if listener doesn't respond to #success and #failure 
expect(listener).to receive(:respond_to?).and_return(false)
expect { future.add_listener(listener) }.to raise_error(::ArgumentError, "listener must respond to both #success and #failure")
Future#add_listener delegates to signal 
expect(listener).to receive(:respond_to?).with(:success).and_return(true)
expect(listener).to receive(:respond_to?).with(:failure).and_return(true)
expect(signal).to receive(:add_listener).once.with(listener)
expect(future.add_listener(listener)).to eq(future)

then

{|value| … }

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.

Note
The block can be called synchronously from current thread if the future has already been resolved, or, asynchronously, from background thread upon resolution.
Examples:
Block returns a value 
future_users = session.execute_async('SELECT * FROM users WHERE user_name = ?', 'Sam')
future_user  = future_users.then {|users| users.first}
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')}
Yield Parameters:
Name Type Details
value Object a value
Yield Returns:
Type Details
(Future or Object) a future or a value to be wrapped in a future
Returns:
Type Details
Future a new future
Raises:
Type Details
ArgumentError if no block given
Specifications:
Future#then raises if no block given 
expect { future.then }.to raise_error(ArgumentError, "no block given")
Future#then delegates to signal 
expect(signal).to receive(:then).once
future.then {|v| nil}

fallback

{|error| … }

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.

Note
The block can be called synchronously from current thread if the future has already been resolved, or, asynchronously, from background thread upon resolution.
Examples:
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}"}
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')}
Yield Parameters:
Name Type Details
error Exception an error
Yield Returns:
Type Details
(Future or Object) a future or a value to be wrapped in a future
Returns:
Type Details
Future a new future
Raises:
Type Details
ArgumentError if no block given
Specifications:
Future#fallback raises of no block given 
expect { future.fallback }.to raise_error(ArgumentError, "no block given")
Future#fallback delegates to signal 
expect(signal).to receive(:fallback).once
future.fallback {|e| nil}

get

(timeout = nil) aliased as: join

Returns future value or raises future error

Note
This method blocks until a future is resolved or a times out
Parameters:
Name Type Details
timeout (nil or Numeric) (defaults to: nil) a maximum number of seconds to block current thread for while waiting for this future to resolve. Will wait indefinitely if passed nil.
Returns:
Type Details
Object the value that the future has been resolved with
Raises:
Type Details
Errors::TimeoutError raised when wait time exceeds the timeout
Exception raises when the future has been resolved with an error. The original exception will be raised.
Specifications:
Future#get delegates to signal 
expect(signal).to receive(:get).once
future.get