Merge pull request #17644 from ktoso/wip-docs-better-balancing-dispatcher-ktoso

+doc #17597 improve BalancingPool docs, show configuring executor

akka-docs/rst/java/routing.rst

@@ -279,6 +279,19 @@ configuration.
 
 .. includecode:: ../scala/code/docs/routing/RouterDocSpec.scala#config-balancing-pool2
 
+The ``BalancingPool`` automatically uses a special ``BalancingDispatcher`` for its
+routees - disregarding any dispatcher that is set on the the routee Props object.
+This is needed in order to implement the balancing semantics via
+sharing the same mailbox by all the routees.
+
+While it is not possible to change the dispatcher used by the routees, it is possible
+to fine tune the used *executor*. By default the ``fork-join-dispatcher`` is used and
+can be configured as explained in :ref:`dispatchers-java`. In situations where the
+routees are expected to perform blocking operations it may be useful to replace it
+with a ``thread-pool-executor`` hinting the number of allocated threads explicitly:
+
+.. includecode:: ../scala/code/docs/routing/RouterDocSpec.scala#config-balancing-pool3
+
 There is no Group variant of the BalancingPool.
 
 SmallestMailboxPool

akka-docs/rst/scala/code/docs/routing/RouterDocSpec.scala

@@ -4,6 +4,7 @@
 package docs.routing
 
 import scala.concurrent.duration._
+import scala.collection.JavaConverters._
 import akka.testkit._
 import akka.actor.{ ActorRef, Props, Actor }
 import akka.actor.Terminated
@@ -84,6 +85,24 @@ akka.actor.deployment {
 }
 #//#config-balancing-pool2
 
+#//#config-balancing-pool3
+akka.actor.deployment {
+  /parent/router10b {
+    router = balancing-pool
+    nr-of-instances = 5
+    pool-dispatcher {
+      executor = "thread-pool-executor"
+
+      # allocate exactly 5 threads for this pool
+      thread-pool-executor {
+        core-pool-size-min = 5
+        core-pool-size-max = 5
+      }
+    }
+  }
+}
+#//#config-balancing-pool3
+    
 #//#config-smallest-mailbox-pool
 akka.actor.deployment {
   /parent/router11 {
@@ -227,9 +246,7 @@ router-dispatcher {}
   final case class Work(payload: String)
 
   //#router-in-actor
-  import akka.routing.ActorRefRoutee
-  import akka.routing.Router
-  import akka.routing.RoundRobinRoutingLogic
+  import akka.routing.{ ActorRefRoutee, RoundRobinRoutingLogic, Router }
 
   class Master extends Actor {
     var router = {
@@ -328,6 +345,16 @@ router-dispatcher {}
       context.actorOf(BalancingPool(5).props(Props[Worker]), "router10")
     //#balancing-pool-2
 
+    // #balancing-pool-3
+    val router10b: ActorRef =
+      context.actorOf(BalancingPool(20).props(Props[Worker]), "router10b")
+    //#balancing-pool-3
+    import scala.collection.JavaConversions._
+    for (i <- 1 to 100) router10b ! i
+    val threads10b = Thread.getAllStackTraces.keySet.filter { _.getName contains "router10b" }
+    val threads10bNr = threads10b.size
+    require(threads10bNr == 5, s"Expected 5 threads for router10b, had $threads10bNr! Got: ${threads10b.map(_.getName)}")
+
     //#smallest-mailbox-pool-1
     val router11: ActorRef =
       context.actorOf(FromConfig.props(Props[Worker]), "router11")

akka-docs/rst/scala/routing.rst

@@ -278,6 +278,19 @@ configuration.
 
 .. includecode:: code/docs/routing/RouterDocSpec.scala#config-balancing-pool2
 
+The ``BalancingPool`` automatically uses a special ``BalancingDispatcher`` for its
+routees - disregarding any dispatcher that is set on the the routee Props object.
+This is needed in order to implement the balancing semantics via
+sharing the same mailbox by all the routees.
+
+While it is not possible to change the dispatcher used by the routees, it is possible
+to fine tune the used *executor*. By default the ``fork-join-dispatcher`` is used and
+can be configured as explained in :ref:`dispatchers-scala`. In situations where the
+routees are expected to perform blocking operations it may be useful to replace it
+with a ``thread-pool-executor`` hinting the number of allocated threads explicitly:
+
+.. includecode:: code/docs/routing/RouterDocSpec.scala#config-balancing-pool3
+
 There is no Group variant of the BalancingPool.
 
 SmallestMailboxPool