Merge pull request #524 from ruby-concurrency/better-thread-pool-docs

Better future/promise documentation.

Author: jdantonio

doc/future.md

@@ -1,4 +1,4 @@
-`Future` is inspired by [Clojure's](http://clojure.org/) [future](http://clojuredocs.org/clojure_core/clojure.core/future) function. A future represents a promise to complete an action at some time in the future. The action is atomic and permanent. The idea behind a future is to send an operation for asynchronous completion, do other stuff, then return and retrieve the result of the async operation at a later time. `Future`s run on the global thread pool. 
+`Future` is inspired by [Clojure's](http://clojure.org/) [future](http://clojuredocs.org/clojure_core/clojure.core/future) function. A future represents a promise to complete an action at some time in the future. The action is atomic and permanent. The idea behind a future is to send an operation for asynchronous completion, do other stuff, then return and retrieve the result of the async operation at a later time. `Future`s run on the global thread pool.
 
 ```cucumber
 Feature:
@@ -7,19 +7,19 @@ Feature:
   So I can perform other tasks without waiting
 ```
 
-`Future`s have four possible states: *:unscheduled*, *:pending*, *:rejected*, and *:fulfilled*. When a `Future` is created it is set to *:unscheduled*. Once the `#execute` method is called the state becomes *:pending* and will remain in that state until processing is complete. A completed `Future` is either *:rejected*, indicating that an exception was thrown during processing, or *:fulfilled*, indicating success. If a `Future` 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 `Future`, as can the `#state` method, which returns a symbol. 
+`Future`s have several possible states: *:unscheduled*, *:pending*, *:processing*, *:rejected*, or *:fulfilled*. These are also aggregated as `#incomplete?` and `#complete?`. When a `Future` 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?` `Future` is either *:rejected*, indicating that an exception was thrown during processing, or *:fulfilled*, indicating success. If a `Future` 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 `Future`, as can the `#state` method, which returns a symbol.
 
 Retrieving the value of a `Future` is done through the `#value` (alias: `#deref`) method. Obtaining the value of a `Future` is a potentially blocking operation. When a `Future` is *:rejected* a call to `#value` will return `nil` immediately. When a `Future` is *:fulfilled* a call to `#value` will immediately return the current value. When a `Future` is *:pending* a call to `#value` will block until the `Future` 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.
 
-The constructor can also be given zero or more processing options. Currently the only supported options are those recognized by the [Dereferenceable](Dereferenceable) module. 
+The constructor can also be given zero or more processing options. Currently the only supported options are those recognized by the [Dereferenceable](Dereferenceable) module.
 
-The `Future` class also includes the behavior of the Ruby standard library [Observable](http://ruby-doc.org/stdlib-2.0/libdoc/observer/rdoc/Observable.html) module, but does so in a thread-safe way. On fulfillment or rejection all observers will be notified according to the normal `Observable` behavior. The observer callback function will be called with three parameters: the `Time` of fulfillment/rejection, the final `value`, and the final `reason`. Observers added after fulfillment/rejection will still be notified as normal. The notification will occur on the global thread pool. 
+The `Future` class also includes the behavior of the Ruby standard library [Observable](http://ruby-doc.org/stdlib-2.0/libdoc/observer/rdoc/Observable.html) module, but does so in a thread-safe way. On fulfillment or rejection all observers will be notified according to the normal `Observable` behavior. The observer callback function will be called with three parameters: the `Time` of fulfillment/rejection, the final `value`, and the final `reason`. Observers added after fulfillment/rejection will still be notified as normal. The notification will occur on the global thread pool.
 
 ### Examples
 
 A fulfilled example:
 
-```ruby    
+```ruby
 require 'concurrent'
 require 'thread'   # for Queue
 require 'open-uri' # for open(uri)
@@ -57,7 +57,7 @@ count.pending? #=> true
 
 count.value #=> nil (after blocking)
 count.rejected? #=> true
-count.reason #=> #<StandardError: Boom!> 
+count.reason #=> #<StandardError: Boom!>
 ```
 
 

lib/concurrent/promise.rb

@@ -28,21 +28,22 @@ module Concurrent
   # 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.
+  # 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