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
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
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
@private
# File lib/cassandra/future.rb 273 def initialize(signal) 274 @signal = signal 275 end
Returns a new promise instance
# File lib/cassandra/future.rb 268 def self.promise 269 @@factory.promise 270 end
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 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
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
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
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
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
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
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