class Concurrent::Promise

Promises are inspired by the JavaScript [Promises/A](wiki.commonjs.org/wiki/Promises/A) and [Promises/A+](promises-aplus.github.io/promises-spec/) specifications.

> A promise represents the eventual value returned from the single > completion of an operation.

Promises are similar to futures and share many of the same behaviours. Promises are far more robust, however. Promises can be chained in a tree structure where each promise may have zero or more children. Promises are chained using the ‘then` method. The result of a call to `then` is always another promise. Promises are resolved asynchronously (with respect to the main thread) but in a strict order: parents are guaranteed to be resolved before their children, children before their younger siblings. The `then` method takes two parameters: an optional block to be executed upon parent resolution and an optional callable to be executed upon parent failure. The result of each promise is passed to each of its children upon resolution. When a promise is rejected all its children will be summarily rejected and will receive the reason.

Promises have several possible states: :unscheduled, :pending, :processing, :rejected, or :fulfilled. These are also aggregated as ‘#incomplete?` and `#complete?`. When a Promise is created it is set to :unscheduled. Once the `#execute` method is called the state becomes :pending. Once a job is pulled from the thread pool’s queue and is given to a thread for processing (often immediately upon ‘#post`) the state becomes :processing. The future will remain in this state until processing is complete. A future that is in the :unscheduled, :pending, or :processing is considered `#incomplete?`. A `#complete?` Promise is either :rejected, indicating that an exception was thrown during processing, or :fulfilled, indicating success. If a Promise is :fulfilled its `#value` will be updated to reflect the result of the operation. If :rejected the `reason` will be updated with a reference to the thrown exception. The predicate methods `#unscheduled?`, `#pending?`, `#rejected?`, and `#fulfilled?` can be called at any time to obtain the state of the Promise, as can the `#state` method, which returns a symbol.

Retrieving the value of a promise is done through the ‘value` (alias: `deref`) method. Obtaining the value of a promise is a potentially blocking operation. When a promise is rejected a call to `value` will return `nil` immediately. When a promise is fulfilled a call to `value` will immediately return the current value. When a promise is pending a call to `value` will block until the promise is either rejected or fulfilled. A timeout value can be passed to `value` to limit how long the call will block. If `nil` the call will block indefinitely. If `0` the call will not block. Any other integer or float value will indicate the maximum number of seconds to block.

Promises run on the global thread pool.

@!macro copy_options

### Examples

Start by requiring promises

“‘ruby require ’concurrent’ “‘

Then create one

“‘ruby p = Concurrent::Promise.execute do

  # do something
  42
end

“‘

Promises can be chained using the ‘then` method. The `then` method accepts a block and an executor, to be executed on fulfillment, and a callable argument to be executed on rejection. The result of the each promise is passed as the block argument to chained promises.

“‘ruby p = Concurrent::Promise.new{10}.then{|x| x * 2}.then{|result| result - 10 }.execute “`

And so on, and so on, and so on…

“‘ruby p = Concurrent::Promise.fulfill(20).

then{|result| result - 10 }.
then{|result| result * 3 }.
then(executor: different_executor){|result| result % 5 }.execute

“‘

The initial state of a newly created Promise depends on the state of its parent:

Promises are executed asynchronously from the main thread. By the time a child Promise finishes intialization it may be in a different state than its parent (by the time a child is created its parent may have completed execution and changed state). Despite being asynchronous, however, the order of execution of Promise objects in a chain (or tree) is strictly defined.

There are multiple ways to create and execute a new ‘Promise`. Both ways provide identical behavior:

“‘ruby # create, operate, then execute p1 = Concurrent::Promise.new{ “Hello World!” } p1.state #=> :unscheduled p1.execute

# create and immediately execute p2 = Concurrent::Promise.new{ “Hello World!” }.execute

# execute during creation p3 = Concurrent::Promise.execute{ “Hello World!” } “‘

Once the ‘execute` method is called a `Promise` becomes `pending`:

“‘ruby p = Concurrent::Promise.execute{ “Hello, world!” } p.state #=> :pending p.pending? #=> true “`

Wait a little bit, and the promise will resolve and provide a value:

“‘ruby p = Concurrent::Promise.execute{ “Hello, world!” } sleep(0.1)

p.state #=> :fulfilled p.fulfilled? #=> true p.value #=> “Hello, world!” “‘

If an exception occurs, the promise will be rejected and will provide a reason for the rejection:

“‘ruby p = Concurrent::Promise.execute{ raise StandardError.new(“Here comes the Boom!”) } sleep(0.1)

p.state #=> :rejected p.rejected? #=> true p.reason #=> “#<StandardError: Here comes the Boom!>” “‘

#### Rejection

When a promise is rejected all its children will be rejected and will receive the rejection ‘reason` as the rejection callable parameter:

“‘ruby p = Concurrent::Promise.execute { Thread.pass; raise StandardError }

c1 = p.then(-> reason { 42 }) c2 = p.then(-> reason { raise ‘Boom!’ })

c1.wait.state #=> :fulfilled c1.value #=> 45 c2.wait.state #=> :rejected c2.reason #=>

Once a promise is rejected it will continue to accept children that will receive immediately rejection (they will be executed asynchronously).

#### Aliases

The ‘then` method is the most generic alias: it accepts a block to be executed upon parent fulfillment and a callable to be executed upon parent rejection. At least one of them should be passed. The default block is `{ |result| result }` that fulfills the child with the parent value. The default callable is `{ |reason| raise reason }` that rejects the child with the parent reason.