Merge pull request #1343 from akka/wip-2687-per-actor-class-configurable-mailboxes-ban

Allow different types of mailboxes on the same dispatcher #2687

akka-docs/rst/java/code/docs/actor/MyBoundedUntypedActor.java

@@ -0,0 +1,14 @@
+/**
+ * Copyright (C) 2009-2013 Typesafe Inc. <http://www.typesafe.com>
+ */
+
+package docs.actor;
+
+//#my-bounded-untyped-actor
+import akka.dispatch.BoundedMessageQueueSemantics;
+import akka.dispatch.RequiresMessageQueue;
+
+public class MyBoundedUntypedActor extends MyUntypedActor
+  implements RequiresMessageQueue<BoundedMessageQueueSemantics> {
+}
+//#my-bounded-untyped-actor

akka-docs/rst/java/code/docs/dispatcher/DispatcherDocTestBase.java

@@ -30,6 +30,11 @@ import java.util.concurrent.ConcurrentLinkedQueue;
 
 //#imports-custom
 
+//#imports-required-mailbox
+
+//#imports-required-mailbox
+
+import docs.actor.MyBoundedUntypedActor;
 import org.junit.AfterClass;
 import org.junit.BeforeClass;
 import org.junit.Test;
@@ -48,8 +53,8 @@ public class DispatcherDocTestBase {
   @BeforeClass
   public static void beforeAll() {
     system = ActorSystem.create("MySystem",
-        ConfigFactory.parseString(
-          DispatcherDocSpec.config()).withFallback(AkkaSpec.testConf()));
+      ConfigFactory.parseString(DispatcherDocSpec.javaConfig()).withFallback(
+              ConfigFactory.parseString(DispatcherDocSpec.config())).withFallback(AkkaSpec.testConf()));
   }
 
   @AfterClass
@@ -96,6 +101,33 @@ public class DispatcherDocTestBase {
     //#lookup
   }
 
+  @SuppressWarnings("unused")
+  @Test
+  public void defineMailboxInConfig() {
+    //#defining-mailbox-in-config
+    ActorRef myActor =
+      system.actorOf(Props.create(MyUntypedActor.class),
+        "priomailboxactor");
+    //#defining-mailbox-in-config
+  }
+
+  @SuppressWarnings("unused")
+  @Test
+  public void defineMailboxInCode() {
+    //#defining-mailbox-in-code
+    ActorRef myActor =
+      system.actorOf(Props.create(MyUntypedActor.class)
+        .withMailbox("prio-mailbox"));
+    //#defining-mailbox-in-code
+  }
+
+  @SuppressWarnings("unused")
+  @Test
+  public void usingARequiredMailbox() {
+    ActorRef myActor =
+      system.actorOf(Props.create(MyBoundedUntypedActor.class));
+  }
+
   @Test
   public void priorityDispatcher() throws Exception {
     JavaTestKit probe = new JavaTestKit(system);

akka-docs/rst/java/dispatchers.rst

@@ -202,14 +202,55 @@ And then an example on how you would use it:
 
 .. includecode:: ../java/code/docs/dispatcher/DispatcherDocTestBase.java#prio-dispatcher
 
+It is also possible to configure a mailbox type directly like this:
+
+.. includecode:: ../scala/code/docs/dispatcher/DispatcherDocSpec.scala
+   :include: prio-mailbox-config-java,mailbox-deployment-config
+
+And then use it either from deployment like this:
+
+.. includecode:: code/docs/dispatcher/DispatcherDocTestBase.java#defining-mailbox-in-config
+
+Or code like this:
+
+.. includecode:: code/docs/dispatcher/DispatcherDocTestBase.java#defining-mailbox-in-code
+
+
+Requiring a message queue type for an Actor
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+It is possible to require a certain type of message queue for a certain type of actor
+by having that actor implement the parameterized interface :class:`RequiresMessageQueue`. Here is
+an example:
+
+.. includecode:: code/docs/actor/MyBoundedUntypedActor.java#my-bounded-untyped-actor
+
+The type parameter to the :class:`RequiresMessageQueue` interface needs to be mapped to a mailbox in
+configuration like this:
+
+.. includecode:: ../scala/code/docs/dispatcher/DispatcherDocSpec.scala
+   :include: bounded-mailbox-config,required-mailbox-config
+
+Now every time you create an actor of type :class:`MyBoundedUntypedActor` it will try to get a bounded
+mailbox. If the actor has a different mailbox configured in deployment, either directly or via
+a dispatcher with a specified mailbox type, then that will override this mapping.
+
 .. note::
 
-  Make sure to include a constructor which takes
-  ``akka.actor.ActorSystem.Settings`` and ``com.typesafe.config.Config``
-  arguments, as this constructor is invoked reflectively to construct your
-  mailbox type. The config passed in as second argument is that section from
-  the configuration which describes the dispatcher using this mailbox type; the
-  mailbox type will be instantiated once for each dispatcher using it.
+  The type of the queue in the mailbox created for an actor will be checked against the required type in the
+  interface and if the queue doesn't implement the required type an error will be logged.
+
+
+Mailbox configuration precedence
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The order of precedence for the mailbox type of an actor, where lower numbers override higher, is:
+
+1. Mailbox type configured in the deployment of the actor
+2. Mailbox type configured on the dispatcher of the actor
+3. Mailbox type configured on the Props of the actor
+4. Mailbox type configured via message queue requirement
+
 
 Creating your own Mailbox type
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -220,7 +261,8 @@ An example is worth a thousand quacks:
 
 .. includecode:: code/docs/dispatcher/DispatcherDocTestBase.java#mailbox-implementation-example
 
-And then you just specify the FQCN of your MailboxType as the value of the "mailbox-type" in the dispatcher configuration.
+And then you just specify the FQCN of your MailboxType as the value of the "mailbox-type" in the dispatcher
+configuration, or the mailbox configuration.
 
 .. note::
 
@@ -228,8 +270,9 @@ And then you just specify the FQCN of your MailboxType as the value of the "mail
   ``akka.actor.ActorSystem.Settings`` and ``com.typesafe.config.Config``
   arguments, as this constructor is invoked reflectively to construct your
   mailbox type. The config passed in as second argument is that section from
-  the configuration which describes the dispatcher using this mailbox type; the
-  mailbox type will be instantiated once for each dispatcher using it.
+  the configuration which describes the dispatcher or mailbox setting using
+  this mailbox type; the mailbox type will be instantiated once for each
+  dispatcher or mailbox setting using it.
 
 
 Special Semantics of ``system.actorOf``