Merge branch 'wip-2366-document-topLevelNames-∂π'

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`.
+

akka-docs/general/supervision.rst

@@ -55,6 +55,65 @@ 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-guardian:
+
+``/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 user 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

akka-docs/java/fault-tolerance.rst

@@ -49,7 +49,7 @@ does not apply, leaving the possibility to specify an absolute upper limit on th
 restarts or to make the restarts work infinitely.
 
 Default Supervisor Strategy
----------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 ``Escalate`` is used if the defined strategy doesn't cover the exception that was thrown.
 
@@ -64,6 +64,24 @@ exceptions are handled by default:
 If the exception escalate all the way up to the root guardian it will handle it
 in the same way as the default strategy defined above.
 
+Stopping Supervisor Strategy
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Closer to the Erlang way is the strategy to just stop children when they fail
+and then take corrective action in the supervisor when DeathWatch signals the
+loss of the child. This strategy is also provided pre-packaged as
+:obj:`SupervisorStrategy.stoppingStrategy` with an accompanying
+:class:`StoppingSupervisorStrategy` configurator to be used when you want the
+``"/user"`` guardian to apply it.
+
+Supervision of Top-Level Actors
+-------------------------------
+
+Toplevel actors means those which are created using ``system.actorOf()``, and
+they are children of the :ref:`User Guardian <user-guardian>`. There are no
+special rules applied in this case, the guardian simply applies the configured
+strategy.
+
 Test Application
 ----------------
 

akka-docs/java/remoting.rst

@@ -66,6 +66,12 @@ As you can see from the example above the following pattern is used to find an `
 
     akka://<actorsystemname>@<hostname>:<port>/<actor path>
 
+Once you obtained a reference to the actor you can interact with it they same way you would with a local actor, e.g.::
+
+  actor.tell("Pretty awesome feature", getSelf());
+
+.. note::
+
   For more details on how actor addresses and paths are formed and used, please refer to :ref:`addressing`.
 
 Creating Actors Remotely
@@ -273,6 +279,16 @@ you simply register as listener to the below described types in on the ``ActorSy
     To subscribe to any inbound-related events, subscribe to ``RemoteServerLifeCycleEvent``
     To subscribe to any remote events, subscribe to ``RemoteLifeCycleEvent``
 
+By default an event listener is registered which logs all of the events
+described below. This default was chosen to help setting up a system, but it is
+quite common to switch this logging off once that phase of the project is
+finished.
+
+.. note::
+  In order to switch off the logging, set
+  ``akka.remote.log-remote-lifecycle-events = off`` in your
+  ``application.conf``.
+
 To intercept when an outbound connection is disconnected, you listen to ``RemoteClientDisconnected`` which
 holds the transport used (RemoteTransport) and the outbound address that was disconnected (Address).
 

akka-docs/java/untyped-actors.rst

@@ -22,10 +22,13 @@ its syntax from Erlang.
 Creating Actors
 ===============
 
+.. note::
+
   Since Akka enforces parental supervision every actor is supervised and
-(potentially) the supervisor of its children; it is advisable that you
+  (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`.
+  may also help to read :ref:`actorOf-vs-actorFor` (the whole of
+  :ref:`addressing` is recommended reading in any case).
 
 Defining an Actor class
 -----------------------

akka-docs/scala/actors.rst

@@ -22,10 +22,13 @@ its syntax from Erlang.
 Creating Actors
 ===============
 
+.. note::
+
   Since Akka enforces parental supervision every actor is supervised and
-(potentially) the supervisor of its children; it is advisable that you
+  (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`.
+  may also help to read :ref:`actorOf-vs-actorFor` (the whole of
+  :ref:`addressing` is recommended reading in any case).
 
 Defining an Actor class
 -----------------------

akka-docs/scala/fault-tolerance.rst

@@ -53,7 +53,7 @@ which is a ``PartialFunction[Throwable, Directive]``. This
 is the piece which maps child failure types to their corresponding directives.
 
 Default Supervisor Strategy
----------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 ``Escalate`` is used if the defined strategy doesn't cover the exception that was thrown.
 
@@ -68,6 +68,23 @@ exceptions are handled by default:
 If the exception escalate all the way up to the root guardian it will handle it
 in the same way as the default strategy defined above.
 
+Stopping Supervisor Strategy
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Closer to the Erlang way is the strategy to just stop children when they fail
+and then take corrective action in the supervisor when DeathWatch signals the
+loss of the child. This strategy is also provided pre-packaged as
+:obj:`SupervisorStrategy.stoppingStrategy` with an accompanying
+:class:`StoppingSupervisorStrategy` configurator to be used when you want the
+``"/user"`` guardian to apply it.
+
+Supervision of Top-Level Actors
+-------------------------------
+
+Toplevel actors means those which are created using ``system.actorOf()``, and
+they are children of the :ref:`User Guardian <user-guardian>`. There are no
+special rules applied in this case, the guardian simply applies the configured
+strategy.
 
 Test Application
 ----------------

akka-docs/scala/remoting.rst

@@ -77,6 +77,8 @@ Once you obtained a reference to the actor you can interact with it they same wa
 
   actor ! "Pretty awesome feature"
 
+.. note::
+
   For more details on how actor addresses and paths are formed and used, please refer to :ref:`addressing`.
 
 Creating Actors Remotely
@@ -281,6 +283,16 @@ you simply register as listener to the below described types in on the ``ActorSy
     To subscribe to any inbound-related events, subscribe to ``RemoteServerLifeCycleEvent``
     To subscribe to any remote events, subscribe to ``RemoteLifeCycleEvent``
 
+By default an event listener is registered which logs all of the events
+described below. This default was chosen to help setting up a system, but it is
+quite common to switch this logging off once that phase of the project is
+finished.
+
+.. note::
+  In order to switch off the logging, set
+  ``akka.remote.log-remote-lifecycle-events = off`` in your
+  ``application.conf``.
+
 To intercept when an outbound connection is disconnected, you listen to ``RemoteClientDisconnected`` which
 holds the transport used (RemoteTransport) and the outbound address that was disconnected (Address).
 

akka-remote/src/main/resources/reference.conf

@@ -72,7 +72,8 @@ akka {
     log-sent-messages = off
 
     # If this is "on", Akka will log all RemoteLifeCycleEvents at the level defined for each, if off then they are not logged
-    log-remote-lifecycle-events = off
+    # Failures to deserialize received messages also fall under this flag.
+    log-remote-lifecycle-events = on
 
     # Each property is annotated with (I) or (O) or (I&O), where I stands for “inbound” and O for “outbound” connections.
     # The NettyRemoteTransport always starts the server role to allow inbound connections, and it starts