Module: Concurrent::Promises::FactoryMethods

Extended by:
FactoryMethods
Includes:
Configuration
Included in:
Concurrent::Promises, FactoryMethods, Throttle
Defined in:
lib/concurrent-ruby/concurrent/promises.rb,
lib/concurrent-ruby-edge/concurrent/edge/promises.rb,
lib/concurrent-ruby-edge/concurrent/edge/old_channel_integration.rb

Overview

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

Defined Under Namespace

Modules: Configuration

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.any_event(*futures_and_or_events) ⇒ Event

Shortcut of #any_event_on with default :io executor supplied.

Returns:

See Also:



319
320
321
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 319

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

.any_event_on(default_executor, *futures_and_or_events) ⇒ Event

Creates a new event which becomes resolved after the first 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:

Returns:



329
330
331
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 329

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

.any_fulfilled_future(*futures_and_or_events) ⇒ Future

Shortcut of #any_fulfilled_future_on with default :io executor supplied.

Returns:

See Also:



300
301
302
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 300

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

.any_fulfilled_future_on(default_executor, *futures_and_or_events) ⇒ Future

Creates a new future which is resolved after the first futures_and_or_events is fulfilled. Its result equals the result of the first resolved future or if all futures_and_or_events reject, it has reason of the last rejected 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:

Returns:



313
314
315
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 313

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

.any_resolved_future(*futures_and_or_events) ⇒ Future Also known as: any

Shortcut of #any_resolved_future_on with default :io executor supplied.

Returns:

See Also:



278
279
280
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 278

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

.any_resolved_future_on(default_executor, *futures_and_or_events) ⇒ Future

Creates a new future which is resolved after the first futures_and_or_events is resolved. Its result equals the 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:

Returns:



294
295
296
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 294

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

.delay(*args, &task) ⇒ Future, Event

Shortcut of #delay_on with default :io executor supplied.

Returns:

See Also:



190
191
192
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 190

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

#delay_on(default_executor, *args) {|*args| ... } ⇒ Future #delay_on(default_executor) ⇒ Event

Creates a new event or future which is resolved only after it is touched, see AbstractEventFuture#touch.

Overloads:

  • #delay_on(default_executor, *args) {|*args| ... } ⇒ Future

    If task is provided it returns a Concurrent::Promises::Future representing the result of the task.

    Parameters:

    • args (Object) —

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

    Yields:

    • (*args) —

      to the task.

    Yield Returns:

    Returns:

  • #delay_on(default_executor) ⇒ Event

    If no task is provided, it returns an Event

    Returns:

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.



207
208
209
210
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 207

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

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

Creates a resolved future which 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.

  • value (Object)

Returns:



127
128
129
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 127

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

.future(*args, &task) ⇒ Future

Shortcut of #future_on with default :io executor supplied.

Returns:

See Also:



94
95
96
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 94

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

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

Constructs a 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 @yield section).

Yields:

  • (*args) —

    to the task.

Yield Returns:

Returns:



106
107
108
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 106

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

#make_future(nil, default_executor = self.default_executor) ⇒ Event #make_future(a_future, default_executor = self.default_executor) ⇒ Future #make_future(an_event, default_executor = self.default_executor) ⇒ Event #make_future(exception, default_executor = self.default_executor) ⇒ Future #make_future(value, default_executor = self.default_executor) ⇒ Future

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

Overloads:

  • #make_future(nil, default_executor = self.default_executor) ⇒ Event

    Returns resolved event.

    Parameters:

    • nil (nil)

    Returns:

    • (Event) —

      resolved event.

  • #make_future(a_future, default_executor = self.default_executor) ⇒ Future

    Returns a future which will be resolved when a_future is.

    Parameters:

    Returns:

    • (Future) —

      a future which will be resolved when a_future is.

  • #make_future(an_event, default_executor = self.default_executor) ⇒ Event

    Returns an event which will be resolved when an_event is.

    Parameters:

    Returns:

    • (Event) —

      an event which will be resolved when an_event is.

  • #make_future(exception, default_executor = self.default_executor) ⇒ Future

    Returns a rejected future with the exception as its reason.

    Parameters:

    • exception (Exception)

    Returns:

    • (Future) —

      a rejected future with the exception as its reason.

  • #make_future(value, default_executor = self.default_executor) ⇒ Future

    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:

See Also:

  • resolved_event, fulfilled_future


174
175
176
177
178
179
180
181
182
183
184
185
186
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 174

