# Class: Concurrent::Promises::AbstractEventFuture

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

Includes:
  ThrottleIntegration

Defined in:
  lib/concurrent/promises.rb,
  lib-edge/concurrent/edge/throttle.rb

## Overview

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

## Direct Known Subclasses

Event, Future

## Defined Under Namespace

Modules: ThrottleIntegration

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

- #chain_throttled_by(throttle, *args, &block) ⇒ Future, Event included from ThrottleIntegration

  Behaves as #chain but the it is throttled.

- #default_executor ⇒ Executor

  Returns default executor.

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

- #throttled_by(throttle) {|a| ... } ⇒ Future, Event included from ThrottleIntegration
- #to_s ⇒ String (also: #inspect)

  Short string representation.

- #touch ⇒ self

  Propagates touch.

- #wait(timeout = nil) ⇒ Future, 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

    576
    577
    578

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

    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 (`Exception`)

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

    594
    595
    596

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

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

    609
    610
    611

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

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

### #chain_throttled_by(throttle, *args, &block) ⇒ `Future`, `Event` Originally defined in module ThrottleIntegration

Behaves as Concurrent::Promises::AbstractEventFuture#chain but the it is throttled.

Returns:

- (`Future`, `Event`)

See Also:

- Concurrent::Promises::AbstractEventFuture#chain

### #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

    570
    571
    572

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

    def default_executor
      @DefaultExecutor
    end

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

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

Returns:

- (`self`)

See Also:

- #on_resolution_using

    617
    618
    619

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

    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 (`Exception`)

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

    635
    636
    637

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

    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 (`Exception`)

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

    653
    654
    655

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

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

    529
    530
    531

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

    def pending?
      !internal_state.resolved?
    end

### #resolved? ⇒ `Boolean`

Is it in resolved state?

Returns:

- (`Boolean`)

    535
    536
    537

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

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

    523
    524
    525

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

    def state
      internal_state.to_sym
    end

### #throttled_by(throttle) {|a| ... } ⇒ `Future`, `Event` Originally defined in module ThrottleIntegration

Yield Parameters:

- a (`Future`) —

  trigger

Yield Returns:

- (`Future`, `Event`)

Returns:

- (`Future`, `Event`)

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

Returns Short string representation.

Returns:

- (`String`) —

  Short string representation.

    599
    600
    601

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

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

    542
    543
    544
    545

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

    def touch
      @Promise.touch
      self
    end

### #wait(timeout = nil) ⇒ `Future`, `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 #touch.

Parameters:

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

  the maximum time in second to wait.

Returns:

- (`Future`, `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.

    558
    559
    560
    561

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

    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

    663
    664
    665

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

    def with_default_executor(executor)
      raise NotImplementedError
    end