Class: Concurrent::Promises::AbstractEventFuture — Concurrent Ruby

# Class: Concurrent::Promises::AbstractEventFuture

Inherits:
  Synchronization::Object
  - Object
  - Synchronization::Object
  - Concurrent::Promises::AbstractEventFuture
  show all

Defined in:
  lib/concurrent/promises.rb

## Overview

Common ancestor of Event and Future classes, many shared methods are defined here.

## Direct Known Subclasses

Event, Future

## Instance Method Summary collapse

- #chain(*args, &task) ⇒ Future

  Shortcut of #chain_on with default `:io` executor supplied.

- #chain_on(executor, *args, &task) ⇒ Future

  Chains the task to be executed asynchronously on executor after it is resolved.

- #chain_resolvable(resolvable) ⇒ self (also: #tangle)

  Resolves the resolvable when receiver is resolved.

- #default_executor ⇒ Executor

  Returns default executor.

- #internal_state ⇒ Object

  The internal_state.

- #on_resolution(*args, &callback) ⇒ self

  Shortcut of #on_resolution_using with default `:io` executor supplied.

- #on_resolution!(*args, &callback) ⇒ self

  Stores the callback to be executed synchronously on resolving thread after it is resolved.

- #on_resolution_using(executor, *args, &callback) ⇒ self

  Stores the callback to be executed asynchronously on executor after it is resolved.

- #pending? ⇒ Boolean

  Is it in pending state?.

- #resolved? ⇒ Boolean

  Is it in resolved state?.

- #state ⇒ Symbol

  Returns its state.

- #to_s ⇒ String (also: #inspect)

  Short string representation.

- #touch ⇒ self

  Propagates touch.

- #wait(timeout = nil) ⇒ self, true, false

  Wait (block the Thread) until receiver is #resolved?.

- #with_default_executor(executor) ⇒ AbstractEventFuture abstract

  Crates new object with same class with the executor set as its new default executor.

## Instance Method Details

### #chain(*args, &task) ⇒ `Future`

Shortcut of #chain_on with default `:io` executor supplied.

Returns:

- (`Future`)

See Also:

- #chain_on

    594
    595
    596
    # File 'lib/concurrent/promises.rb', line 594

    def chain(*args, &task)
      chain_on @DefaultExecutor, *args, &task
    end

### #an_event.chain_on(executor, *args) {|*args| ... } ⇒ `Future` #a_future.chain_on(executor, *args) {|fulfilled, value, reason, *args| ... } ⇒ `Future`

Chains the task to be executed asynchronously on executor after it is resolved.

Overloads:

- #an_event.chain_on(executor, *args) {|*args| ... } ⇒ `Future`

  Yields:

  - (`*args`) —

    to the task.

- #a_future.chain_on(executor, *args) {|fulfilled, value, reason, *args| ... } ⇒ `Future`

  Yields:

  - (`fulfilled`, `value`, `reason`, `*args`) —

    to the task.

  Yield Parameters:

  - fulfilled (`true`, `false`)
  - value (`Object`)
  - reason (`Object`)

Parameters:

- executor (`Executor`, `:io`, `:fast`) —

  Instance of an executor or a name of the global executor. The task is executed on it, default executor remains unchanged.

- args (`Object`) —

  arguments which are passed to the task when it's executed. (It might be prepended with other arguments, see the @yeild section).

Yield Returns:

- will become result of the returned Future. Its returned value becomes Future#value fulfilling it, raised exception becomes Future#reason rejecting it.

Returns:

- (`Future`)

    612
    613
    614
    # File 'lib/concurrent/promises.rb', line 612

    def chain_on(executor, *args, &task)
      ChainPromise.new_blocked_by1(self, @DefaultExecutor, executor, args, &task).future
    end

### #chain_resolvable(resolvable) ⇒ `self` Also known as: tangle

Resolves the resolvable when receiver is resolved.

Parameters:

- resolvable (`Resolvable`)

Returns:

- (`self`)

    627
    628
    629
    # File 'lib/concurrent/promises.rb', line 627

    def chain_resolvable(resolvable)
      on_resolution! { resolvable.resolve_with internal_state }
    end

### #default_executor ⇒ `Executor`

Returns default executor.

Returns:

- (`Executor`) —

  default executor

See Also:

- #with_default_executor
- FactoryMethods#future_on
- FactoryMethods#resolvable_future
- FactoryMethods#any_fulfilled_future_on
- similar

    588
    589
    590
    # File 'lib/concurrent/promises.rb', line 588

    def default_executor
      @DefaultExecutor
    end

### #internal_state ⇒ `Object`

Returns The internal_state.

Returns:

- (`Object`) —

  The internal_state.

    513
    # File 'lib/concurrent/promises.rb', line 513

    attr_atomic(:internal_state)

### #on_resolution(*args, &callback) ⇒ `self`

Shortcut of #on_resolution_using with default `:io` executor supplied.

Returns:

- (`self`)

See Also:

- #on_resolution_using

    635
    636
    637
    # File 'lib/concurrent/promises.rb', line 635

    def on_resolution(*args, &callback)
      on_resolution_using @DefaultExecutor, *args, &callback
    end

### #an_event.on_resolution!(*args) {|*args| ... } ⇒ `self` #a_future.on_resolution!(*args) {|fulfilled, value, reason, *args| ... } ⇒ `self`

