document availability of sender in supervisorStrategy

akka-docs/rst/java/fault-tolerance.rst

@@ -24,6 +24,13 @@ sample as it is easy to follow the log output to understand what is happening in
 
    fault-tolerance-sample
 
+.. note::
+
+  If the strategy is declared inside the supervising actor (as opposed to
+  as a static property or class) its decider has access to all internal state of
+  the actor in a thread-safe fashion, including obtaining a reference to the
+  currently failed child (available as the ``getSender()`` of the failure message).
+
 Creating a Supervisor Strategy
 ------------------------------
 

akka-docs/rst/java/untyped-actors.rst

@@ -136,8 +136,20 @@ to have them converted into actual Debug messages).
 In addition, it offers:
 
 * :obj:`getSelf()` reference to the :class:`ActorRef` of the actor
+
 * :obj:`getSender()` reference sender Actor of the last received message, typically used as described in :ref:`UntypedActor.Reply`
+
 * :obj:`supervisorStrategy()` user overridable definition the strategy to use for supervising child actors
+
+  This strategy is typically declared inside the actor in order to have access
+  to the actor’s internal state within the decider function: since failure is
+  communicated as a message sent to the supervisor and processed like other
+  messages (albeit outside of the normal behavior), all values and variables
+  within the actor are available, as is the ``getSender()`` reference (which will
+  be the immediate child reporting the failure; if the original failure
+  occurred within a distant descendant it is still reported one level up at a
+  time).
+
 * :obj:`getContext()` exposes contextual information for the actor and the current message, such as:
 
   * factory methods to create child actors (:meth:`actorOf`)