Class: Concurrent::Promises::AbstractEventFuture — Concurrent

Class List Method List File List

# Class: Concurrent::Promises::AbstractEventFuture

Inherits:
  Synchronization::Object
  - Object
  - Synchronization::Object
  - Concurrent::Promises::AbstractEventFuture
  show all
Includes:
  ThrottleIntegration
Defined in:
  lib/concurrent/edge/promises.rb,
  lib/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

## Constant Summary

## Instance Method Summary (collapse)

- - (undocumented) add_callback_notify_blocked(promise, index)

  # @!visibility private.

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

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

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

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

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

  Resolves the resolvable when receiver is resolved.

- - (Promises::Future, Promises::Event) chain_throttled_by(throttle, *args, &block) included from ThrottleIntegration

  Behaves as #chain but the it is throttled.

- - (Executor) default_executor

  Returns default executor.

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

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

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

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

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

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

- - (Boolean) pending?(state = internal_state)

  Is it in pending state?.

- - (Boolean) resolved?(state = internal_state)

  Is it in resolved state?.

- - (Symbol) state

  Returns its state.

- - (undocumented) throttled_by(throttle, &throttled_futures) included from ThrottleIntegration
- - (String) to_s (also: #inspect)

  Short string representation.

- - (self) touch

  Propagates touch.

- - (Future, true, false) wait(timeout = nil)

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

- - (AbstractEventFuture) with_default_executor(executor) abstract

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

## Instance Method Details

### - (`undocumented`) add_callback_notify_blocked(promise, index)

# @!visibility private

    742
    743
    744
    # File 'lib/concurrent/edge/promises.rb', line 742

    def add_callback_notify_blocked(promise, index)
      add_callback :callback_notify_blocked, promise, index
    end

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

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

Returns:

- (`Future`)

See Also:

- #chain_on

    605
    606
    607
    # File 'lib/concurrent/edge/promises.rb', line 605

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

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

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

Overloads:

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

  Yields:

  - (`*args`) —

    to the task.

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

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

    623
    624
    625
    # File 'lib/concurrent/edge/promises.rb', line 623

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

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

Resolves the resolvable when receiver is resolved.

Parameters:

- resolvable (`Resolvable`)

Returns:

- (`self`)

    638
    639
    640
    # File 'lib/concurrent/edge/promises.rb', line 638

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

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

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

Returns:

- (`Promises::Future`, `Promises::Event`)

See Also:

- Concurrent::Promises::AbstractEventFuture#chain

### - (`Executor`) default_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

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

    def default_executor
      @DefaultExecutor
    end

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

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

Returns:

- (`self`)

See Also:

- #on_resolution_using

    646
    647
    648
    # File 'lib/concurrent/edge/promises.rb', line 646

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

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

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

Overloads:

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

  Yields:

  - (`*args`) —

    to the callback.

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

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

    664
    665
    666
    # File 'lib/concurrent/edge/promises.rb', line 664

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

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

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

Overloads:

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

  Yields:

  - (`*args`) —

    to the callback.

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

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

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

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

### - (`Boolean`) pending?(state = internal_state)

Is it in pending state?

Returns:

- (`Boolean`)

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

    def pending?(state = internal_state)
      !state.resolved?
    end

### - (`Boolean`) resolved?(state = internal_state)

Is it in resolved state?

Returns:

- (`Boolean`)

    564
    565
    566
    # File 'lib/concurrent/edge/promises.rb', line 564

    def resolved?(state = internal_state)
      state.resolved?
    end

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

Returns its state.

Overloads:

- - (`:pending`, `:resolved`) an_event.state

  Returns:

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

  Both :fulfilled, :rejected implies :resolved.

  Returns:

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

Returns:

- (`Symbol`)

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

    def state
      internal_state.to_sym
    end

### - (`undocumented`) throttled_by(throttle, &throttled_futures) Originally defined in module ThrottleIntegration

### - (`String`) to_s Also known as: inspect

Returns Short string representation.

Returns:

- (`String`) —

  Short string representation.

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

    def to_s
      format '<#%s:0x%x %s>', self.class, object_id << 1, state
    end

### - (`self`) touch

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

    571
    572
    573
    574
    # File 'lib/concurrent/edge/promises.rb', line 571

    def touch
      @Promise.touch
      self
    end

### - (`Future`, `true`, `false`) wait(timeout = nil)

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.

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

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

### - (`AbstractEventFuture`) with_default_executor(executor)

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

    692
    693
    694
    # File 'lib/concurrent/edge/promises.rb', line 692

    def with_default_executor(executor)
      raise NotImplementedError
    end