diff --git a/akka-docs/general/addressing.rst b/akka-docs/general/addressing.rst index 424140ab96..299ad5199a 100644 --- a/akka-docs/general/addressing.rst +++ b/akka-docs/general/addressing.rst @@ -316,21 +316,36 @@ the address of this actor system, in which case it will be resolved to the actor’s local reference. Otherwise, it will be represented by a remote actor reference. -Special Paths used by Akka --------------------------- +.. _toplevel-paths: + +Top-Level Scopes for Actor Paths +-------------------------------- At the root of the path hierarchy resides the root guardian above which all -other actors are found. The next level consists of the following: +other actors are found; its name is ``"/"``. The next level consists of the +following: - ``"/user"`` is the guardian actor for all user-created top-level actors; - actors created using :meth:`ActorSystem.actorOf` are found at the next level. + actors created using :meth:`ActorSystem.actorOf` are found below this one. - ``"/system"`` is the guardian actor for all system-created top-level actors, e.g. logging listeners or actors automatically deployed by configuration at the start of the actor system. - ``"/deadLetters"`` is the dead letter actor, which is where all messages sent to - stopped or non-existing actors are re-routed. + stopped or non-existing actors are re-routed (on a best-effort basis: messages + may be lost even within the local JVM). - ``"/temp"`` is the guardian for all short-lived system-created actors, e.g. those which are used in the implementation of :meth:`ActorRef.ask`. - ``"/remote"`` is an artificial path below which all actors reside whose supervisors are remote actor references +The need to structure the name space for actors like this arises from a central +and very simple design goal: everything in the hierarchy is an actor, and all +actors function in the same way. Hence you can not only look up the actors you +created, you can also look up the system guardian and send it a message (which +it will dutifully discard in this case). This powerful principle means that +there are no quirks to remember, it makes the whole system more uniform and +consistent. + +If you want to read more about the top-level structure of an actor system, have +a look at :ref:`toplevel-supervisors`. + diff --git a/akka-docs/general/guardians.png b/akka-docs/general/guardians.png new file mode 100644 index 0000000000..67dce546f5 Binary files /dev/null and b/akka-docs/general/guardians.png differ diff --git a/akka-docs/general/supervision.rst b/akka-docs/general/supervision.rst index c1bc684ce4..75512dd03f 100644 --- a/akka-docs/general/supervision.rst +++ b/akka-docs/general/supervision.rst @@ -55,6 +55,63 @@ actors cannot be orphaned or attached to supervisors from the outside, which might otherwise catch them unawares. In addition, this yields a natural and clean shutdown procedure for (sub-trees of) actor applications. +.. _toplevel-supervisors: + +The Top-Level Supervisors +------------------------- + +.. image:: guardians.png + :align: center + :width: 360 + +An actor system will during its creation start at least three actors, shown in +the image above. For more information about the consequences for actor paths +see :ref:`toplevel-paths`. + +``/user``: The Guardian Actor +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The actor which is probably most interacted with is the parent of all +user-created actors, the guardian named ``"/user"``. Actors created using +``system.actorOf()`` are children of this actor. This means that when this +guardian terminates, all normal actors in the system will be shutdown, too. It +also means that this guardian’s supervisor strategy determines how the +top-level normal actors are supervised. Since Akka 2.1 it is possible to +configure this using the setting ``akka.actor.guardian-supervisor-strategy``, +which takes the fully-qualified class-name of a +:class:`SupervisorStrategyConfigurator`. When the guardian escalates a failure, +the root guardian’s response will be to terminate the guardian, which in effect +will shut down the whole actor system. + +``/system``: The System Guardian +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This special guardian has been introduced in order to achieve an orderly +shut-down sequence where logging remains active while all normal actors +terminate, even though logging itself is implemented using actors. This is +realized by having the system guardian watch the guardian and initiate its own +shut-down upon reception of the :class:`Terminated` message. The top-level +system actors are supervised using a strategy which will restart indefinitely +upon all types of :class:`Exception` except for +:class:`ActorInitializationException` and :class:`ActorKilledException`, which +will terminate the child in question. All other throwables are escalated, +which will shut down the whole actor system. + +``/``: The Root Guardian +^^^^^^^^^^^^^^^^^^^^^^^^ + +The root guardian is the grand-parent of all so-called “top-level” actors and +supervises all the special actors mentioned in :ref:`toplevel-paths` using the +``SupervisorStrategy.stoppingStrategy``, whose purpose is to terminate the +child upon any type of :class:`Exception`. All other throwables will be +escalated … but to whom? Since every real actor has a supervisor, the +supervisor of the root guardian cannot be a real actor. And because this means +that it is “outside of the bubble”, it is called the “bubble-walker”. This is a +synthetic :class:`ActorRef` which in effect stops its child upon the first sign +of trouble and sets the actor system’s ``isTerminated`` status to ``true`` as +soon as the root guardian is fully terminated (all children recursively +stopped). + .. _supervision-restart: What Restarting Means diff --git a/akka-docs/java/remoting.rst b/akka-docs/java/remoting.rst index 82a736973f..b356381766 100644 --- a/akka-docs/java/remoting.rst +++ b/akka-docs/java/remoting.rst @@ -61,7 +61,9 @@ As you can see from the example above the following pattern is used to find an ` akka://@:/ -For more details on how actor addresses and paths are formed and used, please refer to :ref:`addressing`. +.. note:: + + For more details on how actor addresses and paths are formed and used, please refer to :ref:`addressing`. Creating Actors Remotely ^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/akka-docs/java/untyped-actors.rst b/akka-docs/java/untyped-actors.rst index d80aa45cd7..a983a578c9 100644 --- a/akka-docs/java/untyped-actors.rst +++ b/akka-docs/java/untyped-actors.rst @@ -22,10 +22,13 @@ its syntax from Erlang. Creating Actors =============== -Since Akka enforces parental supervision every actor is supervised and -(potentially) the supervisor of its children; it is advisable that you -familiarize yourself with :ref:`actor-systems` and :ref:`supervision` and it -may also help to read :ref:`actorOf-vs-actorFor`. +.. note:: + + Since Akka enforces parental supervision every actor is supervised and + (potentially) the supervisor of its children, it is advisable that you + familiarize yourself with :ref:`actor-systems` and :ref:`supervision` and it + may also help to read :ref:`actorOf-vs-actorFor` (the whole of + :ref:`addressing` is recommended reading in any case). Defining an Actor class ----------------------- diff --git a/akka-docs/scala/actors.rst b/akka-docs/scala/actors.rst index b995c78438..548190c6fd 100644 --- a/akka-docs/scala/actors.rst +++ b/akka-docs/scala/actors.rst @@ -22,10 +22,13 @@ its syntax from Erlang. Creating Actors =============== -Since Akka enforces parental supervision every actor is supervised and -(potentially) the supervisor of its children; it is advisable that you -familiarize yourself with :ref:`actor-systems` and :ref:`supervision` and it -may also help to read :ref:`actorOf-vs-actorFor`. +.. note:: + + Since Akka enforces parental supervision every actor is supervised and + (potentially) the supervisor of its children, it is advisable that you + familiarize yourself with :ref:`actor-systems` and :ref:`supervision` and it + may also help to read :ref:`actorOf-vs-actorFor` (the whole of + :ref:`addressing` is recommended reading in any case). Defining an Actor class ----------------------- diff --git a/akka-docs/scala/remoting.rst b/akka-docs/scala/remoting.rst index ab49765fad..6a0e8731b7 100644 --- a/akka-docs/scala/remoting.rst +++ b/akka-docs/scala/remoting.rst @@ -72,7 +72,9 @@ Once you obtained a reference to the actor you can interact with it they same wa actor ! "Pretty awesome feature" -For more details on how actor addresses and paths are formed and used, please refer to :ref:`addressing`. +.. note:: + + For more details on how actor addresses and paths are formed and used, please refer to :ref:`addressing`. Creating Actors Remotely ^^^^^^^^^^^^^^^^^^^^^^^^