class Concurrent::Future

{include:file:docs-source/future.md}

@!macro copy_options

@see ruby-doc.org/stdlib-2.1.1/libdoc/observer/rdoc/Observable.html Ruby Observable module @see clojuredocs.org/clojure_core/clojure.core/future Clojure's future function @see docs.oracle.com/javase/7/docs/api/java/util/concurrent/Future.html java.util.concurrent.Future

Public Class Methods

execute(opts = {}, &block) click to toggle source

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

@yield the asynchronous operation to perform

@!macro executor_and_deref_options

@option opts [object, Array] :args zero or more arguments to be passed the task

block on execution

@raise [ArgumentError] if no block is given

@return [Future] the newly created `Future` in the `:pending` state

@example

future = Concurrent::Future.execute{ sleep(1); 42 }
future.state #=> :pending
# File lib/concurrent-ruby/concurrent/future.rb, line 77
def self.execute(opts = {}, &block)
  Future.new(opts, &block).execute
end
new(opts = {}, &block) click to toggle source

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

@yield the asynchronous operation to perform

@!macro executor_and_deref_options

@option opts [object, Array] :args zero or more arguments to be passed the task

block on execution

@raise [ArgumentError] if no block is given

Calls superclass method
# File lib/concurrent-ruby/concurrent/future.rb, line 33
def initialize(opts = {}, &block)
  raise ArgumentError.new('no block given') unless block_given?
  super(NULL, opts.merge(__task_from_block__: block), &nil)
end

Public Instance Methods

cancel() click to toggle source

Attempt to cancel the operation if it has not already processed. The operation can only be cancelled while still `pending`. It cannot be cancelled once it has begun processing or has completed.

@return [Boolean] was the operation successfully cancelled.

# File lib/concurrent-ruby/concurrent/future.rb, line 99
def cancel
  if compare_and_set_state(:cancelled, :pending)
    complete(false, nil, CancelledOperationError.new)
    true
  else
    false
  end
end
cancelled?() click to toggle source

Has the operation been successfully cancelled?

@return [Boolean]

# File lib/concurrent-ruby/concurrent/future.rb, line 111
def cancelled?
  state == :cancelled
end
execute() click to toggle source

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`.

@return [Future] a reference to `self`

@example Instance and execute in separate steps

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

@example Instance and execute in one line

future = Concurrent::Future.new{ sleep(1); 42 }.execute
future.state #=> :pending
# File lib/concurrent-ruby/concurrent/future.rb, line 53
def execute
  if compare_and_set_state(:pending, :unscheduled)
    @executor.post{ safe_execute(@task, @args) }
    self
  end
end
set(value = NULL, &block) click to toggle source

@!macro ivar_set_method

# File lib/concurrent-ruby/concurrent/future.rb, line 82
def set(value = NULL, &block)
  check_for_block_or_value!(block_given?, value)
  synchronize do
    if @state != :unscheduled
      raise MultipleAssignmentError
    else
      @task = block || Proc.new { value }
    end
  end
  execute
end
wait_or_cancel(timeout) click to toggle source

Wait the given number of seconds for the operation to complete. On timeout attempt to cancel the operation.

@param [Numeric] timeout the maximum time in seconds to wait. @return [Boolean] true if the operation completed before the timeout

else false
# File lib/concurrent-ruby/concurrent/future.rb, line 121
def wait_or_cancel(timeout)
  wait(timeout)
  if complete?
    true
  else
    cancel
    false
  end
end

Protected Instance Methods

ns_initialize(value, opts) click to toggle source
Calls superclass method
# File lib/concurrent-ruby/concurrent/future.rb, line 133
def ns_initialize(value, opts)
  super
  @state = :unscheduled
  @task = opts[:__task_from_block__]
  @executor = Options.executor_from_options(opts) || Concurrent.global_io_executor
  @args = get_arguments_from(opts)
end