Better executor documentation.

Author: jdantonio

lib/concurrent/executor/immediate_executor.rb

@@ -6,6 +6,13 @@ module Concurrent
   # An executor service which runs all operations on the current thread,
   # blocking as necessary. Operations are performed in the order they are
   # received and no two operations can be performed simultaneously.
+  #
+  # This executor service exists mainly for testing an debugging. When used
+  # it immediately runs every `#post` operation on the current thread, blocking
+  # that thread until the operation is complete. This can be very beneficial
+  # during testing because it makes all operations deterministic.
+  #
+  # @note Intended for use primarily in testing and debugging.
   class ImmediateExecutor
     include SerialExecutor
 

lib/concurrent/executor/per_thread_executor.rb

@@ -5,8 +5,18 @@ module Concurrent
 
   # An executor service in which every operation spawns a new,
   # independently operating thread.
+  #
+  # This is perhaps the most inefficient executor service in this
+  # library. It exists mainly for testing an debugging. Thread creation
+  # and management is expensive in Ruby and this executor performs no
+  # resource pooling. This can be very beneficial during testing and
+  # debugging because it decouples the using code from the underlying
+  # executor implementation. In production this executor will likely
+  # lead to suboptimal performance.
+  #
+  # @note Intended for use primarily in testing and debugging.
   class PerThreadExecutor
-    include SerialExecutor
+    include Executor
 
     # Creates a new executor
     def initialize