Introduce stable priority mailboxes.

Similar to existing priority mailboxes, but these preserve FIFO ordering
for messages of equal priority.

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

@@ -25,7 +25,7 @@ import akka.event.LoggingAdapter;
 
 //#imports-prio-mailbox
 import akka.dispatch.PriorityGenerator;
-import akka.dispatch.UnboundedPriorityMailbox;
+import akka.dispatch.UnboundedStablePriorityMailbox;
 import akka.testkit.AkkaJUnitActorSystemResource;
 import akka.testkit.JavaTestKit;
 import com.typesafe.config.Config;
@@ -74,7 +74,7 @@ public class DispatcherDocTest {
         .withDispatcher("my-pinned-dispatcher"));
     //#defining-pinned-dispatcher
   }
-  
+
   @SuppressWarnings("unused")
   public void compileLookup() {
     //#lookup
@@ -188,7 +188,7 @@ public class DispatcherDocTest {
 
   static
   //#prio-mailbox
-  public class MyPrioMailbox extends UnboundedPriorityMailbox {
+  public class MyPrioMailbox extends UnboundedStablePriorityMailbox {
     // needed for reflective instantiation
     public MyPrioMailbox(ActorSystem.Settings settings, Config config) {
       // Create a new PriorityGenerator, lower prio means more important

akka-docs/rst/java/mailboxes.rst

@@ -82,8 +82,8 @@ dispatcher which will execute it. Then the mailbox is determined as follows:
 Default Mailbox
 ---------------
 
-When the mailbox is not specified as described above the default mailbox 
-is used. By default it is an unbounded mailbox, which is backed by a 
+When the mailbox is not specified as described above the default mailbox
+is used. By default it is an unbounded mailbox, which is backed by a
 ``java.util.concurrent.ConcurrentLinkedQueue``.
 
 ``SingleConsumerOnlyUnboundedMailbox`` is an even more efficient mailbox, and
@@ -155,6 +155,8 @@ Akka comes shipped with a number of mailbox implementations:
 
   - Backed by a ``java.util.concurrent.PriorityBlockingQueue``
 
+  - Delivery order for messages of equal priority is undefined - contrast with the UnboundedStablePriorityMailbox
+
   - Blocking: Yes
 
   - Bounded: No
@@ -163,7 +165,9 @@ Akka comes shipped with a number of mailbox implementations:
 
 * BoundedPriorityMailbox
 
-  - Backed by a ``java.util.PriorityBlockingQueue`` wrapped in an ``akka.util.BoundedBlockingQueue``
+  - Backed by a ``java.util.PriorityQueue`` wrapped in an ``akka.util.BoundedBlockingQueue``
+
+  - Delivery order for messages of equal priority is undefined - contrast with the BoundedStablePriorityMailbox
 
   - Blocking: Yes
 
@@ -171,6 +175,30 @@ Akka comes shipped with a number of mailbox implementations:
 
   - Configuration name: "akka.dispatch.BoundedPriorityMailbox"
 
+* UnboundedStablePriorityMailbox
+
+  - Backed by a ``java.util.concurrent.PriorityBlockingQueue`` wrapped in an ``akka.util.PriorityQueueStabilizer``
+
+  - FIFO order is preserved for messages of equal priority - contrast with the UnboundedPriorityMailbox
+
+  - Blocking: Yes
+
+  - Bounded: No
+
+  - Configuration name: "akka.dispatch.UnboundedStablePriorityMailbox"
+
+* BoundedStablePriorityMailbox
+
+  - Backed by a ``java.util.PriorityQueue`` wrapped in an ``akka.util.PriorityQueueStabilizer`` and an ``akka.util.BoundedBlockingQueue``
+
+  - FIFO order is preserved for messages of equal priority - contrast with the BoundedPriorityMailbox
+
+  - Blocking: Yes
+
+  - Bounded: Yes
+
+  - Configuration name: "akka.dispatch.BoundedStablePriorityMailbox"
+
 * UnboundedControlAwareMailbox
 
   - Delivers messages that extend ``akka.dispatch.ControlMessage`` with higher priority