Stores the callback to be executed synchronously on resolving thread after it is resolved.

Overloads:

- #an_event.on_resolution!(*args) {|*args| ... } ⇒ `self`

  Yields:

  - (`*args`) —

    to the callback.

- #a_future.on_resolution!(*args) {|fulfilled, value, reason, *args| ... } ⇒ `self`

  Yields:

  - (`fulfilled`, `value`, `reason`, `*args`) —

    to the callback.

  Yield Parameters:

  - fulfilled (`true`, `false`)
  - value (`Object`)
  - reason (`Object`)

Parameters:

- args (`Object`) —

  arguments which are passed to the task when it's executed. (It might be prepended with other arguments, see the @yeild section).

Yield Returns:

- is forgotten.

Returns:

- (`self`)

    653
    654
    655
    # File 'lib/concurrent/promises.rb', line 653

    def on_resolution!(*args, &callback)
      add_callback :callback_on_resolution, args, callback
    end

### #an_event.on_resolution_using(executor, *args) {|*args| ... } ⇒ `self` #a_future.on_resolution_using(executor, *args) {|fulfilled, value, reason, *args| ... } ⇒ `self`

Stores the callback to be executed asynchronously on executor after it is resolved.

Overloads:

- #an_event.on_resolution_using(executor, *args) {|*args| ... } ⇒ `self`

  Yields:

  - (`*args`) —

    to the callback.

- #a_future.on_resolution_using(executor, *args) {|fulfilled, value, reason, *args| ... } ⇒ `self`

  Yields:

  - (`fulfilled`, `value`, `reason`, `*args`) —

    to the callback.

  Yield Parameters:

  - fulfilled (`true`, `false`)
  - value (`Object`)
  - reason (`Object`)

Parameters:

- executor (`Executor`, `:io`, `:fast`) —

  Instance of an executor or a name of the global executor. The task is executed on it, default executor remains unchanged.

- args (`Object`) —

  arguments which are passed to the task when it's executed. (It might be prepended with other arguments, see the @yeild section).

Yield Returns:

- is forgotten.

Returns:

- (`self`)

    671
    672
    673
    # File 'lib/concurrent/promises.rb', line 671

    def on_resolution_using(executor, *args, &callback)
      add_callback :async_callback_on_resolution, executor, args, callback
    end

### #pending? ⇒ `Boolean`

Is it in pending state?

Returns:

- (`Boolean`)

    547
    548
    549
    # File 'lib/concurrent/promises.rb', line 547

    def pending?
      !internal_state.resolved?
    end

### #resolved? ⇒ `Boolean`

Is it in resolved state?

Returns:

- (`Boolean`)

    553
    554
    555
    # File 'lib/concurrent/promises.rb', line 553

    def resolved?
      internal_state.resolved?
    end

### #an_event.state ⇒ `:pending`, `:resolved` #a_future.state ⇒ `:pending`, `:fulfilled`, `:rejected`

Returns its state.

Overloads:

- #an_event.state ⇒ `:pending`, `:resolved`

  Returns:

  - (`:pending`, `:resolved`)
- #a_future.state ⇒ `:pending`, `:fulfilled`, `:rejected`

  Both :fulfilled, :rejected implies :resolved.

  Returns:

  - (`:pending`, `:fulfilled`, `:rejected`)

Returns:

- (`Symbol`)

    541
    542
    543
    # File 'lib/concurrent/promises.rb', line 541

    def state
      internal_state.to_sym
    end

### #to_s ⇒ `String` Also known as: inspect

Returns Short string representation.

Returns:

- (`String`) —

  Short string representation.

    617
    618
    619
    # File 'lib/concurrent/promises.rb', line 617

    def to_s
      format '%s %s>', super[0..-2], state
    end

### #touch ⇒ `self`

Propagates touch. Requests all the delayed futures, which it depends on, to be executed. This method is called by any other method requiring resolved state, like #wait.

Returns:

- (`self`)

    560
    561
    562
    563
    # File 'lib/concurrent/promises.rb', line 560

    def touch
      @Promise.touch
      self
    end

### #wait(timeout = nil) ⇒ `self`, `true`, `false`

Note:

This function potentially blocks current thread until the Future is resolved. Be careful it can deadlock. Try to chain instead.

Wait (block the Thread) until receiver is #resolved?. Calls AbstractEventFuture#touch.

Parameters:

- timeout (`Numeric`) (defaults to: `nil`) —

  the maximum time in second to wait.

Returns:

- (`self`, `true`, `false`) —

  self implies timeout was not used, true implies timeout was used and it was resolved, false implies it was not resolved within timeout.

    576
    577
    578
    579
    # File 'lib/concurrent/promises.rb', line 576

    def wait(timeout = nil)
      result = wait_until_resolved(timeout)
      timeout ? result : self
    end

### #with_default_executor(executor) ⇒ `AbstractEventFuture`

This method is abstract.

Crates new object with same class with the executor set as its new default executor. Any futures depending on it will use the new default executor.

Returns:

- (`AbstractEventFuture`)

Raises:

- (`NotImplementedError`)

See Also:

- Event#with_default_executor
- Future#with_default_executor

    681
    682
    683
    # File 'lib/concurrent/promises.rb', line 681

    def with_default_executor(executor)
      raise NotImplementedError
    end