Class: Cassandra::Future

Inherits:
Object
  • Object
show all
Defined in:
lib/cassandra/future.rb

Overview

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.

Defined Under Namespace

Classes: Listener

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.all(*futures) ⇒ Cassandra::Future<Array<Object>> .all(futures) ⇒ Cassandra::Future<Array<Object>>

Returns a future that resolves with values of all futures



263
264
265
 
# File 'lib/cassandra/future.rb', line 263

def self.all(*futures)
  @@factory.all(*futures)
end

.error(error) ⇒ Cassandra::Future<Exception>

Returns a future resolved to a given error



251
252
253
 
# File 'lib/cassandra/future.rb', line 251

def self.error(error)
  @@factory.error(error)
end

.promise ⇒ Object

Returns a new promise instance



268
269
270
 
# File 'lib/cassandra/future.rb', line 268

def self.promise
  @@factory.promise
end

.value(value) ⇒ Cassandra::Future<Object>

Returns a future resolved to a given value



244
245
246
 
# File 'lib/cassandra/future.rb', line 244

def self.value(value)
  @@factory.value(value)
end

Instance Method Details

#add_listener(listener) ⇒ self

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

Add future listener



328
329
330
331
332
333
334
335
 
# File 'lib/cassandra/future.rb', line 328

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

#fallback {|error| ... } ⇒ Cassandra::Future

Note:

The block can be called synchronously from current thread if the future has already been resolved, or, asynchronously, from background thread upon resolution.

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.

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:

  • error (Exception) —

    an error

Yield Returns:

Raises:

  • (ArgumentError) —

    if no block given



383
384
385
386
 
# File 'lib/cassandra/future.rb', line 383

def fallback(&block)
  raise ::ArgumentError, 'no block given' unless block_given?
  @signal.fallback(&block)
end

#get(timeout = nil) ⇒ Object Also known as: join

Note:

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

Returns future value or raises future error

Raises:

  • (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.



401
402
403
 
# File 'lib/cassandra/future.rb', line 401

def get(timeout = nil)
  @signal.get(timeout)
end

#on_complete {|value, error| ... } ⇒ self

Note:

The block can be called synchronously from current thread if the future has already been resolved, or, asynchronously, from background thread upon resolution.

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.

Yield Parameters:

  • value (Object, nil) —

    a value or nil

  • error (Exception, nil) —

    an error or nil

Raises:

  • (ArgumentError) —

    if no block given



313
314
315
316
317
 
# File 'lib/cassandra/future.rb', line 313

def on_complete(&block)
  raise ::ArgumentError, 'no block given' unless block_given?
  @signal.on_complete(&block)
  self
end

#on_failure {|error| ... } ⇒ self

Note:

The block can be called synchronously from current thread if the future has already been resolved, or, asynchronously, from background thread upon resolution.

Run block when future resolves to error

Yield Parameters:

  • error (Exception) —

    an error

Raises:

  • (ArgumentError) —

    if no block given



297
298
299
300
301
 
# File 'lib/cassandra/future.rb', line 297

def on_failure(&block)
  raise ::ArgumentError, 'no block given' unless block_given?
  @signal.on_failure(&block)
  self
end

#on_success {|value| ... } ⇒ self

Note:

The block can be called synchronously from current thread if the future has already been resolved, or, asynchronously, from background thread upon resolution.

Run block when future resolves to a value

Yield Parameters:

  • value (Object) —

    a value

Raises:

  • (ArgumentError) —

    if no block given



284
285
286
287
288
 
# File 'lib/cassandra/future.rb', line 284

def on_success(&block)
  raise ::ArgumentError, 'no block given' unless block_given?
  @signal.on_success(&block)
  self
end

#then {|value| ... } ⇒ Cassandra::Future

Note:

The block can be called synchronously from current thread if the future has already been resolved, or, asynchronously, from background thread upon resolution.

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.

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:

  • value (Object) —

    a value

Yield Returns:

Raises:

  • (ArgumentError) —

    if no block given



357
358
359
360
 
# File 'lib/cassandra/future.rb', line 357

def then(&block)
  raise ::ArgumentError, 'no block given' unless block_given?
  @signal.then(&block)
end