Merge pull request #488 from bappelt/update_threadpool_documentation

Update thread pool documentation

Author: jdantonio

doc/thread_pools.md

@@ -48,7 +48,11 @@ If you'd like to configure a maximum number of threads, you can use the more gen
 
 A [ThreadPoolExecutor](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/ThreadPoolExecutor.html) is a general-purpose thread pool that can be configured to have various behaviors.
 
-The `CachedThreadPool` and `FixedThreadPool` are simply `ThreadPoolExecutor`s with certain configuration pre-determined. For instance, to create a `ThreadPoolExecutor` that works just like a `FixedThreadPool.new 5`, you could:
+A `ThreadPoolExecutor` will automatically adjust the pool size according to the bounds set by `min-threads` and `max-threads`. 
+When a new task is submitted and fewer than `min-threads` threads are running, a new thread is created to handle the request, even if other worker threads are idle. 
+If there are more than `min-threads` but less than `max-threads` threads running, a new thread will be created only if the queue is full.
+
+The `CachedThreadPool` and `FixedThreadPool` are simply `ThreadPoolExecutors` with certain configuration pre-determined. For instance, to create a `ThreadPoolExecutor` that works just like a `FixedThreadPool.new 5`, you could:
 
 ~~~ruby
 pool = Concurrent::ThreadPoolExecutor.new(
@@ -58,12 +62,14 @@ pool = Concurrent::ThreadPoolExecutor.new(
 )
 ~~~
 
-If you want to provide a maximum queue size, you may also consider the `fallback_policy` -- what will happen if work is posted to a pool when the queue of waiting work has reached the maximum size? Available policies:
+If you wants to provide a maximum queue size, you may also consider the `fallback_policy` which defines what will happen if work is posted to a pool when the queue of waiting work has reached the maximum size and no new threads can be created. Available policies:
 
 * abort: Raise a `Concurrent::RejectedExecutionError` exception and discard the task. (default policy)
 * discard: Silently discard the task and return nil as the task result.
 * caller_runs: The work will be executed in the thread of the caller, instead of being given to another thread in the pool.
 
+For example:
+
 ~~~ruby
 pool = Concurrent::ThreadPoolExecutor.new(
    min_threads: 5,
@@ -73,24 +79,15 @@ pool = Concurrent::ThreadPoolExecutor.new(
 )
 ~~~
 
-Similarly, you can create something similar to a `CachedThreadPool`, but with a maximum number of threads. With an unbounded queue:
-
-~~~ruby
-pool = Concurrent::ThreadPoolExecutor.new(
-   min_threads: 3, # create 3 threads at startup
-   max_threads: 10, # create at most 10 threads
-   max_queue: 0, # unbounded queue of work waiting for an available thread
-)
-~~~
-
-Or, with a variable number of threads like a CachedThreadPool, but with a bounded queue and a fallback_policy:
+You can create something similar to a `CachedThreadPool`, but with a maximum number of threads and a bounded queue.
+A new thread will be created for the first 3 tasks submitted, and then, once the queue is full, up to an additional 7 threads (10 total) will be created.
+If all 10 threads are busy and 100 tasks are already queued, additional tasks will be rejected.
 
 ~~~ruby
 pool = Concurrent::ThreadPoolExecutor.new(
-   min_threads: 3, # create 3 threads at startup
+   min_threads: 3, # create up to 3 threads before queueing tasks
    max_threads: 10, # create at most 10 threads
-   max_queue: 100, # at most 100 jobs waiting in the queue,
-   fallback_policy: :abort
+   max_queue: 100, # at most 100 jobs waiting in the queue
 )
 ~~~
 

lib/concurrent/executor/fixed_thread_pool.rb

@@ -116,8 +116,8 @@ module Concurrent
   #
   #   * `idletime`: The number of seconds that a thread may be idle before being reclaimed.
   #   * `max_queue`: The maximum number of tasks that may be waiting in the work queue at
-  #     any one time. When the queue size reaches `max_queue` subsequent tasks will be
-  #     rejected in accordance with the configured `fallback_policy`.
+  #     any one time. When the queue size reaches `max_queue` and no new threads can be created,
+  #     subsequent tasks will be rejected in accordance with the configured `fallback_policy`.
   #   * `auto_terminate`: When true (default) an `at_exit` handler will be registered which
   #     will stop the thread pool when the application exits. See below for more information
   #     on shutting down thread pools.
@@ -171,8 +171,8 @@ module Concurrent
 
   # @!macro [attach] fixed_thread_pool
   #
-  #   A thread pool with a set number of threads. The number of threads in the pool
-  #   is set on construction and remains constant. When all threads are busy new
+  #   A thread pool that reuses a fixed number of threads operating off an unbounded queue.
+  #   At any point, at most `num_threads` will be active processing tasks. When all threads are busy new
   #   tasks `#post` to the thread pool are enqueued until a thread becomes available.
   #   Should a thread crash for any reason the thread will immediately be removed
   #   from the pool and replaced.

lib/concurrent/executor/thread_pool_executor.rb

@@ -18,16 +18,22 @@ module Concurrent
   # @!macro [attach] thread_pool_executor
   #
   #   An abstraction composed of one or more threads and a task queue. Tasks
-  #   (blocks or `proc` objects) are submit to the pool and added to the queue.
+  #   (blocks or `proc` objects) are submitted to the pool and added to the queue.
   #   The threads in the pool remove the tasks and execute them in the order
-  #   they were received. When there are more tasks queued than there are
-  #   threads to execute them the pool will create new threads, up to the
-  #   configured maximum. Similarly, threads that are idle for too long will
-  #   be garbage collected, down to the configured minimum options. Should a
-  #   thread crash it, too, will be garbage collected.
+  #   they were received.
+  #
+  #   A `ThreadPoolExecutor` will automatically adjust the pool size according
+  #   to the bounds set by `min-threads` and `max-threads`. When a new task is
+  #   submitted and fewer than `min-threads` threads are running, a new thread
+  #   is created to handle the request, even if other worker threads are idle.
+  #   If there are more than `min-threads` but less than `max-threads` threads
+  #   running, a new thread will be created only if the queue is full.
+  #
+  #   Threads that are idle for too long will be garbage collected, down to the
+  #   configured minimum options. Should a thread crash it, too, will be garbage collected.
   #
   #   `ThreadPoolExecutor` is based on the Java class of the same name. From
-  #   the official Java documentationa;
+  #   the official Java documentation;
   #
   #   > Thread pools address two different problems: they usually provide
   #   > improved performance when executing large numbers of asynchronous tasks,
@@ -57,8 +63,8 @@ class ThreadPoolExecutor < ThreadPoolExecutorImplementation
     #  
     #   @option opts [Integer] :max_threads (DEFAULT_MAX_POOL_SIZE) the maximum
     #     number of threads to be created
-    #   @option opts [Integer] :min_threads (DEFAULT_MIN_POOL_SIZE) the minimum
-    #     number of threads to be retained
+    #   @option opts [Integer] :min_threads (DEFAULT_MIN_POOL_SIZE) When a new task is submitted
+    #      and fewer than `min_threads` are running, a new thread is created
     #   @option opts [Integer] :idletime (DEFAULT_THREAD_IDLETIMEOUT) the maximum
     #     number of seconds a thread may be idle before being reclaimed
     #   @option opts [Integer] :max_queue (DEFAULT_MAX_QUEUE_SIZE) the maximum