Renamed new Promise methods to all?, any?, none?, and on? (added question marks).

Author: jdantonio

lib/concurrent/promise.rb

@@ -7,15 +7,41 @@ module Concurrent
 
   PromiseExecutionError = Class.new(StandardError)
 
-  # Promises are inspired by the JavaScript [Promises/A](http://wiki.commonjs.org/wiki/Promises/A) and [Promises/A+](http://promises-aplus.github.io/promises-spec/) specifications.
+  # Promises are inspired by the JavaScript [Promises/A](http://wiki.commonjs.org/wiki/Promises/A)
+  # and [Promises/A+](http://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 four possible states: *unscheduled*, *pending*, *rejected*, and *fulfilled*. A Promise created using `.new` will be *unscheduled*. It is scheduled by calling the `execute` method. Upon execution the Promise and all its children will be set to *pending*. When a promise is *pending* it will remain in that state until processing is complete. A completed Promise is either *rejected*, indicating that an exception was thrown during processing, or *fulfilled*, indicating it succeeded. 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. A Promise created using `.execute` will be *pending*, a Promise created using `.fulfill(value)` will be *fulfilled* with the given value and a Promise created using `.reject(reason)` will be *rejected* with the given reason. 
-  # 
-  # 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 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 four possible states: *unscheduled*, *pending*, *rejected*, and *fulfilled*. A
+  # Promise created using `.new` will be *unscheduled*. It is scheduled by calling the `execute`
+  # method. Upon execution the Promise and all its children will be set to *pending*. When a promise
+  # is *pending* it will remain in that state until processing is complete. A completed Promise is
+  # either *rejected*, indicating that an exception was thrown during processing, or *fulfilled*,
+  # indicating it succeeded. 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. A Promise created using `.execute` will be *pending*, a Promise
+  # created using `.fulfill(value)` will be *fulfilled* with the given value and a Promise created
+  # using `.reject(reason)` will be *rejected* with the given reason. 
+  # 
+  # 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.
   # 
@@ -30,13 +56,15 @@ module Concurrent
   # Then create one
   # 
   # ```ruby
-  # p = Promise.execute do
+  # p = Concurrent::Promise.execute do
   #       # do something
   #       42
   #     end
   # ```
   # 
-  # Promises can be chained using the `then` method. The `then` method accepts a block, 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. 
+  # Promises can be chained using the `then` method. The `then` method accepts a block, 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
@@ -57,7 +85,10 @@ module Concurrent
   # - if parent is *fulfilled* the child will be *pending*
   # - if parent is *rejected* the child will be *pending* (but will ultimately be *rejected*)
   # 
-  # Promises are executed asynchronously from the main thread. By the time a child Promise finishes initialization it may be in a different state that 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. 
+  # Promises are executed asynchronously from the main thread. By the time a child Promise finishes 
+  # nitialization it may be in a different state that 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:
   # 
@@ -107,7 +138,8 @@ module Concurrent
   # 
   # #### Rejection
   # 
-  # When a promise is rejected all its children will be rejected and will receive the rejection `reason` as the rejection callable parameter:
+  # 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 } ]
@@ -121,11 +153,15 @@ module Concurrent
   # c2.state  #=> :rejected
   # ```
   # 
-  # Once a promise is rejected it will continue to accept children that will receive immediately rejection (they will be executed asynchronously).
+  # 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. 
+  # 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. 
   # 
   # - `on_success { |result| ... }` is the same as `then {|result| ... }`
   # - `rescue { |reason| ... }` is the same as `then(Proc.new { |reason| ... } )`
@@ -292,13 +328,11 @@ def zip(*others)
       self.class.zip(self, *others)
     end
 
-    # Aggregate a collection of zero or more promises under a composite promise,
-    # execute the aggregated promises and collect them into a standard Ruby array,
-    # call the given Ruby `Ennnumerable` predicate (such as `any?`, `all?`, `none?`,
-    # or `one?`) on the collection checking for the success or failure of each,
-    # then executing the composite's `#then` handlers if the predicate returns
-    # `true` or executing the composite's `#rescue` handlers if the predicate
-    # returns false.
+    # Aggregates a collection of promises and executes the `then` condition
+    # if all aggregated promises succeed. Executes the `rescue` handler with
+    # a `Concurrent::PromiseExecutionError` if any of the aggregated promises
+    # fail. Upon execution will execute any of the aggregate promises that
+    # were not already executed.
     #
     # @!macro [attach] promise_self_aggregate
     #
@@ -314,28 +348,7 @@ def zip(*others)
     #   @param [Array] promises Zero or more promises to aggregate
     #   @return [Promise] an unscheduled (not executed) promise that aggregates
     #     the promises given as arguments
-    def self.aggregate(method, *promises)
-      composite = Promise.new do
-        completed = promises.collect do |promise|
-          promise.execute if promise.unscheduled?
-          promise.wait
-          promise
-        end
-        unless completed.empty? || completed.send(method){|promise| promise.fulfilled? }
-          raise PromiseExecutionError
-        end
-      end
-      composite
-    end
-
-    # Aggregates a collection of promises and executes the `then` condition
-    # if all aggregated promises succeed. Executes the `rescue` handler with
-    # a `Concurrent::PromiseExecutionError` if any of the aggregated promises
-    # fail. Upon execution will execute any of the aggregate promises that
-    # were not already executed.
-    #
-    # @!macro promise_self_aggregate
-    def self.all(*promises)
+    def self.all?(*promises)
       aggregate(:all?, *promises)
     end
 
@@ -346,7 +359,7 @@ def self.all(*promises)
     # were not already executed.
     #
     # @!macro promise_self_aggregate
-    def self.any(*promises)
+    def self.any?(*promises)
       aggregate(:any?, *promises)
     end
 
@@ -357,7 +370,7 @@ def self.any(*promises)
     # were not already executed.
     #
     # @!macro promise_self_aggregate
-    def self.none(*promises)
+    def self.none?(*promises)
       aggregate(:none?, *promises)
     end
 
@@ -368,12 +381,35 @@ def self.none(*promises)
     # the aggregate promises that were not already executed.
     #
     # @!macro promise_self_aggregate
-    def self.one(*promises)
+    def self.one?(*promises)
       aggregate(:one?, *promises)
     end
 
     protected
 
+    # Aggregate a collection of zero or more promises under a composite promise,
+    # execute the aggregated promises and collect them into a standard Ruby array,
+    # call the given Ruby `Ennnumerable` predicate (such as `any?`, `all?`, `none?`,
+    # or `one?`) on the collection checking for the success or failure of each,
+    # then executing the composite's `#then` handlers if the predicate returns
+    # `true` or executing the composite's `#rescue` handlers if the predicate
+    # returns false.
+    #
+    # @!macro promise_self_aggregate
+    def self.aggregate(method, *promises)
+      composite = Promise.new do
+        completed = promises.collect do |promise|
+          promise.execute if promise.unscheduled?
+          promise.wait
+          promise
+        end
+        unless completed.empty? || completed.send(method){|promise| promise.fulfilled? }
+          raise PromiseExecutionError
+        end
+      end
+      composite
+    end
+
     def set_pending
       mutex.synchronize do
         @state = :pending