U:RDoc::NormalClass[iI"Promise:ETI"Concurrent::Promise;TI"Concurrent::IVar;To:RDoc::Markup::Document:@parts[o;;[Vo:RDoc::Markup::Paragraph;[I"dPromises are inspired by the JavaScript [Promises/A](http://wiki.commonjs.org/wiki/Promises/A) ;TI"Vand [Promises/A+](http://promises-aplus.github.io/promises-spec/) specifications.;To:RDoc::Markup::BlankLineo;	;[I"H> A promise represents the eventual value returned from the single ;TI""> completion of an operation.;T@o;	;[I"LPromises are similar to futures and share many of the same behaviours. ;TI"NPromises are far more robust, however. Promises can be chained in a tree ;TI"Ostructure where each promise may have zero or more children. Promises are ;TI"Ochained using the `then` method. The result of a call to `then` is always ;TI"Panother promise. Promises are resolved asynchronously (with respect to the ;TI"Omain thread) but in a strict order: parents are guaranteed to be resolved ;TI"Obefore their children, children before their younger siblings. The `then` ;TI"Omethod takes two parameters: an optional block to be executed upon parent ;TI"Qresolution and an optional callable to be executed upon parent failure. The ;TI"Oresult of each promise is passed to each of its children upon resolution. ;TI"PWhen a promise is rejected all its children will be summarily rejected and ;TI"will receive the reason.;T@o;	;[I"HPromises have several possible states: *:unscheduled*, *:pending*, ;TI"O*:processing*, *:rejected*, or *:fulfilled*. These are also aggregated as ;TI"M`#incomplete?` and `#complete?`. When a Promise is created it is set to ;TI"L*:unscheduled*. Once the `#execute` method is called the state becomes ;TI"P*:pending*. Once a job is pulled from the thread pool's queue and is given ;TI"Kto a thread for processing (often immediately upon `#post`) the state ;TI"Rbecomes *:processing*. The future will remain in this state until processing ;TI"Iis complete. A future that is in the *:unscheduled*, *:pending*, or ;TI"R*:processing* is considered `#incomplete?`. A `#complete?` Promise is either ;TI"P*:rejected*, indicating that an exception was thrown during processing, or ;TI"Q*:fulfilled*, indicating success. If a Promise is *:fulfilled* its `#value` ;TI"Pwill be updated to reflect the result of the operation. If *:rejected* the ;TI"L`reason` will be updated with a reference to the thrown exception. The ;TI"Gpredicate methods `#unscheduled?`, `#pending?`, `#rejected?`, and ;TI"Q`#fulfilled?` can be called at any time to obtain the state of the Promise, ;TI"8as can the `#state` method, which returns a symbol.;T@o;	;[I"KRetrieving the value of a promise is done through the `value` (alias: ;TI"Q`deref`) method. Obtaining the value of a promise is a potentially blocking ;TI"Qoperation. When a promise is *rejected* a call to `value` will return `nil` ;TI"Gimmediately. When a promise is *fulfilled* a call to `value` will ;TI"Qimmediately return the current value. When a promise is *pending* a call to ;TI"Q`value` will block until the promise is either *rejected* or *fulfilled*. A ;TI"N*timeout* value can be passed to `value` to limit how long the call will ;TI"Pblock. If `nil` the call will block indefinitely. If `0` the call will not ;TI"Qblock. Any other integer or float value will indicate the maximum number of ;TI"seconds to block.;T@o;	;[I",Promises run on the global thread pool.;T@o;	;[I"@!macro copy_options;T@o;	;[I"### Examples;T@o;	;[I" Start by requiring promises;T@o;	;[I"
```ruby ;TI"require 'concurrent' ;TI"```;T@o;	;[I"Then create one;T@o;	;[I"
```ruby ;TI"'p = Concurrent::Promise.execute do;To:RDoc::Markup::Verbatim;[I"  # do something
;TI"
  42
;TI"	end
;T:@format0o;	;[I"```;T@o;	;[	I"RPromises can be chained using the `then` method. The `then` method accepts a ;TI"bblock and an executor, to be executed on fulfillment, and a callable argument to be executed ;TI"Ron rejection. The result of the each promise is passed as the block argument ;TI"to chained promises.;T@o;	;[I"
```ruby ;TI"Yp = Concurrent::Promise.new{10}.then{|x| x * 2}.then{|result| result - 10 }.execute ;TI"```;T@o;	;[I"'And so on, and so on, and so on...;T@o;	;[I"
```ruby ;TI")p = Concurrent::Promise.fulfill(20).;To;;[I""then{|result| result - 10 }.
;TI"!then{|result| result * 3 }.
;TI"Fthen(executor: different_executor){|result| result % 5 }.execute
;T;0o;	;[I"```;T@o;	;[I"UThe initial state of a newly created Promise depends on the state of its parent:;To:RDoc::Markup::List:
@type:BULLET:@items[	o:RDoc::Markup::ListItem:@label0;[o;	;[I"?if parent is *unscheduled* the child will be *unscheduled*;To;;0;[o;	;[I"7if parent is *pending* the child will be *pending*;To;;0;[o;	;[I"9if parent is *fulfilled* the child will be *pending*;To;;0;[o;	;[I"\if parent is *rejected* the child will be *pending* (but will ultimately be *rejected*);T@o;	;[
I"NPromises are executed asynchronously from the main thread. By the time a ;TI"Rchild Promise finishes intialization it may be in a different state than its ;TI"Jparent (by the time a child is created its parent may have completed ;TI"Rexecution and changed state). Despite being asynchronous, however, the order ;TI"Nof execution of Promise objects in a chain (or tree) is strictly defined.;T@o;	;[I"NThere are multiple ways to create and execute a new `Promise`. Both ways ;TI" provide identical behavior:;T@o;	;[
I"
```ruby ;TI"%# create, operate, then execute ;TI"4p1 = Concurrent::Promise.new{ "Hello World!" } ;TI"p1.state #=> :unscheduled ;TI"p1.execute;T@o;	;[I"&# create and immediately execute ;TI";p2 = Concurrent::Promise.new{ "Hello World!" }.execute;T@o;	;[I"# execute during creation ;TI"8p3 = Concurrent::Promise.execute{ "Hello World!" } ;TI"```;T@o;	;[I"GOnce the `execute` method is called a `Promise` becomes `pending`:;T@o;	;[
I"
```ruby ;TI"8p = Concurrent::Promise.execute{ "Hello, world!" } ;TI"p.state    #=> :pending ;TI"p.pending? #=> true ;TI"```;T@o;	;[I"IWait a little bit, and the promise will resolve and provide a value:;T@o;	;[I"
```ruby ;TI"8p = Concurrent::Promise.execute{ "Hello, world!" } ;TI"sleep(0.1);T@o;	;[	I"!p.state      #=> :fulfilled ;TI"p.fulfilled? #=> true ;TI"&p.value      #=> "Hello, world!" ;TI"```;T@o;	;[I"KIf an exception occurs, the promise will be rejected and will provide ;TI" a reason for the rejection:;T@o;	;[I"
```ruby ;TI"Xp = Concurrent::Promise.execute{ raise StandardError.new("Here comes the Boom!") } ;TI"sleep(0.1);T@o;	;[	I"p.state     #=> :rejected ;TI"p.rejected? #=> true ;TI">p.reason    #=> "#<StandardError: Here comes the Boom!>" ;TI"```;T@o;	;[I"#### Rejection;T@o;	;[I"KWhen a promise is rejected all its children will be rejected and will ;TI"Hreceive the rejection `reason` as the rejection callable parameter:;T@o;	;[I"
```ruby ;TI"Ip = Concurrent::Promise.execute { Thread.pass; raise StandardError };T@o;	;[I"#c1 = p.then(-> reason { 42 }) ;TI"-c2 = p.then(-> reason { raise 'Boom!' });T@o;	;[
I"#c1.wait.state  #=> :fulfilled ;TI"c1.value       #=> 45 ;TI""c2.wait.state  #=> :rejected ;TI"/c2.reason      #=> #<RuntimeError: Boom!> ;TI"```;T@o;	;[I"NOnce a promise is rejected it will continue to accept children that will ;TI"Jreceive immediately rejection (they will be executed asynchronously).;T@o;	;[I"#### Aliases;T@o;	;[I"KThe `then` method is the most generic alias: it accepts a block to be ;TI"Pexecuted upon parent fulfillment and a callable to be executed upon parent ;TI"Orejection. At least one of them should be passed. The default block is `{ ;TI"K|result| result }` that fulfills the child with the parent value. The ;TI"Qdefault callable is `{ |reason| raise reason }` that rejects the child with ;TI"the parent reason.;T@o;
;;;[o;;0;[o;	;[I"H`on_success { |result| ... }` is the same as `then {|result| ... }`;To;;0;[o;	;[I"P`rescue { |reason| ... }` is the same as `then(Proc.new { |reason| ... } )`;To;;0;[o;	;[I"2`rescue` is aliased by `catch` and `on_error`;T:
@fileI".lib/concurrent-ruby/concurrent/promise.rb;T:0@omit_headings_from_table_of_contents_below0;0;0[[[[[I"
class;T[[:public[[I"	all?;TI".lib/concurrent-ruby/concurrent/promise.rb;T[I"	any?;T@
[I"execute;T@
[I"fulfill;T@
[I"new;T@
[I"reject;T@
[I"zip;T@
[:protected[[I"aggregate;T@
[:private[[I"
instance;T[[;[[I"
catch;T@
[I"execute;T@
[I"	fail;T@
[I"
flat_map;T@
[I"
on_error;T@
[I"on_success;T@
[I"rescue;T@
[I"set;T@
[I"	then;T@
[I"zip;T@
[;[[I"
complete;T@
[I"notify_child;T@
[I"ns_initialize;T@
[I"on_fulfill;T@
[I"on_reject;T@
[I"realize;T@
[I"set_pending;T@
[I"set_state!;T@
[I"synchronized_set_state!;T@
[;[[[U:RDoc::Context::Section[i0o;;[;0;0[@	
I"Concurrent;TcRDoc::NormalModule