diff --git a/akka-docs/rst/java/dispatchers.rst b/akka-docs/rst/java/dispatchers.rst index 1339f068fd..08011ea742 100644 --- a/akka-docs/rst/java/dispatchers.rst +++ b/akka-docs/rst/java/dispatchers.rst @@ -141,159 +141,3 @@ Note that it's not guaranteed that the *same* thread is used over time, since th is used for ``PinnedDispatcher`` to keep resource usage down in case of idle actors. To use the same thread all the time you need to add ``thread-pool-executor.allow-core-timeout=off`` to the configuration of the ``PinnedDispatcher``. - -Mailboxes ---------- - -An Akka ``Mailbox`` holds the messages that are destined for an ``Actor``. -Normally each ``Actor`` has its own mailbox, but with example a ``BalancingDispatcher`` all actors with the same ``BalancingDispatcher`` will share a single instance. - -Builtin implementations -^^^^^^^^^^^^^^^^^^^^^^^ - -Akka comes shipped with a number of default mailbox implementations: - -* UnboundedMailbox - - - Backed by a ``java.util.concurrent.ConcurrentLinkedQueue`` - - - Blocking: No - - - Bounded: No - -* BoundedMailbox - - - Backed by a ``java.util.concurrent.LinkedBlockingQueue`` - - - Blocking: Yes - - - Bounded: Yes - -* UnboundedPriorityMailbox - - - Backed by a ``java.util.concurrent.PriorityBlockingQueue`` - - - Blocking: Yes - - - Bounded: No - -* BoundedPriorityMailbox - - - Backed by a ``java.util.PriorityBlockingQueue`` wrapped in an ``akka.util.BoundedBlockingQueue`` - - - Blocking: Yes - - - Bounded: Yes - -* Durable mailboxes, see :ref:`durable-mailboxes-java`. - -Mailbox configuration examples -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -How to create a PriorityMailbox: - -.. includecode:: ../java/code/docs/dispatcher/DispatcherDocTest.java#prio-mailbox - -And then add it to the configuration: - -.. includecode:: ../scala/code/docs/dispatcher/DispatcherDocSpec.scala#prio-dispatcher-config - -And then an example on how you would use it: - -.. includecode:: ../java/code/docs/dispatcher/DispatcherDocTest.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/DispatcherDocTest.java#defining-mailbox-in-config - -Or code like this: - -.. includecode:: code/docs/dispatcher/DispatcherDocTest.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:: - - 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 then actor creation will fail. - - -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 -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -An example is worth a thousand quacks: - -.. includecode:: code/docs/dispatcher/DispatcherDocTest.java#imports-custom - -.. includecode:: code/docs/dispatcher/DispatcherDocTest.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, or the mailbox configuration. - -.. 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 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`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -In order to make ``system.actorOf`` both synchronous and non-blocking while -keeping the return type :class:`ActorRef` (and the semantics that the returned -ref is fully functional), special handling takes place for this case. Behind -the scenes, a hollow kind of actor reference is constructed, which is sent to -the system’s guardian actor who actually creates the actor and its context and -puts those inside the reference. Until that has happened, messages sent to the -:class:`ActorRef` will be queued locally, and only upon swapping the real -filling in will they be transferred into the real mailbox. Thus, - -.. code-block:: scala - - final Props props = ... - // this actor uses MyCustomMailbox, which is assumed to be a singleton - system.actorOf(props.withDispatcher("myCustomMailbox").tell("bang", sender); - assert(MyCustomMailbox.getInstance().getLastEnqueued().equals("bang")); - -will probably fail; you will have to allow for some time to pass and retry the -check à la :meth:`TestKit.awaitCond`. - diff --git a/akka-docs/rst/java/durable-mailbox.rst b/akka-docs/rst/java/durable-mailbox.rst index 2f320a3b79..1a5c38aadf 100644 --- a/akka-docs/rst/java/durable-mailbox.rst +++ b/akka-docs/rst/java/durable-mailbox.rst @@ -15,8 +15,8 @@ mailbox when the node of the actor resides on crashes, then when you restart the node, the actor will be able to continue processing as if nothing had happened; with all pending messages still in its mailbox. -You configure durable mailboxes through the dispatcher. The actor is oblivious -to which type of mailbox it is using. +You configure durable mailboxes through the dispatcher or the actor deployment (see +:ref:`mailboxes-java`). The actor is oblivious to which type of mailbox it is using. This gives you an excellent way of creating bulkheads in your application, where groups of actors sharing the same dispatcher also share the same backing diff --git a/akka-docs/rst/java/index-actors.rst b/akka-docs/rst/java/index-actors.rst index 12d2887ff2..64a4c863ee 100644 --- a/akka-docs/rst/java/index-actors.rst +++ b/akka-docs/rst/java/index-actors.rst @@ -8,6 +8,7 @@ Actors typed-actors fault-tolerance dispatchers + mailboxes routing fsm testing diff --git a/akka-docs/rst/java/mailboxes.rst b/akka-docs/rst/java/mailboxes.rst new file mode 100644 index 0000000000..c2b8c8bbf2 --- /dev/null +++ b/akka-docs/rst/java/mailboxes.rst @@ -0,0 +1,158 @@ +.. _mailboxes-java: + +Mailboxes +========= + +An Akka ``Mailbox`` holds the messages that are destined for an ``Actor``. +Normally each ``Actor`` has its own mailbox, but with for example a ``BalancingDispatcher`` +all actors with the same ``BalancingDispatcher`` will share a single instance. + +Builtin Mailbox Implementations +------------------------------- + +Akka comes shipped with a number of default mailbox implementations: + +* UnboundedMailbox + + - Backed by a ``java.util.concurrent.ConcurrentLinkedQueue`` + + - Blocking: No + + - Bounded: No + +* BoundedMailbox + + - Backed by a ``java.util.concurrent.LinkedBlockingQueue`` + + - Blocking: Yes + + - Bounded: Yes + +* UnboundedPriorityMailbox + + - Backed by a ``java.util.concurrent.PriorityBlockingQueue`` + + - Blocking: Yes + + - Bounded: No + +* BoundedPriorityMailbox + + - Backed by a ``java.util.PriorityBlockingQueue`` wrapped in an ``akka.util.BoundedBlockingQueue`` + + - Blocking: Yes + + - Bounded: Yes + +* Durable mailboxes, see :ref:`durable-mailboxes-java`. + +Mailbox configuration examples +------------------------------ + +How to create a PriorityMailbox: + +.. includecode:: ../java/code/docs/dispatcher/DispatcherDocTest.java#prio-mailbox + +And then add it to the configuration: + +.. includecode:: ../scala/code/docs/dispatcher/DispatcherDocSpec.scala#prio-dispatcher-config + +And then an example on how you would use it: + +.. includecode:: ../java/code/docs/dispatcher/DispatcherDocTest.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/DispatcherDocTest.java#defining-mailbox-in-config + +Or code like this: + +.. includecode:: code/docs/dispatcher/DispatcherDocTest.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:: + + 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 then actor creation will fail. + + +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 +------------------------------ + +An example is worth a thousand quacks: + +.. includecode:: code/docs/dispatcher/DispatcherDocTest.java#imports-custom + +.. includecode:: code/docs/dispatcher/DispatcherDocTest.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, or the mailbox configuration. + +.. 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 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`` +--------------------------------------- + +In order to make ``system.actorOf`` both synchronous and non-blocking while +keeping the return type :class:`ActorRef` (and the semantics that the returned +ref is fully functional), special handling takes place for this case. Behind +the scenes, a hollow kind of actor reference is constructed, which is sent to +the system’s guardian actor who actually creates the actor and its context and +puts those inside the reference. Until that has happened, messages sent to the +:class:`ActorRef` will be queued locally, and only upon swapping the real +filling in will they be transferred into the real mailbox. Thus, + +.. code-block:: scala + + final Props props = ... + // this actor uses MyCustomMailbox, which is assumed to be a singleton + system.actorOf(props.withDispatcher("myCustomMailbox").tell("bang", sender); + assert(MyCustomMailbox.getInstance().getLastEnqueued().equals("bang")); + +will probably fail; you will have to allow for some time to pass and retry the +check à la :meth:`TestKit.awaitCond`. + diff --git a/akka-docs/rst/java/untyped-actors.rst b/akka-docs/rst/java/untyped-actors.rst index 7483a7cc8d..f2d5dbf9ce 100644 --- a/akka-docs/rst/java/untyped-actors.rst +++ b/akka-docs/rst/java/untyped-actors.rst @@ -149,10 +149,12 @@ Creating Actors with Factory Methods ------------------------------------ If your UntypedActor has a constructor that takes parameters then those need to -be part of the :class:`Props` as well, as described `above `_. But there +be part of the :class:`Props` as well, as described `above`__. But there are cases when a factory method must be used, for example when the actual constructor arguments are determined by a dependency injection framework. +__ Props_ + .. includecode:: code/docs/actor/UntypedActorDocTest.java#import-indirect .. includecode:: code/docs/actor/UntypedActorDocTest.java :include: creating-indirectly @@ -691,14 +693,8 @@ behavior. Upon changing the actor's message handler, i.e., right before invoking ``getContext().become()`` or ``getContext().unbecome()``, all stashed messages can be "unstashed", thereby prepending them to the actor's mailbox. This way, the stashed messages can be processed in the same -order as they have been received originally. - -.. warning:: - - Please note that the stash can only be used together with actors - that have a deque-based mailbox. For this, configure the - ``mailbox-type`` of the dispatcher to be a deque-based mailbox, such as - ``akka.dispatch.UnboundedDequeBasedMailbox`` (see :ref:`dispatchers-java`). +order as they have been received originally. An actor that extends +``UntypedActorWithStash`` will automatically get a deque-based mailbox. Here is an example of the ``UntypedActorWithStash`` class in action: diff --git a/akka-docs/rst/scala/actors.rst b/akka-docs/rst/scala/actors.rst index 472d94a636..319198a077 100644 --- a/akka-docs/rst/scala/actors.rst +++ b/akka-docs/rst/scala/actors.rst @@ -165,10 +165,12 @@ Creating Actors with Factory Methods ------------------------------------ If your UntypedActor has a constructor that takes parameters then those need to -be part of the :class:`Props` as well, as described `above `_. But there +be part of the :class:`Props` as well, as described `above`__. But there are cases when a factory method must be used, for example when the actual constructor arguments are determined by a dependency injection framework. +__ Props_ + .. includecode:: code/docs/actor/ActorDocSpec.scala :include: creating-indirectly :exclude: obtain-fresh-Actor-instance-from-DI-framework @@ -795,8 +797,9 @@ order as they have been received originally. Please note that the ``Stash`` can only be used together with actors that have a deque-based mailbox. For this, configure the - ``mailbox-type`` of the dispatcher to be a deque-based mailbox, such as - ``akka.dispatch.UnboundedDequeBasedMailbox`` (see :ref:`dispatchers-scala`). + ``mailbox-type`` of the dispatcher or in the deployment of the actor + to be a deque-based mailbox, such as ``akka.dispatch.UnboundedDequeBasedMailbox`` + (see :ref:`mailboxes-scala`). Here is an example of the ``Stash`` in action: diff --git a/akka-docs/rst/scala/dispatchers.rst b/akka-docs/rst/scala/dispatchers.rst index 40ba81160a..89c403af03 100644 --- a/akka-docs/rst/scala/dispatchers.rst +++ b/akka-docs/rst/scala/dispatchers.rst @@ -143,157 +143,3 @@ Note that it's not guaranteed that the *same* thread is used over time, since th is used for ``PinnedDispatcher`` to keep resource usage down in case of idle actors. To use the same thread all the time you need to add ``thread-pool-executor.allow-core-timeout=off`` to the configuration of the ``PinnedDispatcher``. - -Mailboxes ---------- - -An Akka ``Mailbox`` holds the messages that are destined for an ``Actor``. -Normally each ``Actor`` has its own mailbox, but with example a ``BalancingDispatcher`` all actors with the same ``BalancingDispatcher`` will share a single instance. - -Builtin implementations -^^^^^^^^^^^^^^^^^^^^^^^ - -Akka comes shipped with a number of default mailbox implementations: - -* UnboundedMailbox - - - Backed by a ``java.util.concurrent.ConcurrentLinkedQueue`` - - - Blocking: No - - - Bounded: No - -* BoundedMailbox - - - Backed by a ``java.util.concurrent.LinkedBlockingQueue`` - - - Blocking: Yes - - - Bounded: Yes - -* UnboundedPriorityMailbox - - - Backed by a ``java.util.concurrent.PriorityBlockingQueue`` - - - Blocking: Yes - - - Bounded: No - -* BoundedPriorityMailbox - - - Backed by a ``java.util.PriorityBlockingQueue`` wrapped in an ``akka.util.BoundedBlockingQueue`` - - - Blocking: Yes - - - Bounded: Yes - -* Durable mailboxes, see :ref:`durable-mailboxes-scala`. - -Mailbox configuration examples -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -How to create a PriorityMailbox: - -.. includecode:: ../scala/code/docs/dispatcher/DispatcherDocSpec.scala#prio-mailbox - -And then add it to the configuration: - -.. includecode:: ../scala/code/docs/dispatcher/DispatcherDocSpec.scala#prio-dispatcher-config - -And then an example on how you would use it: - -.. includecode:: ../scala/code/docs/dispatcher/DispatcherDocSpec.scala#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,mailbox-deployment-config - -And then use it either from deployment like this: - -.. includecode:: ../scala/code/docs/dispatcher/DispatcherDocSpec.scala#defining-mailbox-in-config - -Or code like this: - -.. includecode:: ../scala/code/docs/dispatcher/DispatcherDocSpec.scala#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 extend the parameterized trait :class:`RequiresMessageQueue`. Here is -an example: - -.. includecode:: ../scala/code/docs/dispatcher/DispatcherDocSpec.scala#required-mailbox-class - -The type parameter to the :class:`RequiresMessageQueue` trait 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:`MyBoundedActor` 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:: - - The type of the queue in the mailbox created for an actor will be checked against the required type in the - trait and if the queue doesn't implement the required type then actor creation will fail. - - -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 -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -An example is worth a thousand quacks: - -.. includecode:: ../scala/code/docs/dispatcher/DispatcherDocSpec.scala#mailbox-implementation-example - -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:: - - 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 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`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -In order to make ``system.actorOf`` both synchronous and non-blocking while -keeping the return type :class:`ActorRef` (and the semantics that the returned -ref is fully functional), special handling takes place for this case. Behind -the scenes, a hollow kind of actor reference is constructed, which is sent to -the system’s guardian actor who actually creates the actor and its context and -puts those inside the reference. Until that has happened, messages sent to the -:class:`ActorRef` will be queued locally, and only upon swapping the real -filling in will they be transferred into the real mailbox. Thus, - -.. code-block:: scala - - val props: Props = ... - // this actor uses MyCustomMailbox, which is assumed to be a singleton - system.actorOf(props.withDispatcher("myCustomMailbox")) ! "bang" - assert(MyCustomMailbox.instance.getLastEnqueuedMessage == "bang") - -will probably fail; you will have to allow for some time to pass and retry the -check à la :meth:`TestKit.awaitCond`. - diff --git a/akka-docs/rst/scala/durable-mailbox.rst b/akka-docs/rst/scala/durable-mailbox.rst index 76815df4cd..29758cde65 100644 --- a/akka-docs/rst/scala/durable-mailbox.rst +++ b/akka-docs/rst/scala/durable-mailbox.rst @@ -15,8 +15,8 @@ mailbox when the node of the actor resides on crashes, then when you restart the node, the actor will be able to continue processing as if nothing had happened; with all pending messages still in its mailbox. -You configure durable mailboxes through the dispatcher. The actor is oblivious -to which type of mailbox it is using. +You configure durable mailboxes through the dispatcher or the actor deployment (see +:ref:`mailboxes-scala`). The actor is oblivious to which type of mailbox it is using. This gives you an excellent way of creating bulkheads in your application, where groups of actors sharing the same dispatcher also share the same backing diff --git a/akka-docs/rst/scala/index-actors.rst b/akka-docs/rst/scala/index-actors.rst index af097d8693..3504ad8daf 100644 --- a/akka-docs/rst/scala/index-actors.rst +++ b/akka-docs/rst/scala/index-actors.rst @@ -9,6 +9,7 @@ Actors typed-actors fault-tolerance dispatchers + mailboxes routing fsm testing diff --git a/akka-docs/rst/scala/mailboxes.rst b/akka-docs/rst/scala/mailboxes.rst new file mode 100644 index 0000000000..ac933cb781 --- /dev/null +++ b/akka-docs/rst/scala/mailboxes.rst @@ -0,0 +1,155 @@ +.. _mailboxes-scala: + +Mailboxes +========= + +An Akka ``Mailbox`` holds the messages that are destined for an ``Actor``. +Normally each ``Actor`` has its own mailbox, but with for example a ``BalancingDispatcher`` +all actors with the same ``BalancingDispatcher`` will share a single instance. + +Builtin implementations +----------------------- + +Akka comes shipped with a number of default mailbox implementations: + +* UnboundedMailbox + + - Backed by a ``java.util.concurrent.ConcurrentLinkedQueue`` + + - Blocking: No + + - Bounded: No + +* BoundedMailbox + + - Backed by a ``java.util.concurrent.LinkedBlockingQueue`` + + - Blocking: Yes + + - Bounded: Yes + +* UnboundedPriorityMailbox + + - Backed by a ``java.util.concurrent.PriorityBlockingQueue`` + + - Blocking: Yes + + - Bounded: No + +* BoundedPriorityMailbox + + - Backed by a ``java.util.PriorityBlockingQueue`` wrapped in an ``akka.util.BoundedBlockingQueue`` + + - Blocking: Yes + + - Bounded: Yes + +* Durable mailboxes, see :ref:`durable-mailboxes-scala`. + +Mailbox configuration examples +------------------------------ + +How to create a PriorityMailbox: + +.. includecode:: ../scala/code/docs/dispatcher/DispatcherDocSpec.scala#prio-mailbox + +And then add it to the configuration: + +.. includecode:: ../scala/code/docs/dispatcher/DispatcherDocSpec.scala#prio-dispatcher-config + +And then an example on how you would use it: + +.. includecode:: ../scala/code/docs/dispatcher/DispatcherDocSpec.scala#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,mailbox-deployment-config + +And then use it either from deployment like this: + +.. includecode:: ../scala/code/docs/dispatcher/DispatcherDocSpec.scala#defining-mailbox-in-config + +Or code like this: + +.. includecode:: ../scala/code/docs/dispatcher/DispatcherDocSpec.scala#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 extend the parameterized trait :class:`RequiresMessageQueue`. Here is +an example: + +.. includecode:: ../scala/code/docs/dispatcher/DispatcherDocSpec.scala#required-mailbox-class + +The type parameter to the :class:`RequiresMessageQueue` trait 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:`MyBoundedActor` 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:: + + The type of the queue in the mailbox created for an actor will be checked against the required type in the + trait and if the queue doesn't implement the required type then actor creation will fail. + + +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 +------------------------------ + +An example is worth a thousand quacks: + +.. includecode:: ../scala/code/docs/dispatcher/DispatcherDocSpec.scala#mailbox-implementation-example + +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:: + + 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 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`` +--------------------------------------- + +In order to make ``system.actorOf`` both synchronous and non-blocking while +keeping the return type :class:`ActorRef` (and the semantics that the returned +ref is fully functional), special handling takes place for this case. Behind +the scenes, a hollow kind of actor reference is constructed, which is sent to +the system’s guardian actor who actually creates the actor and its context and +puts those inside the reference. Until that has happened, messages sent to the +:class:`ActorRef` will be queued locally, and only upon swapping the real +filling in will they be transferred into the real mailbox. Thus, + +.. code-block:: scala + + val props: Props = ... + // this actor uses MyCustomMailbox, which is assumed to be a singleton + system.actorOf(props.withDispatcher("myCustomMailbox")) ! "bang" + assert(MyCustomMailbox.instance.getLastEnqueuedMessage == "bang") + +will probably fail; you will have to allow for some time to pass and retry the +check à la :meth:`TestKit.awaitCond`.