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

Overloads:



233
234
235
 
# File 'lib/cassandra/future.rb', line 233

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

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

Returns a future resolved to a given error

Parameters:

  • error (Exception) —

    error for the future

Returns:



221
222
223
 
# File 'lib/cassandra/future.rb', line 221

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

.promise ⇒ Object

Returns a new promise instance



238
239
240
 
# File 'lib/cassandra/future.rb', line 238

def self.promise
  @@factory.promise
end

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

Returns a future resolved to a given value

Parameters:

  • value (Object) —

    value for the future

Returns:



214
215
216
 
# File 'lib/cassandra/future.rb', line 214

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

Parameters:

Returns:

  • (self) 


298
299
300
301
302
303
304
305
 
# File 'lib/cassandra/future.rb', line 298

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:

Returns:

Raises:

  • (ArgumentError) —

    if no block given



353
354
355
356
 
# File 'lib/cassandra/future.rb', line 353

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

#get ⇒ Object

Note:

This method blocks until a future is resolved

Returns future value or raises future error

Returns:

  • (Object) —

    value used to resolve this future if any

Raises:

  • (Exception) —

    error used to resolve this future if any



362
363
364
365
 
# File 'lib/cassandra/future.rb', line 362

def get
  @signal.get
  
end

#join ⇒ self

Note:

This method blocks until a future is resolved

Note:

This method won't raise any errors or return anything but the future itself

Block until the future has been resolved

Returns:

  • (self) 


372
373
374
375
 
# File 'lib/cassandra/future.rb', line 372

def join
  @signal.join
  self
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

Returns:

  • (self)

Raises:

  • (ArgumentError) —

    if no block given



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

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

Returns:

  • (self)

Raises:

  • (ArgumentError) —

    if no block given



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

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

Returns:

  • (self)

Raises:

  • (ArgumentError) —

    if no block given



254
255
256
257
258
 
# File 'lib/cassandra/future.rb', line 254

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:

Returns:

Raises:

  • (ArgumentError) —

    if no block given



327
328
329
330
 
# File 'lib/cassandra/future.rb', line 327

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