Merge pull request #478 from akka/wip-2080-doc-routers-and-dispatchers

added docs about BalancingDispatcher and routers, see #2080

akka-docs/java/dispatchers.rst

@@ -72,6 +72,8 @@ There are 4 different types of message dispatchers:
 
   - This is an executor based event driven dispatcher that will try to redistribute work from busy actors to idle actors. 
 
+  - All the actors share a single Mailbox that they get their messages from.
+
   - It is assumed that all actors using the same instance of this dispatcher can process all messages that have been sent to one of the actors; i.e. the actors belong to a pool of actors, and to the client there is no guarantee about which actor instance actually processes a given message.
 
   - Sharability: Actors of the same type only

akka-docs/java/routing.rst

@@ -358,8 +358,8 @@ routing is not so important (i.e. no consistent hashing or round-robin is
 required); this enables newly created routees to pick up work immediately by
 stealing it from their siblings.
 
-The “head” router, of course, cannot run on the same balancing dispatcher,
-because it does not process the same messages, hence this special actor does
+The “head” router cannot always run on the same dispatcher, because it
+does not process the same type of messages, hence this special actor does
 not use the dispatcher configured in :class:`Props`, but takes the
 ``routerDispatcher`` from the :class:`RouterConfig` instead, which defaults to
 the actor system’s default dispatcher. All standard routers allow setting this
@@ -368,3 +368,31 @@ implement the method in a suitable way.
 
 .. includecode:: code/akka/docs/jrouting/CustomRouterDocTestBase.java#dispatchers
 
+.. note::
+
+   It is not allowed to configure the ``routerDispatcher`` to be a
+   :class:`BalancingDispatcher` since the messages meant for the special
+   router actor cannot be processed by any other actor.
+
+At first glance there seems to be an overlap between the
+:class:`BalancingDispatcher` and Routers, but they complement each other.
+The balancing dispatcher is in charge of running the actors while the routers
+are in charge of deciding which message goes where. A router can also have
+children that span multiple actor systems, even remote ones, but a dispatcher
+lives inside a single actor system.
+
+When using a :class:`RoundRobinRouter` with a :class:`BalancingDispatcher`
+there are some configuration settings to take into account.
+
+- There can only be ``nr-of-instances`` messages being processed at the same
+  time no matter how many threads are configured for the
+  :class:`BalancingDispatcher`.
+
+- Having ``throughput`` set to a low number makes no sense since you will only
+  be handing off to another actor that processes the same :class:`MailBox`
+  as yourself, which can be costly. Either the message just got into the
+  mailbox and you can receive it as well as anybody else, or everybody else
+  is busy and you are the only one available to receive the message.
+
+- Resizing the number of routees only introduce inertia, since resizing
+  is performed at specified intervals, but work stealing is instantaneous.

akka-docs/scala/dispatchers.rst

@@ -71,7 +71,9 @@ There are 4 different types of message dispatchers:
 
 * BalancingDispatcher
 
-  - This is an executor based event driven dispatcher that will try to redistribute work from busy actors to idle actors. 
+  - This is an executor based event driven dispatcher that will try to redistribute work from busy actors to idle actors.
+
+  - All the actors share a single Mailbox that they get their messages from.
 
   - It is assumed that all actors using the same instance of this dispatcher can process all messages that have been sent to one of the actors; i.e. the actors belong to a pool of actors, and to the client there is no guarantee about which actor instance actually processes a given message.
 

akka-docs/scala/routing.rst

@@ -364,8 +364,8 @@ stealing it from their siblings.
    that was configured for them in their ``Props``, it is not possible to change an actors dispatcher
    after it has been created.
 
-The “head” router, of course, cannot run on the same balancing dispatcher,
-because it does not process the same messages, hence this special actor does
+The “head” router cannot always run on the same dispatcher, because it
+does not process the same type of messages, hence this special actor does
 not use the dispatcher configured in :class:`Props`, but takes the
 ``routerDispatcher`` from the :class:`RouterConfig` instead, which defaults to
 the actor system’s default dispatcher. All standard routers allow setting this
@@ -374,3 +374,32 @@ implement the method in a suitable way.
 
 .. includecode:: code/akka/docs/routing/RouterDocSpec.scala#dispatchers
 
+
+.. note::
+
+   It is not allowed to configure the ``routerDispatcher`` to be a
+   :class:`BalancingDispatcher` since the messages meant for the special
+   router actor cannot be processed by any other actor.
+
+At first glance there seems to be an overlap between the
+:class:`BalancingDispatcher` and Routers, but they complement each other.
+The balancing dispatcher is in charge of running the actors while the routers
+are in charge of deciding which message goes where. A router can also have
+children that span multiple actor systems, even remote ones, but a dispatcher
+lives inside a single actor system.
+
+When using a :class:`RoundRobinRouter` with a :class:`BalancingDispatcher`
+there are some configuration settings to take into account.
+
+- There can only be ``nr-of-instances`` messages being processed at the same
+  time no matter how many threads are configured for the
+  :class:`BalancingDispatcher`.
+
+- Having ``throughput`` set to a low number makes no sense since you will only
+  be handing off to another actor that processes the same :class:`MailBox`
+  as yourself, which can be costly. Either the message just got into the
+  mailbox and you can receive it as well as anybody else, or everybody else
+  is busy and you are the only one available to receive the message.
+
+- Resizing the number of routees only introduce inertia, since resizing
+  is performed at specified intervals, but work stealing is instantaneous.