123456789_123456789_123456789_123456789_123456789_

Module: Concurrent::Promises::FactoryMethods

Relationships & Source Files
Namespace Children
Modules:
Configuration, OldChannelIntegration
Extension / Inclusion / Inheritance Descendants
Extended In:
Promises
Included In:
Throttle
Super Chains via Extension / Inclusion / Inheritance
Class Chain:
ReInclude, self
Instance Chain:
self, OldChannelIntegration, Configuration
Defined in: lib/concurrent-ruby/concurrent/promises.rb,
lib/concurrent-ruby-edge/concurrent/edge/old_channel_integration.rb,
lib/concurrent-ruby-edge/concurrent/edge/promises.rb

Overview

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

Class Method Summary

ReInclude - Extended

extended, include, included

Instance Method Summary

OldChannelIntegration - Included

#select

only proof of concept.

Configuration - Included

#default_executor

Instance Method Details

#any(*futures_and_or_events)

Alias for #any_resolved_future.

[ GitHub ] 

  


# File 'lib/concurrent-ruby/concurrent/promises.rb', line 282



alias_method :any, :any_resolved_future


  








  

    #any_event(*futures_and_or_events)  ⇒ Event 
  



  

    

Shortcut of #any_event_on with default :io executor supplied.


  





    
See Also:

  



  [ GitHub ]


  

  


# 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 Concurrent::AbstractEventFuture#touch, leaving delayed futures un-executed if they are not required any more.


  





  
Parameters:





  [ GitHub ]


  

  


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


  





    
See Also:

  



  [ GitHub ]


  

  


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





  [ GitHub ]


  

  


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


  





    
See Also:

  



  [ GitHub ]


  

  


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





  [ GitHub ]


  

  


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


  





    
See Also:

  



  [ GitHub ]


  

  


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

    
  
    • 





  [ GitHub ]


  

  


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





  [ GitHub ]


  

  


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


  





    
See Also:

  



  [ GitHub ]


  

  


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





  [ GitHub ]


  

  


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


  





  
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.
    

    
  
    • 


  
See Also:

  
    
      
  • resolved_event, fulfilled_future
    • 
      




  [ GitHub ]


  

  


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





  [ GitHub ]


  

  


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


  





    
See Also:

  



  [ GitHub ]


  

  


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

    
  
    • 





  [ GitHub ]


  

  


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


  





    
See Also:

  



  [ GitHub ]


  

  


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

    
  
    • 





  [ GitHub ]


  

  


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

    
  
    • 





  [ GitHub ]


  

  


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

    
  
    • 





  [ GitHub ]


  

  


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


  





    
See Also:

  



  [ GitHub ]


  

  


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


  





  
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.
    

    
  
    • 





  [ GitHub ]


  

  


# 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(*futures_and_or_events)  
  



  

    

Alias for #zip_futures.


  



  [ GitHub ]


  

  


# File 'lib/concurrent-ruby/concurrent/promises.rb', line 258



alias_method :zip, :zip_futures


  








  

    #zip_events(*futures_and_or_events)  ⇒ Event 
  



  

    

Shortcut of #zip_events_on with default :io executor supplied.


  





    
See Also:

  



  [ GitHub ]


  

  


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





  [ GitHub ]


  

  


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


  





    
See Also:

  



  [ GitHub ]


  

  


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





  [ GitHub ]


  

  


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


  





    
See Also:

  



  [ GitHub ]


  

  


# 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
    

    
  
    • 





  [ GitHub ]


  

  


# 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