Merge pull request #310 from jboner/wip-executor-patriknw

PinnedDispatcher config and docs for dispatcher executor.

akka-docs/scala/code/akka/docs/dispatcher/DispatcherDocSpec.scala

@@ -20,6 +20,27 @@ object DispatcherDocSpec {
   val config = """
     //#my-dispatcher-config
     my-dispatcher {
+      # Dispatcher is the name of the event-based dispatcher
+      type = Dispatcher
+      # What kind of ExecutionService to use
+      executor = "fork-join-executor"
+      # Configuration for the fork join pool
+      fork-join-executor {
+        # Min number of threads to cap factor-based parallelism number to
+        parallelism-min = 2
+        # Parallelism (threads) ... ceil(available processors * factor)
+        parallelism-factor = 2.0
+        # Max number of threads to cap factor-based parallelism number to
+        parallelism-max = 10
+      }
+      # Throughput defines the number of messages that are processed in a batch before the
+      # thread is returned to the pool. Set to 1 for as fair as possible.
+      throughput = 100
+    }
+    //#my-dispatcher-config
+
+    //#my-thread-pool-dispatcher-config
+    my-thread-pool-dispatcher {
       # Dispatcher is the name of the event-based dispatcher
       type = Dispatcher
       # What kind of ExecutionService to use
@@ -37,7 +58,14 @@ object DispatcherDocSpec {
       # thread is returned to the pool. Set to 1 for as fair as possible.
       throughput = 100
     }
-    //#my-dispatcher-config
+    //#my-thread-pool-dispatcher-config
+
+    //#my-pinned-dispatcher-config
+    my-pinned-dispatcher {
+      executor = "thread-pool-executor"
+      type = PinnedDispatcher
+    }
+    //#my-pinned-dispatcher-config
 
     //#my-bounded-config
     my-dispatcher-bounded-queue {

akka-docs/scala/dispatchers.rst

@@ -54,6 +54,17 @@ Default values are taken from ``default-dispatcher``, i.e. all options doesn't n
 :ref:`configuration` for the default values of the ``default-dispatcher``. You can also override
 the values for the ``default-dispatcher`` in your configuration.
 
+There are two different executor services:
+
+* executor = "fork-join-executor", ``ExecutorService`` based on ForkJoinPool (jsr166y). This is used by default for
+  ``default-dispatcher``.
+* executor = "thread-pool-executor", ``ExecutorService`` based on ``java.util.concurrent.ThreadPoolExecutor``.
+
+Note that the pool size is configured differently for the two executor services. The configuration above
+is an example for ``fork-join-executor``. Below is an example for ``thread-pool-executor``:
+
+.. includecode:: code/akka/docs/dispatcher/DispatcherDocSpec.scala#my-thread-pool-dispatcher-config
+
 Let's now walk through the different dispatchers in more detail.
 
 Thread-based
@@ -66,9 +77,11 @@ has worse performance and scalability than the event-based dispatcher but works
 a low frequency of messages and are allowed to go off and do their own thing for a longer period of time. Another advantage with
 this dispatcher is that Actors do not block threads for each other.
 
-The ``PinnedDispatcher`` can't be configured, but is created and associated with an actor like this:
+The ``PinnedDispatcher`` is configured like this:
 
-.. includecode:: code/akka/docs/dispatcher/DispatcherDocSpec.scala#defining-pinned-dispatcher
+.. includecode:: code/akka/docs/dispatcher/DispatcherDocSpec.scala#my-pinned-dispatcher-config
+
+Note that it must be used with ``executor = "thread-pool-executor"``.
 
 Event-based
 ^^^^^^^^^^^