def make_future(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

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

Creates a resolved future which 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.

  • reason (Object)

Returns:



136
137
138
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 136

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

.resolvable_event ⇒ ResolvableEvent

Shortcut of #resolvable_event_on with default :io executor supplied.

Returns:

See Also:



63
64
65
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 63

def resolvable_event
  resolvable_event_on default_executor
end

.resolvable_event_on(default_executor = self.default_executor) ⇒ ResolvableEvent

Creates a resolvable event, user is responsible for resolving the event once by calling 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:



72
73
74
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 72

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

.resolvable_future ⇒ ResolvableFuture

Shortcut of #resolvable_future_on with default :io executor supplied.

Returns:

See Also:



78
79
80
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 78

def resolvable_future
  resolvable_future_on default_executor
end

.resolvable_future_on(default_executor = self.default_executor) ⇒ ResolvableFuture

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:



88
89
90
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 88

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

.resolved_event(default_executor = self.default_executor) ⇒ Event

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:



144
145
146
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 144

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

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

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

Parameters:

  • fulfilled (true, false)
  • value (Object)
  • reason (Object)
  • 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:



118
119
120
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 118

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

.schedule(intended_time, *args, &task) ⇒ Future, Event

Shortcut of #schedule_on with default :io executor supplied.

Returns:

See Also:



214
215
216
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 214

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

#schedule_on(default_executor, intended_time, *args) {|*args| ... } ⇒ Future #schedule_on(default_executor, intended_time) ⇒ Event

Creates a new event or future which is resolved in intended_time.

Overloads:

  • #schedule_on(default_executor, intended_time, *args) {|*args| ... } ⇒ Future

    If task is provided it returns a Concurrent::Promises::Future representing the result of the task.

    Parameters:

    • args (Object) —

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

    Yields:

    • (*args) —

      to the task.

    Yield Returns:

    Returns:

  • #schedule_on(default_executor, intended_time) ⇒ Event

    If no task is provided, it returns an Event

    Returns:

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.

  • intended_time (Numeric, Time) —

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



233
234
235
236
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 233

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

.zip_events(*futures_and_or_events) ⇒ Event

Shortcut of #zip_events_on with default :io executor supplied.

Returns:

See Also:



262
263
264
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 262

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

.zip_events_on(default_executor, *futures_and_or_events) ⇒ Event

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

Parameters:

Returns:



272
273
274
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 272

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

.zip_futures(*futures_and_or_events) ⇒ Future Also known as: zip

Shortcut of #zip_futures_on with default :io executor supplied.

Returns:

See Also:



240
241
242
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 240

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

.zip_futures_on(default_executor, *futures_and_or_events) ⇒ Future

Creates a new future which is resolved after all futures_and_or_events are resolved. Its value is an array of zipped future values. Its reason is an 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:

Returns:



254
255
256
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 254

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

.zip_futures_over(enumerable, &future_factory) ⇒ Future

Note:

Edge Features are under active development and may change frequently.

  • Deprecations are not added before incompatible changes.
  • Edge version: major is always 0, minor bump means incompatible change, patch bump means compatible change.
  • Edge features may also lack tests and documentation.
  • Features developed in concurrent-ruby-edge are expected to move to concurrent-ruby when finalised.

Shortcut of #zip_futures_over_on with default :io executor supplied.

Returns:

See Also:



72
73
74
 
# File 'lib/concurrent-ruby-edge/concurrent/edge/promises.rb', line 72

def zip_futures_over(enumerable, &future_factory)
  zip_futures_over_on default_executor, enumerable, &future_factory
end

.zip_futures_over_on(default_executor, enumerable) {|element| ... } ⇒ Future

Note:

Edge Features are under active development and may change frequently.

  • Deprecations are not added before incompatible changes.
  • Edge version: major is always 0, minor bump means incompatible change, patch bump means compatible change.
  • Edge features may also lack tests and documentation.
  • Features developed in concurrent-ruby-edge are expected to move to concurrent-ruby when finalised.

Creates new future which is resolved after all the futures created by future_factory from enumerable elements are resolved. Simplified it does: zip(*enumerable.map { |e| future e, &future_factory })

Examples:

# `#succ` calls are executed in parallel
zip_futures_over_on(:io, [1, 2], &:succ).value! # => [2, 3]

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.

  • enumerable (Enumerable)

Yields:

  • a task to be executed in future

Yield Parameters:

  • element (Object) —

    from enumerable

Yield Returns:

  • (Object) —

    a value of the future

Returns:



90
91
92
93
 
# File 'lib/concurrent-ruby-edge/concurrent/edge/promises.rb', line 90

def zip_futures_over_on(default_executor, enumerable, &future_factory)
  # ZipFuturesPromise.new_blocked_by(futures_and_or_events, default_executor).future
  zip_futures_on(default_executor, *enumerable.map { |e| future e, &future_factory })
end

.default_executor ⇒ Executor, :io, :fast 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

Instance Method Details

#any_event(*futures_and_or_events) ⇒ Event

Shortcut of #any_event_on with default :io executor supplied.

Returns:

See Also:



319
320
321
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 319

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

#any_event_on(default_executor, *futures_and_or_events) ⇒ Event

Creates a new event which becomes resolved after the first 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:

Returns:



329
330
331
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 329

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

#any_fulfilled_future(*futures_and_or_events) ⇒ Future

Shortcut of #any_fulfilled_future_on with default :io executor supplied.

Returns:

See Also:



300
301
302
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 300

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

#any_fulfilled_future_on(default_executor, *futures_and_or_events) ⇒ Future

Creates a new future which is resolved after the first futures_and_or_events is fulfilled. Its result equals the result of the first resolved future or if all futures_and_or_events reject, it has reason of the last rejected 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:

Returns:



313
314
315
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 313

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

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

Shortcut of #any_resolved_future_on with default :io executor supplied.

Returns:

See Also:



278
279
280
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 278

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

#any_resolved_future_on(default_executor, *futures_and_or_events) ⇒ Future

Creates a new future which is resolved after the first futures_and_or_events is resolved. Its result equals the 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:

Returns:



294
295
296
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 294

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

#delay(*args, &task) ⇒ Future, Event

Shortcut of #delay_on with default :io executor supplied.

Returns:

See Also:



190
191
192
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 190

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

#delay_on(default_executor, *args) {|*args| ... } ⇒ Future #delay_on(default_executor) ⇒ Event

Creates a new event or future which is resolved only after it is touched, see AbstractEventFuture#touch.

Overloads:

  • #delay_on(default_executor, *args) {|*args| ... } ⇒ Future

    If task is provided it returns a Concurrent::Promises::Future representing the result of the task.

    Parameters:

    • args (Object) —

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

    Yields:

    • (*args) —

      to the task.

    Yield Returns:

    Returns:

  • #delay_on(default_executor) ⇒ Event

    If no task is provided, it returns an Event

    Returns:

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.



207
208
209
210
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 207

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

#fulfilled_future(value, default_executor = self.default_executor) ⇒ Future

Creates a resolved future which 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.

  • value (Object)

Returns:



127
128
129
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 127

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

#future(*args, &task) ⇒ Future

Shortcut of #future_on with default :io executor supplied.

Returns:

See Also:



94
95
96
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 94

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

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

Constructs a 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 @yield section).

