=act #17425 Document NonBlockingBoundedMailbox to be single-consumer

akka-actor/src/main/java/akka/dispatch/AbstractBoundedNodeQueue.java

@@ -9,7 +9,7 @@ import akka.util.Unsafe;
 import java.util.concurrent.atomic.AtomicReference;
 
 /**
- * Lock-free bounded non-blocking multiple-producer multiple-consumer queue based on the works of:
+ * Lock-free bounded non-blocking multiple-producer single-consumer queue based on the works of:
  *
  * Andriy Plokhotnuyk (https://github.com/plokhotnyuk)
  *   - https://github.com/plokhotnyuk/actors/blob/2e65abb7ce4cbfcb1b29c98ee99303d6ced6b01f/src/test/scala/akka/dispatch/Mailboxes.scala

akka-actor/src/main/scala/akka/dispatch/Mailbox.scala

@@ -386,7 +386,10 @@ class NodeMessageQueue extends AbstractNodeQueue[Envelope] with MessageQueue wit
   }
 }
 
-//Discards overflowing messages into DeadLetters
+/**
+ * Lock-free bounded non-blocking multiple-producer single-consumer queue.
+ * Discards overflowing messages into DeadLetters.
+ */
 class BoundedNodeMessageQueue(capacity: Int) extends AbstractBoundedNodeQueue[Envelope](capacity)
   with MessageQueue with BoundedMessageQueueSemantics with MultipleConsumerSemantics {
   final def pushTimeOut: Duration = Duration.Undefined
@@ -627,9 +630,11 @@ final case class SingleConsumerOnlyUnboundedMailbox() extends MailboxType with P
 }
 
 /**
- * NonBlockingBoundedMailbox is a high-performance, multiple producer—multiple consumer, bounded MailboxType,
+ * NonBlockingBoundedMailbox is a high-performance, multiple-producer single-consumer, bounded MailboxType,
  * Noteworthy is that it discards overflow as DeadLetters.
  *
+ * It can't have multiple consumers, which rules out using it with BalancingPool (BalancingDispatcher) for instance.
+ *
  * NOTE: NonBlockingBoundedMailbox does not use `mailbox-push-timeout-time` as it is non-blocking.
  */
 case class NonBlockingBoundedMailbox(val capacity: Int) extends MailboxType with ProducesMessageQueue[BoundedNodeMessageQueue] {

akka-docs/rst/java/mailboxes.rst

@@ -134,9 +134,9 @@ Akka comes shipped with a number of mailbox implementations:
 
 * **NonBlockingBoundedMailbox**
 
-  - Backed by a very efficient Multiple-Producer Multiple-Consumer queue
+  - Backed by a very efficient Multiple-Producer Single-Consumer queue
 
-  - Blocking: No
+  - Blocking: No (discards overflowing messages into deadLetters)
 
   - Bounded: Yes
 

akka-docs/rst/scala/mailboxes.rst

@@ -134,9 +134,9 @@ Akka comes shipped with a number of mailbox implementations:
 
 * **NonBlockingBoundedMailbox**
 
-  - Backed by a very efficient Multiple-Producer Multiple-Consumer queue
+  - Backed by a very efficient Multiple-Producer Single-Consumer queue
 
-  - Blocking: No
+  - Blocking: No (discards overflowing messages into deadLetters)
 
   - Bounded: Yes