Module: Concurrent::Promises::FactoryMethods

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

Overview

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

Defined Under Namespace

Modules: Configuration

Instance Method Summary collapse

Methods included from Configuration

#default_executor

Instance Method Details

#any_event(*futures_and_or_events) ⇒ Future

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

Returns:

See Also:



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

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

Returns:



327
328
329
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 327

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:



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

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

Returns:



311
312
313
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 311

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:



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

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

Returns:



292
293
294
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 292

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:



188
189
190
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 188

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

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

Creates 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 @yeild 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.



205
206
207
208
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 205

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

  • value (Object)

Returns:



125
126
127
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 125

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:



92
93
94
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 92

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

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

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:

Returns:



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

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


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

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

  • reason (Object)

Returns:



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

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:



61
62
63
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 61

def resolvable_event
  resolvable_event_on default_executor
end

#resolvable_event_on(default_executor = self.default_executor) ⇒ ResolvableEvent

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:



70
71
72
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 70

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:



76
77
78
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 76

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:



86
87
88
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 86

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:



142
143
144
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 142

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 resolved future with will be either fulfilled with the given value or rejection 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:



116
117
118
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 116

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:



212
213
214
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 212

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 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 @yeild 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`.



231
232
233
234
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 231

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:



260
261
262
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 260

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 new event which is resolved after all futures_and_or_events are resolved. (Future is resolved when fulfilled or rejected.)

Parameters:

Returns:



270
271
272
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 270

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:



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

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

Returns:



252
253
254
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 252

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