Yields:

  • (*args) —

    to the task.

Yield Returns:

Returns:



106
107
108
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 106

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

#make_future(nil, default_executor = self.default_executor) ⇒ Event #make_future(a_future, default_executor = self.default_executor) ⇒ Future #make_future(an_event, default_executor = self.default_executor) ⇒ Event #make_future(exception, default_executor = self.default_executor) ⇒ Future #make_future(value, default_executor = self.default_executor) ⇒ Future

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

Overloads:

  • #make_future(nil, default_executor = self.default_executor) ⇒ Event

    Returns resolved event.

    Parameters:

    • nil (nil)

    Returns:

    • (Event) —

      resolved event.

  • #make_future(a_future, default_executor = self.default_executor) ⇒ Future

    Returns a future which will be resolved when a_future is.

    Parameters:

    Returns:

    • (Future) —

      a future which will be resolved when a_future is.

  • #make_future(an_event, default_executor = self.default_executor) ⇒ Event

    Returns an event which will be resolved when an_event is.

    Parameters:

    Returns:

    • (Event) —

      an event which will be resolved when an_event is.

  • #make_future(exception, default_executor = self.default_executor) ⇒ Future

    Returns a rejected future with the exception as its reason.

    Parameters:

    • exception (Exception)

    Returns:

    • (Future) —

      a rejected future with the exception as its reason.

  • #make_future(value, default_executor = self.default_executor) ⇒ Future

    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:

See Also:

  • resolved_event, fulfilled_future


174
175
176
177
178
179
180
181
182
183
184
185
186
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 174

