+act #3246 Added control aware mailbox types

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

@@ -3,6 +3,7 @@
  */
 package docs.dispatcher;
 
+import akka.dispatch.ControlMessage;
 import akka.dispatch.RequiresMessageQueue;
 import akka.testkit.AkkaSpec;
 import com.typesafe.config.ConfigFactory;
@@ -150,6 +151,41 @@ public class DispatcherDocTest {
     probe.expectMsgClass(Terminated.class);
   }
 
+  @Test
+  public void controlAwareDispatcher() throws Exception {
+    JavaTestKit probe = new JavaTestKit(system);
+    //#control-aware-dispatcher
+
+    class Demo extends UntypedActor {
+      LoggingAdapter log = Logging.getLogger(getContext().system(), this);
+      {
+        for (Object msg : new Object[] { "foo", "bar", new MyControlMessage(),
+                PoisonPill.getInstance() }) {
+          getSelf().tell(msg, getSelf());
+        }
+      }
+
+      public void onReceive(Object message) {
+        log.info(message.toString());
+      }
+    }
+
+    // We create a new Actor that just prints out what it processes
+    ActorRef myActor = system.actorOf(Props.create(Demo.class, this)
+            .withDispatcher("control-aware-dispatcher"));
+
+    /*
+    Logs:
+      'MyControlMessage
+      'foo
+      'bar
+    */
+    //#control-aware-dispatcher
+
+    probe.watch(myActor);
+    probe.expectMsgClass(Terminated.class);
+  }
+
   static
   //#prio-mailbox
   public class MyPrioMailbox extends UnboundedPriorityMailbox {
@@ -173,6 +209,11 @@ public class DispatcherDocTest {
   }
   //#prio-mailbox
 
+  static
+  //#control-aware-mailbox-messages
+  public class MyControlMessage implements ControlMessage {}
+  //#control-aware-mailbox-messages
+
   @Test
   public void requiredMailboxDispatcher() throws Exception {
     ActorRef myActor = system.actorOf(Props.create(MyUntypedActor.class)

akka-docs/rst/java/mailboxes.rst

@@ -161,9 +161,36 @@ Akka comes shipped with a number of mailbox implementations:
 
   - Configuration name: "akka.dispatch.BoundedPriorityMailbox"
 
+* UnboundedControlAwareMailbox
+
+  - Delivers messages that extend ``akka.dispatch.ControlMessage`` with higher priority
+
+  - Backed by two ``java.util.concurrent.ConcurrentLinkedQueue``
+
+  - Blocking: No
+
+  - Bounded: No
+
+  - Configuration name: "akka.dispatch.UnboundedControlAwareMailbox"
+
+* BoundedControlAwareMailbox
+
+  - Delivers messages that extend ``akka.dispatch.ControlMessage`` with higher priority
+
+  - Backed by two ``java.util.concurrent.ConcurrentLinkedQueue`` and blocking on enqueue if capacity has been reached
+
+  - Blocking: Yes
+
+  - Bounded: Yes
+
+  - Configuration name: "akka.dispatch.BoundedControlAwareMailbox"
+
 Mailbox configuration examples
 ==============================
 
+PriorityMailbox
+---------------
+
 How to create a PriorityMailbox:
 
 .. includecode:: ../java/code/docs/dispatcher/DispatcherDocTest.java#prio-mailbox
@@ -189,6 +216,23 @@ Or code like this:
 
 .. includecode:: code/docs/dispatcher/DispatcherDocTest.java#defining-mailbox-in-code
 
+ControlAwareMailbox
+-------------------
+
+A ``ControlAwareMailbox`` can be very useful if an actor needs to be able to receive control messages
+immediately no matter how many other messages are already in its mailbox.
+
+It can be configured like this:
+
+.. includecode:: ../scala/code/docs/dispatcher/DispatcherDocSpec.scala#control-aware-mailbox-config
+
+Control messages need to extend the ``ControlMessage`` trait:
+
+.. includecode:: ../java/code/docs/dispatcher/DispatcherDocTest.java#control-aware-mailbox-messages
+
+And then an example on how you would use it:
+
+.. includecode:: ../java/code/docs/dispatcher/DispatcherDocTest.java#control-aware-dispatcher
 
 Creating your own Mailbox type
 ==============================