Module: Concurrent::Promises::FactoryMethods — Concurrent

Class List Method List File List

# Module: Concurrent::Promises::FactoryMethods

Includes:
  Configuration, NewChannelIntegration
Included in:
  Concurrent::Promises
Defined in:
  lib/concurrent/edge/promises.rb,
  lib/concurrent/edge/old_channel_integration.rb,
  lib/concurrent/edge/promises.rb

## Overview

Container of all Future, Event factory methods. They are never constructed directly with new.

## Defined Under Namespace

Modules: Configuration, NewChannelIntegration

## Class Method Summary (collapse)

- + (undocumented) extended(base) extended from ReInclude
- + (undocumented) include(*modules) extended from ReInclude
- + (undocumented) included(base) extended from ReInclude

## Instance Method Summary (collapse)

- - (Future) any_event(*futures_and_or_events)

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

- - (Event) any_event_on(default_executor, *futures_and_or_events)

  Creates new event which becomes resolved after first of the futures_and_or_events resolves.

- - (Future) any_fulfilled_future(*futures_and_or_events)

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

- - (Future) any_fulfilled_future_on(default_executor, *futures_and_or_events)

  Creates new future which is resolved after first of futures_and_or_events is fulfilled.

- - (Future) any_resolved_future(*futures_and_or_events) (also: #any)

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

- - (Future) any_resolved_future_on(default_executor, *futures_and_or_events)

  Creates new future which is resolved after first futures_and_or_events is resolved.

- - (Event, Future) create(argument = nil, default_executor = self.default_executor)

  General constructor.

- - (Executor, :io, :fast) default_executor included from Configuration

  The executor which is used when none is supplied to a factory method.

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

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

- - (Future) delay_on(default_executor, *args) {|*args| ... }

  Constructs new Future which will be resolved after block is evaluated on default executor.

- - (Future) fulfilled_future(value, default_executor = self.default_executor)

  Creates resolved future with will be fulfilled with the given value.

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

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

- - (Future) future_on(default_executor, *args) {|*args| ... }

  Constructs new Future which will be resolved after block is evaluated on default executor.

- - (Future) rejected_future(reason, default_executor = self.default_executor)

  Creates resolved future with will be rejected with the given reason.

- - (ResolvableEvent) resolvable_event

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

- - (ResolvableEvent) resolvable_event_on(default_executor = self.default_executor)

  Created resolvable event, user is responsible for resolving the event once by ResolvableEvent#resolve.

- - (ResolvableFuture) resolvable_future

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

- - (ResolvableFuture) resolvable_future_on(default_executor = self.default_executor)

  Creates resolvable future, user is responsible for resolving the future once by ResolvableFuture#resolve, ResolvableFuture#fulfill, or ResolvableFuture#reject.

- - (Event) resolved_event(default_executor = self.default_executor)

  Creates resolved event.

- - (Future) resolved_future(fulfilled, value, reason, default_executor = self.default_executor)

  Creates resolved future with will be either fulfilled with the given value or rejection with the given reason.

- - (Future) schedule(intended_time, *args, &task)

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

- - (Future) schedule_on(default_executor, intended_time, *args) {|*args| ... }

  Constructs new Future which will be resolved after block is evaluated on default executor.

- - (Future) select_channel(*channels) included from NewChannelIntegration

  Selects a channel which is ready to be read from.

- - (Event) zip_events(*futures_and_or_events)

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

- - (Event) zip_events_on(default_executor, *futures_and_or_events)

  Creates new event which is resolved after all futures_and_or_events are resolved.

- - (Future) zip_futures(*futures_and_or_events) (also: #zip)

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

- - (Future) zip_futures_on(default_executor, *futures_and_or_events)

  Creates new future which is resolved after all futures_and_or_events are resolved.

## Class Method Details

### + (`undocumented`) extended(base) Originally defined in module ReInclude

### + (`undocumented`) include(*modules) Originally defined in module ReInclude

### + (`undocumented`) included(base) Originally defined in module ReInclude

## Instance Method Details

### - (`Future`) any_event(*futures_and_or_events)

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

Returns:

- (`Future`)

See Also:

- #any_event_on

    323
    324
    325
    # File 'lib/concurrent/edge/promises.rb', line 323

    def any_event(*futures_and_or_events)
      any_event_on default_executor, *futures_and_or_events
    end

### - (`Event`) any_event_on(default_executor, *futures_and_or_events)

Creates new event which becomes resolved after first of the futures_and_or_events resolves. If resolved it does not propagate AbstractEventFuture#touch, leaving delayed futures un-executed if they are not required any more.

Parameters:

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

  Instance of an executor or a name of the global executor. Default executor propagates to chained futures unless overridden with executor parameter or changed with AbstractEventFuture#with_default_executor.

- futures_and_or_events (`AbstractEventFuture`)

Returns:

- (`Event`)

    333
    334
    335
    # File 'lib/concurrent/edge/promises.rb', line 333

    def any_event_on(default_executor, *futures_and_or_events)
      AnyResolvedEventPromise.new_blocked_by(futures_and_or_events, default_executor).event
    end

### - (`Future`) any_fulfilled_future(*futures_and_or_events)

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

Returns:

- (`Future`)

See Also:

- #any_fulfilled_future_on

    304
    305
    306
    # File 'lib/concurrent/edge/promises.rb', line 304

    def any_fulfilled_future(*futures_and_or_events)
      any_fulfilled_future_on default_executor, *futures_and_or_events
    end

### - (`Future`) any_fulfilled_future_on(default_executor, *futures_and_or_events)

Creates new future which is resolved after first of futures_and_or_events is fulfilled. Its result equals result of the first resolved future or if all futures_and_or_events reject, it has reason of the last resolved future. If resolved it does not propagate AbstractEventFuture#touch, leaving delayed futures un-executed if they are not required any more. If event is supplied, which does not have value and can be only resolved, it's represented as `:fulfilled` with value `nil`.

Parameters:

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

  Instance of an executor or a name of the global executor. Default executor propagates to chained futures unless overridden with executor parameter or changed with AbstractEventFuture#with_default_executor.

- futures_and_or_events (`AbstractEventFuture`)

Returns:

- (`Future`)

    317
    318
    319
    # File 'lib/concurrent/edge/promises.rb', line 317

    def any_fulfilled_future_on(default_executor, *futures_and_or_events)
      AnyFulfilledFuturePromise.new_blocked_by(futures_and_or_events, default_executor).future
    end

### - (`Future`) any_resolved_future(*futures_and_or_events) Also known as: any

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

Returns:

- (`Future`)

See Also:

- #any_resolved_future_on

    282
    283
    284
    # File 'lib/concurrent/edge/promises.rb', line 282

    def any_resolved_future(*futures_and_or_events)
      any_resolved_future_on default_executor, *futures_and_or_events
    end

### - (`Future`) any_resolved_future_on(default_executor, *futures_and_or_events)

Creates new future which is resolved after first futures_and_or_events is resolved. Its result equals result of the first resolved future. If resolved it does not propagate AbstractEventFuture#touch, leaving delayed futures un-executed if they are not required any more. If event is supplied, which does not have value and can be only resolved, it's represented as `:fulfilled` with value `nil`.

Parameters:

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

  Instance of an executor or a name of the global executor. Default executor propagates to chained futures unless overridden with executor parameter or changed with AbstractEventFuture#with_default_executor.

- futures_and_or_events (`AbstractEventFuture`)

Returns:

- (`Future`)

    298
    299
    300
    # File 'lib/concurrent/edge/promises.rb', line 298

    def any_resolved_future_on(default_executor, *futures_and_or_events)
      AnyResolvedFuturePromise.new_blocked_by(futures_and_or_events, default_executor).future
    end

### - (`Event`) create(nil, default_executor = self.default_executor) - (`Future`) create(a_future, default_executor = self.default_executor) - (`Event`) create(an_event, default_executor = self.default_executor) - (`Future`) create(exception, default_executor = self.default_executor) - (`Future`) create(value, default_executor = self.default_executor)

General constructor. Behaves differently based on the argument's type. It's provided for convenience but it's better to be explicit.

Overloads:

- - (`Event`) create(nil, default_executor = self.default_executor)

  Returns resolved event.

  Parameters:

  - nil (`nil`)

  Returns:

  - (`Event`) —

    resolved event.

- - (`Future`) create(a_future, default_executor = self.default_executor)

  Returns a future which will be resolved when a_future is.

  Parameters:

  - a_future (`Future`)

  Returns:

  - (`Future`) —

    a future which will be resolved when a_future is.

- - (`Event`) create(an_event, default_executor = self.default_executor)

  Returns an event which will be resolved when an_event is.

  Parameters:

  - an_event (`Event`)

  Returns:

  - (`Event`) —

    an event which will be resolved when an_event is.

- - (`Future`) create(exception, default_executor = self.default_executor)

  Returns a rejected future with the exception as its reason.

  Parameters:

  - exception (`Exception`)

  Returns:

  - (`Future`) —

    a rejected future with the exception as its reason.

- - (`Future`) create(value, default_executor = self.default_executor)

  Returns a fulfilled future with the value.

  Parameters:

  - value (`Object`) —

    when none of the above overloads fits

  Returns:

  - (`Future`) —

    a fulfilled future with the value.

Parameters:

- default_executor (`Executor`, `:io`, `:fast`) (defaults to: `self.default_executor`) —

  Instance of an executor or a name of the global executor. Default executor propagates to chained futures unless overridden with executor parameter or changed with AbstractEventFuture#with_default_executor.

Returns:

- (`Event`, `Future`)

See Also:

- resolved_event, fulfilled_future

    197
    198
    199
    200
    201
    202
    203
    204
    205
    206
    207
    208
    209
    # File 'lib/concurrent/edge/promises.rb', line 197

    def create(argument = nil, default_executor = self.default_executor)
      case argument
      when AbstractEventFuture
        # returning wrapper would change nothing
        argument
      when Exception
        rejected_future argument, default_executor
      when nil
        resolved_event default_executor
      else
        fulfilled_future argument, default_executor
      end
    end

### - (`Executor`, `:io`, `:fast`) default_executor Originally defined in module Configuration

Returns the executor which is used when none is supplied to a factory method. The method can be overridden in the receivers of `include FactoryMethod`

Returns:

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

  the executor which is used when none is supplied to a factory method. The method can be overridden in the receivers of `include FactoryMethod`

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

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

Returns:

- (`Future`)

See Also:

- #delay_on

    213
    214
    215
    # File 'lib/concurrent/edge/promises.rb', line 213

    def delay(*args, &task)
      delay_on default_executor, *args, &task
    end

### - (`Future`) delay_on(default_executor, *args) {|*args| ... }

Constructs new Future which will be resolved after block is evaluated on default executor. The task will be evaluated only after the future is touched, see AbstractEventFuture#touch

Parameters:

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

  Instance of an executor or a name of the global executor. Default executor propagates to chained futures unless overridden with executor parameter or changed with AbstractEventFuture#with_default_executor.

- args (`Object`) —

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

Yields:

- (`*args`) —

  to the task.

Yield Returns:

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

Returns:

- (`Future`)

    221
    222
    223
    # File 'lib/concurrent/edge/promises.rb', line 221

    def delay_on(default_executor, *args, &task)
      DelayPromise.new(default_executor).event.chain(*args, &task)
    end

### - (`Future`) fulfilled_future(value, default_executor = self.default_executor)

Creates resolved future with will be fulfilled with the given value.

Parameters:

- default_executor (`Executor`, `:io`, `:fast`) (defaults to: `self.default_executor`) —

  Instance of an executor or a name of the global executor. Default executor propagates to chained futures unless overridden with executor parameter or changed with AbstractEventFuture#with_default_executor.

Returns:

- (`Future`)

    151
    152
    153
    # File 'lib/concurrent/edge/promises.rb', line 151

    def fulfilled_future(value, default_executor = self.default_executor)
      resolved_future true, value, nil, default_executor
    end

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

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

Returns:

- (`Future`)

See Also:

- #future_on

    120
    121
    122
    # File 'lib/concurrent/edge/promises.rb', line 120

    def future(*args, &task)
      future_on(default_executor, *args, &task)
    end

### - (`Future`) future_on(default_executor, *args) {|*args| ... }

Constructs new Future which will be resolved after block is evaluated on default executor. Evaluation begins immediately.

Parameters:

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

  Instance of an executor or a name of the global executor. Default executor propagates to chained futures unless overridden with executor parameter or changed with AbstractEventFuture#with_default_executor.

- args (`Object`) —

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

Yields:

- (`*args`) —

  to the task.

Yield Returns:

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

Returns:

- (`Future`)

    134
    135
    136
    # File 'lib/concurrent/edge/promises.rb', line 134

    def future_on(default_executor, *args, &task)
      ImmediateEventPromise.new(default_executor).future.then(*args, &task)
    end

### - (`Future`) rejected_future(reason, default_executor = self.default_executor)

Creates resolved future with will be rejected with the given reason.

Parameters:

- default_executor (`Executor`, `:io`, `:fast`) (defaults to: `self.default_executor`) —

  Instance of an executor or a name of the global executor. Default executor propagates to chained futures unless overridden with executor parameter or changed with AbstractEventFuture#with_default_executor.

Returns:

- (`Future`)

    159
    160
    161
    # File 'lib/concurrent/edge/promises.rb', line 159

    def rejected_future(reason, default_executor = self.default_executor)
      resolved_future false, nil, reason, default_executor
    end

### - (`ResolvableEvent`) resolvable_event

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

Returns:

- (`ResolvableEvent`)

See Also:

- #resolvable_event_on

    89
    90
    91
    # File 'lib/concurrent/edge/promises.rb', line 89

    def resolvable_event
      resolvable_event_on default_executor
    end

### - (`ResolvableEvent`) resolvable_event_on(default_executor = self.default_executor)

Created resolvable event, user is responsible for resolving the event once by ResolvableEvent#resolve.

Parameters:

- default_executor (`Executor`, `:io`, `:fast`) (defaults to: `self.default_executor`) —

  Instance of an executor or a name of the global executor. Default executor propagates to chained futures unless overridden with executor parameter or changed with AbstractEventFuture#with_default_executor.

Returns:

- (`ResolvableEvent`)

    98
    99
    100
    # File 'lib/concurrent/edge/promises.rb', line 98

    def resolvable_event_on(default_executor = self.default_executor)
      ResolvableEventPromise.new(default_executor).future
    end

### - (`ResolvableFuture`) resolvable_future

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

Returns:

- (`ResolvableFuture`)

See Also:

- #resolvable_future_on

    104
    105
    106
    # File 'lib/concurrent/edge/promises.rb', line 104

    def resolvable_future
      resolvable_future_on default_executor
    end

### - (`ResolvableFuture`) resolvable_future_on(default_executor = self.default_executor)

Creates resolvable future, user is responsible for resolving the future once by ResolvableFuture#resolve, ResolvableFuture#fulfill, or ResolvableFuture#reject

Parameters:

- default_executor (`Executor`, `:io`, `:fast`) (defaults to: `self.default_executor`) —

  Instance of an executor or a name of the global executor. Default executor propagates to chained futures unless overridden with executor parameter or changed with AbstractEventFuture#with_default_executor.

Returns:

- (`ResolvableFuture`)

    114
    115
    116
    # File 'lib/concurrent/edge/promises.rb', line 114

    def resolvable_future_on(default_executor = self.default_executor)
      ResolvableFuturePromise.new(default_executor).future
    end

### - (`Event`) resolved_event(default_executor = self.default_executor)

Creates resolved event.

Parameters:

- default_executor (`Executor`, `:io`, `:fast`) (defaults to: `self.default_executor`) —

  Instance of an executor or a name of the global executor. Default executor propagates to chained futures unless overridden with executor parameter or changed with AbstractEventFuture#with_default_executor.

Returns:

- (`Event`)

    167
    168
    169
    # File 'lib/concurrent/edge/promises.rb', line 167

    def resolved_event(default_executor = self.default_executor)
      ImmediateEventPromise.new(default_executor).event
    end

### - (`Future`) resolved_future(fulfilled, value, reason, default_executor = self.default_executor)

Creates resolved future with will be either fulfilled with the given value or rejection with the given reason.

Parameters:

- default_executor (`Executor`, `:io`, `:fast`) (defaults to: `self.default_executor`) —

  Instance of an executor or a name of the global executor. Default executor propagates to chained futures unless overridden with executor parameter or changed with AbstractEventFuture#with_default_executor.

Returns:

- (`Future`)

    143
    144
    145
    # File 'lib/concurrent/edge/promises.rb', line 143

    def resolved_future(fulfilled, value, reason, default_executor = self.default_executor)
      ImmediateFuturePromise.new(default_executor, fulfilled, value, reason).future
    end

### - (`Future`) schedule(intended_time, *args, &task)

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

Returns:

- (`Future`)

See Also:

- #schedule_on

    227
    228
    229
    # File 'lib/concurrent/edge/promises.rb', line 227

    def schedule(intended_time, *args, &task)
      schedule_on default_executor, intended_time, *args, &task
    end

### - (`Future`) schedule_on(default_executor, intended_time, *args) {|*args| ... }

Constructs new Future which will be resolved after block is evaluated on default executor. The task is planned for execution in intended_time.

Parameters:

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

  Instance of an executor or a name of the global executor. Default executor propagates to chained futures unless overridden with executor parameter or changed with AbstractEventFuture#with_default_executor.

- args (`Object`) —

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

- intended_time (`Numeric`, `Time`) —

  `Numeric` means to run in `intended_time` seconds. `Time` means to run on `intended_time`.

Yields:

- (`*args`) —

  to the task.

Yield Returns:

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

Returns:

- (`Future`)

    238
    239
    240
    # File 'lib/concurrent/edge/promises.rb', line 238

    def schedule_on(default_executor, intended_time, *args, &task)
      ScheduledPromise.new(default_executor, intended_time).event.chain(*args, &task)
    end

### - (`Future`) select_channel(*channels) Originally defined in module NewChannelIntegration

Selects a channel which is ready to be read from.

Parameters:

- channels (`Channel`)

Returns:

- (`Future`) —

  a future which is fulfilled with pair [channel, message] when one of the channels is available for reading

### - (`Event`) zip_events(*futures_and_or_events)

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

Returns:

- (`Event`)

See Also:

- #zip_events_on

    266
    267
    268
    # File 'lib/concurrent/edge/promises.rb', line 266

    def zip_events(*futures_and_or_events)
      zip_events_on default_executor, *futures_and_or_events
    end

### - (`Event`) zip_events_on(default_executor, *futures_and_or_events)

Creates new event which is resolved after all futures_and_or_events are resolved. (Future is resolved when fulfilled or rejected.)

Parameters:

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

  Instance of an executor or a name of the global executor. Default executor propagates to chained futures unless overridden with executor parameter or changed with AbstractEventFuture#with_default_executor.

- futures_and_or_events (`AbstractEventFuture`)

Returns:

- (`Event`)

    276
    277
    278
    # File 'lib/concurrent/edge/promises.rb', line 276

    def zip_events_on(default_executor, *futures_and_or_events)
      ZipEventsPromise.new_blocked_by(futures_and_or_events, default_executor).event
    end

### - (`Future`) zip_futures(*futures_and_or_events) Also known as: zip

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

Returns:

- (`Future`)

See Also:

- #zip_futures_on

    244
    245
    246
    # File 'lib/concurrent/edge/promises.rb', line 244

    def zip_futures(*futures_and_or_events)
      zip_futures_on default_executor, *futures_and_or_events
    end

### - (`Future`) zip_futures_on(default_executor, *futures_and_or_events)

Creates new future which is resolved after all futures_and_or_events are resolved. Its value is array of zipped future values. Its reason is array of reasons for rejection. If there is an error it rejects. If event is supplied, which does not have value and can be only resolved, it's represented as `:fulfilled` with value `nil`.

Parameters:

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

  Instance of an executor or a name of the global executor. Default executor propagates to chained futures unless overridden with executor parameter or changed with AbstractEventFuture#with_default_executor.

- futures_and_or_events (`AbstractEventFuture`)

Returns:

- (`Future`)

    258
    259
    260
    # File 'lib/concurrent/edge/promises.rb', line 258

    def zip_futures_on(default_executor, *futures_and_or_events)
      ZipFuturesPromise.new_blocked_by(futures_and_or_events, default_executor).future
    end