def make_future(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

#rejected_future(reason, default_executor = self.default_executor) ⇒ Future

Creates a resolved future which 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.

  • reason (Object)

Returns:



136
137
138
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 136

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

#resolvable_event ⇒ ResolvableEvent

Shortcut of #resolvable_event_on with default :io executor supplied.

Returns:

See Also:



63
64
65
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 63

def resolvable_event
  resolvable_event_on default_executor
end

#resolvable_event_on(default_executor = self.default_executor) ⇒ ResolvableEvent

Creates a resolvable event, user is responsible for resolving the event once by calling 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:



72
73
74
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 72

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

#resolvable_future ⇒ ResolvableFuture

Shortcut of #resolvable_future_on with default :io executor supplied.

Returns:

See Also:



78
79
80
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 78

def resolvable_future
  resolvable_future_on default_executor
end

#resolvable_future_on(default_executor = self.default_executor) ⇒ ResolvableFuture

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:



88
89
90
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 88

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

#resolved_event(default_executor = self.default_executor) ⇒ Event

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:



144
145
146
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 144

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

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

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

Parameters:

  • fulfilled (true, false)
  • value (Object)
  • reason (Object)
  • 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:



118
119
120
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 118

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

#schedule(intended_time, *args, &task) ⇒ Future, Event

Shortcut of #schedule_on with default :io executor supplied.

Returns:

See Also:



214
215
216
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 214

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

#schedule_on(default_executor, intended_time, *args) {|*args| ... } ⇒ Future #schedule_on(default_executor, intended_time) ⇒ Event

Creates a new event or future which is resolved in intended_time.

Overloads:

  • #schedule_on(default_executor, intended_time, *args) {|*args| ... } ⇒ Future

    If task is provided it returns a Concurrent::Promises::Future representing the result of the task.

    Parameters:

    • args (Object) —

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

    Yields:

    • (*args) —

      to the task.

    Yield Returns:

    Returns:

  • #schedule_on(default_executor, intended_time) ⇒ Event

    If no task is provided, it returns an Event

    Returns:

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.

  • intended_time (Numeric, Time) —

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



233
234
235
236
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 233

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

#zip_events(*futures_and_or_events) ⇒ Event

Shortcut of #zip_events_on with default :io executor supplied.

Returns:

See Also:



262
263
264
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 262

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

#zip_events_on(default_executor, *futures_and_or_events) ⇒ Event

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

Parameters:

Returns:



272
273
274
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 272

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

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

Shortcut of #zip_futures_on with default :io executor supplied.

Returns:

See Also:



240
241
242
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 240

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

#zip_futures_on(default_executor, *futures_and_or_events) ⇒ Future

Creates a new future which is resolved after all futures_and_or_events are resolved. Its value is an array of zipped future values. Its reason is an 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:

Returns:



254
255
256
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 254

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

#zip_futures_over(enumerable, &future_factory) ⇒ Future

Note:

Edge Features are under active development and may change frequently.

  • Deprecations are not added before incompatible changes.
  • Edge version: major is always 0, minor bump means incompatible change, patch bump means compatible change.
  • Edge features may also lack tests and documentation.
  • Features developed in concurrent-ruby-edge are expected to move to concurrent-ruby when finalised.

Shortcut of #zip_futures_over_on with default :io executor supplied.

Returns:

See Also:



72
73
74
 
# File 'lib/concurrent-ruby-edge/concurrent/edge/promises.rb', line 72

def zip_futures_over(enumerable, &future_factory)
  zip_futures_over_on default_executor, enumerable, &future_factory
end

#zip_futures_over_on(default_executor, enumerable) {|element| ... } ⇒ Future

Note:

Edge Features are under active development and may change frequently.

  • Deprecations are not added before incompatible changes.
  • Edge version: major is always 0, minor bump means incompatible change, patch bump means compatible change.
  • Edge features may also lack tests and documentation.
  • Features developed in concurrent-ruby-edge are expected to move to concurrent-ruby when finalised.

Creates new future which is resolved after all the futures created by future_factory from enumerable elements are resolved. Simplified it does: zip(*enumerable.map { |e| future e, &future_factory })

Examples:

# `#succ` calls are executed in parallel
zip_futures_over_on(:io, [1, 2], &:succ).value! # => [2, 3]

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.

  • enumerable (Enumerable)

Yields:

  • a task to be executed in future

Yield Parameters:

  • element (Object) —

    from enumerable

Yield Returns:

  • (Object) —

    a value of the future

Returns:



90
91
92
93
 
# File 'lib/concurrent-ruby-edge/concurrent/edge/promises.rb', line 90

def zip_futures_over_on(default_executor, enumerable, &future_factory)
  # ZipFuturesPromise.new_blocked_by(futures_and_or_events, default_executor).future
  zip_futures_on(default_executor, *enumerable.map { |e| future e, &future_factory })
end

#default_executor ⇒ Executor, :io, :fast 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