class Cassandra::Future

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

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

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")

Future.all trivially succeeds when there are no futures

expect(Future.all.get).to eq([])
expect(Future.all([]).get).to eq([])

Returns a new promise instance

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}

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}

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 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)

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}

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}

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