Class: Concurrent::Future

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

Overview

See Also:

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from IVar

#add_observer, #fail, #set

Methods included from Observable

#add_observer, #count_observers, #delete_observer, #delete_observers, #with_observer

Methods included from Obligation

#completed?, #exception, #fulfilled?, #incomplete?, #no_error!, #pending?, #reason, #rejected?, #state, #unscheduled?, #value, #value!, #wait

Methods included from Dereferenceable

#value

Constructor Details

#initialize(opts = {}) { ... } ⇒ Future

Create a new ‘Future` in the `:unscheduled` state.

Parameters:

  • opts (Hash) (defaults to: {}) —

    the options controlling how the future will be processed

Options Hash (opts):

  • :operation (Boolean) — default: false —

    when ‘true` will execute the future on the global operation pool (for long-running operations), when `false` will execute the future on the global task pool (for short-running tasks)

  • :executor (object) —

    when provided will run all operations on this executor rather than the global thread pool (overrides :operation)

  • :args (object, Array) —

    zero or more arguments to be passed the task block on execution

  • :dup_on_deref (String) — default: false —

    call ‘#dup` before returning the data

  • :freeze_on_deref (String) — default: false —

    call ‘#freeze` before returning the data

  • :copy_on_deref (String) — default: nil —

    call the given ‘Proc` passing the internal value and returning the value returned from the proc

Yields:

  • the asynchronous operation to perform

Raises:

  • (ArgumentError) —

    if no block is given



34
35
36
37
38
39
40
41
 
# File 'lib/concurrent/future.rb', line 34

def initialize(opts = {}, &block)
  raise ArgumentError.new('no block given') unless block_given?
  super(IVar::NO_VALUE, opts)
  @state = :unscheduled
  @task = block
  @executor = OptionsParser::get_executor_from(opts) || Concurrent.configuration.global_operation_pool
  @args = OptionsParser::get_arguments_from(opts)
end

Class Method Details

.execute(opts = {}) { ... } ⇒ Future

Create a new ‘Future` object with the given block, execute it, and return the `:pending` object.

Examples:

future = Concurrent::Future.execute{ sleep(1); 42 }
future.state #=> :pending

Parameters:

  • opts (Hash) (defaults to: {}) —

    the options controlling how the future will be processed

Options Hash (opts):

  • :operation (Boolean) — default: false —

    when ‘true` will execute the future on the global operation pool (for long-running operations), when `false` will execute the future on the global task pool (for short-running tasks)

  • :executor (object) —

    when provided will run all operations on this executor rather than the global thread pool (overrides :operation)

  • :args (object, Array) —

    zero or more arguments to be passed the task block on execution

  • :dup_on_deref (String) — default: false —

    call ‘#dup` before returning the data

  • :freeze_on_deref (String) — default: false —

    call ‘#freeze` before returning the data

  • :copy_on_deref (String) — default: nil —

    call the given ‘Proc` passing the internal value and returning the value returned from the proc

Yields:

  • the asynchronous operation to perform

Returns:

  • (Future) —

    the newly created ‘Future` in the `:pending` state

Raises:

  • (ArgumentError) —

    if no block is given



90
91
92
 
# File 'lib/concurrent/future.rb', line 90

def self.execute(opts = {}, &block)
  Future.new(opts, &block).execute
end

Instance Method Details

#execute ⇒ Future

Execute an ‘:unscheduled` `Future`. Immediately sets the state to `:pending` and passes the block to a new thread/thread pool for eventual execution. Does nothing if the `Future` is in any state other than `:unscheduled`.

Examples:

Instance and execute in separate steps

future = Concurrent::Future.new{ sleep(1); 42 }
future.state #=> :unscheduled
future.execute
future.state #=> :pending

Instance and execute in one line

future = Concurrent::Future.new{ sleep(1); 42 }.execute
future.state #=> :pending

Returns:

  • (Future) —

    a reference to ‘self`



58
59
60
61
62
63
 
# File 'lib/concurrent/future.rb', line 58

def execute
  if compare_and_set_state(:pending, :unscheduled)
    @executor.post(@args){ work }
    self
  end
end