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

PinnedDispatcher config and docs for dispatcher executor.

akka-actor-tests/src/test/scala/akka/actor/SupervisorMiscSpec.scala

@@ -14,6 +14,7 @@ import akka.util.duration._
 object SupervisorMiscSpec {
   val config = """
     pinned-dispatcher {
+      executor = thread-pool-executor
       type = PinnedDispatcher
     }
     test-dispatcher {

akka-actor-tests/src/test/scala/akka/actor/dispatch/ActorModelSpec.scala

@@ -435,6 +435,7 @@ object DispatcherModelSpec {
   val config = {
     """
       boss {
+        executor = thread-pool-executor
         type = PinnedDispatcher
       }
     """ +
@@ -506,6 +507,7 @@ object BalancingDispatcherModelSpec {
   val config = {
     """
       boss {
+        executor = thread-pool-executor
         type = PinnedDispatcher
       }
     """ +

akka-actor-tests/src/test/scala/akka/actor/dispatch/PinnedActorSpec.scala

@@ -12,6 +12,7 @@ import akka.pattern.ask
 object PinnedActorSpec {
   val config = """
     pinned-dispatcher {
+      executor = thread-pool-executor
       type = PinnedDispatcher
     }
     """

akka-actor-tests/src/test/scala/akka/testkit/CallingThreadDispatcherModelSpec.scala

@@ -16,6 +16,7 @@ object CallingThreadDispatcherModelSpec {
   val config = {
     """
       boss {
+        executor = thread-pool-executor
         type = PinnedDispatcher
       }
     """ +

akka-actor/src/main/resources/reference.conf

@@ -156,7 +156,8 @@ akka {
       # the same type), PinnedDispatcher, or a FQCN to a class inheriting
       # MessageDispatcherConfigurator with a constructor with
       # com.typesafe.config.Config parameter and akka.dispatch.DispatcherPrerequisites
-      # parameters
+      # parameters.
+      # PinnedDispatcher must be used toghether with executor=thread-pool-executor.
       type = "Dispatcher"
 
       # Which kind of ExecutorService to use for this dispatcher

akka-actor/src/main/scala/akka/AkkaException.scala

@@ -23,6 +23,7 @@ object AkkaException {
       sb.append("\tat %s\n" format trace(i))
     sb.toString
   }
+
 }
 
 /**

akka-agent/src/main/resources/reference.conf

@@ -10,11 +10,13 @@ akka {
 
     # The dispatcher used for agent-send-off actor
     send-off-dispatcher {
+      executor = thread-pool-executor
       type = PinnedDispatcher
     }
 
     # The dispatcher used for agent-alter-off actor
     alter-off-dispatcher {
+      executor = thread-pool-executor
       type = PinnedDispatcher
     }
 

akka-docs/java/dispatchers.rst

@@ -55,6 +55,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:: ../scala/code/akka/docs/dispatcher/DispatcherDocSpec.scala#my-thread-pool-dispatcher-config
+
 Let's now walk through the different dispatchers in more detail.
 
 Thread-based
@@ -67,9 +78,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/DispatcherDocTestBase.java#defining-pinned-dispatcher
+.. includecode:: ../scala/code/akka/docs/dispatcher/DispatcherDocSpec.scala#my-pinned-dispatcher-config
+
+Note that it must be used with ``executor = "thread-pool-executor"``.
 
 Event-based
 ^^^^^^^^^^^

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
 ^^^^^^^^^^^

akka-remote/src/main/resources/reference.conf

@@ -133,6 +133,7 @@ akka {
 
     # The dispatcher used for the system actor "network-event-sender"
     network-event-sender-dispatcher {
+      executor = thread-pool-executor
       type = PinnedDispatcher
     }
   }

akka-zeromq/src/main/resources/reference.conf

@@ -15,6 +15,7 @@ akka {
     socket-dispatcher {
       # A zeromq socket needs to be pinned to the thread that created it.
       # Changing this value results in weird errors and race conditions within zeromq
+      executor = thread-pool-executor
       type = "PinnedDispatcher"
     }
   }