Merge branch 'master' into wip-1626-1627-typed-actors-√

akka-docs/java/code/akka/docs/jrouting/ParentActor.java

@@ -7,6 +7,7 @@ import akka.routing.ScatterGatherFirstCompletedRouter;
 import akka.routing.BroadcastRouter;
 import akka.routing.RandomRouter;
 import akka.routing.RoundRobinRouter;
+import akka.routing.SmallestMailboxRouter;
 import akka.actor.UntypedActor;
 import akka.actor.ActorRef;
 import akka.actor.Props;
@@ -34,6 +35,14 @@ public class ParentActor extends UntypedActor {
         randomRouter.tell(i, getSelf());
       }
       //#randomRouter
+    } else if (msg.equals("smr")) {
+      //#smallestMailboxRouter
+      ActorRef smallestMailboxRouter = getContext().actorOf(
+          new Props(PrintlnActor.class).withRouter(new SmallestMailboxRouter(5)), "router");
+      for (int i = 1; i <= 10; i++) {
+        smallestMailboxRouter.tell(i, getSelf());
+      }
+      //#smallestMailboxRouter
     } else if (msg.equals("br")) {
       //#broadcastRouter
       ActorRef broadcastRouter = getContext().actorOf(new Props(PrintlnActor.class).withRouter(new BroadcastRouter(5)),

akka-docs/java/logging.rst

@@ -17,8 +17,13 @@ as illustrated in this example:
 .. includecode:: code/akka/docs/event/LoggingDocTestBase.java
    :include: imports,my-actor
 
-The second parameter to the ``Logging.getLogger`` is the source of this logging channel.
-The source object is translated to a String according to the following rules:
+The first parameter to ``Logging.getLogger`` could also be any
+:class:`LoggingBus`, specifically ``system.eventStream()``; in the demonstrated
+case, the actor system’s address is included in the ``akkaSource``
+representation of the log source (see `Logging Thread and Akka Source in MDC`_)
+while in the second case this is not automatically done. The second parameter
+to ``Logging.getLogger`` is the source of this logging channel.  The source
+object is translated to a String according to the following rules:
 
   * if it is an Actor or ActorRef, its path is used
   * in case of a String it is used as is
@@ -28,6 +33,13 @@ The source object is translated to a String according to the following rules:
 The log message may contain argument placeholders ``{}``, which will be substituted if the log level
 is enabled.
 
+The Java :class:`Class` of the log source is also included in the generated
+:class:`LogEvent`. In case of a simple string this is replaced with a “marker”
+class :class:`akka.event.DummyClassForStringSources` in order to allow special
+treatment of this case, e.g. in the SLF4J event listener which will then use
+the string instead of the class’ name for looking up the logger instance to
+use.
+
 Event Handler
 =============
 
@@ -83,8 +95,8 @@ creating the ``LoggingAdapter`` correspond to the name of the SL4FJ logger.
     loglevel = "DEBUG"
   }
 
-Logging thread in MDC
----------------------
+Logging Thread and Akka Source in MDC
+-------------------------------------
 
 Since the logging is done asynchronously the thread in which the logging was performed is captured in
 Mapped Diagnostic Context (MDC) with attribute name ``sourceThread``.
@@ -96,3 +108,22 @@ With Logback the thread name is available with ``%X{sourceThread}`` specifier wi
     </layout>
   </appender>
 
+.. note::
+  
+  It will probably be a good idea to use the ``sourceThread`` MDC value also in
+  non-Akka parts of the application in order to have this property consistently
+  available in the logs.
+
+Another helpful facility is that Akka captures the actor’s address when
+instantiating a logger within it, meaning that the full instance identification
+is available for associating log messages e.g. with members of a router. This
+information is available in the MDC with attribute name ``akkaSource``::
+
+  <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
+    <layout>
+      <pattern>%date{ISO8601} %-5level %logger{36} %X{akkaSource} - %msg%n</pattern>
+    </layout>
+  </appender>
+
+For more details on what this attribute contains—also for non-actors—please see
+`How to Log`_.

akka-docs/java/routing.rst

@@ -16,11 +16,12 @@ Router
 A Router is an actor that routes incoming messages to outbound actors.
 The router routes the messages sent to it to its underlying actors called 'routees'.
 
-Akka comes with four defined routers out of the box, but as you will see in this chapter it
-is really easy to create your own. The four routers shipped with Akka are:
+Akka comes with some defined routers out of the box, but as you will see in this chapter it
+is really easy to create your own. The routers shipped with Akka are:
 
 * ``akka.routing.RoundRobinRouter``
 * ``akka.routing.RandomRouter``
+* ``akka.routing.SmallestMailboxRouter``
 * ``akka.routing.BroadcastRouter``
 * ``akka.routing.ScatterGatherFirstCompletedRouter``
 
@@ -44,9 +45,8 @@ You can also give the router already created routees as in:
 When you create a router programatically you define the number of routees *or* you pass already created routees to it.
 If you send both parameters to the router *only* the latter will be used, i.e. ``nrOfInstances`` is disregarded.
 
-*It is also worth pointing out that if you define the number of routees (``nr-of-instances`` or  ``routees``) in
-the configuration file then this value will be used instead of any programmatically sent parameters, but you must
-also define the ``router`` property in the configuration.*
+*It is also worth pointing out that if you define the ``router`` in the configuration file then this value will be used
+instead of any programmatically sent parameters.*
 
 Once you have the router actor it is just to send messages to it as you would to any actor:
 
@@ -122,6 +122,21 @@ When run you should see a similar output to this:
 The result from running the random router should be different, or at least random, every time you run it.
 Try to run it a couple of times to verify its behavior if you don't trust us.
 
+SmallestMailboxRouter
+*********************
+A Router that tries to send to the non-suspended routee with fewest messages in mailbox.
+The selection is done in this order:
+
+ * pick any idle routee (not processing message) with empty mailbox
+ * pick any routee with empty mailbox
+ * pick routee with fewest pending messages in mailbox
+ * pick any remote routee, remote actors are consider lowest priority,
+   since their mailbox size is unknown
+
+Code example:
+
+.. includecode:: code/akka/docs/jrouting/ParentActor.java#smallestMailboxRouter
+
 BroadcastRouter
 ***************
 A broadcast router forwards the message it receives to *all* its routees.
@@ -241,6 +256,14 @@ If you are interested in how to use the VoteCountRouter it looks like this:
 
 .. includecode:: code/akka/docs/jrouting/CustomRouterDocTestBase.java#crTest
 
+Configured Custom Router
+************************
+
+It is possible to define configuration properties for custom routers. In the ``router`` property of the deployment
+configuration you define the fully qualified class name of the router class. The router class must extend
+``akka.routing.CustomRouterConfig`` and and have constructor with ``com.typesafe.config.Config`` parameter.
+The deployment section of the configuration is passed to the constructor.
+
 Custom Resizer
 **************