document availability of sender in supervisorStrategy

akka-actor-tests/src/test/scala/akka/actor/SupervisorMiscSpec.scala

@@ -142,5 +142,21 @@ class SupervisorMiscSpec extends AkkaSpec(SupervisorMiscSpec.config) with Defaul
       }
     }
 
+    "have access to the failing child’s reference in supervisorStrategy" in {
+      val parent = system.actorOf(Props(new Actor {
+        override val supervisorStrategy = OneForOneStrategy() {
+          case _: Exception ⇒ testActor ! sender; SupervisorStrategy.Stop
+        }
+        def receive = {
+          case "doit" ⇒ context.actorOf(Props.empty, "child") ! Kill
+        }
+      }))
+      EventFilter[ActorKilledException](occurrences = 1) intercept {
+        parent ! "doit"
+      }
+      val p = expectMsgType[ActorRef].path
+      p.parent must be === parent.path
+      p.name must be === "child"
+    }
   }
 }

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`)

akka-docs/rst/scala/actors.rst

@@ -240,8 +240,20 @@ actual Debug messages).
 In addition, it offers:
 
 * :obj:`self` reference to the :class:`ActorRef` of the actor
+
 * :obj:`sender` reference sender Actor of the last received message, typically used as described in :ref:`Actor.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 ``sender`` 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:`context` exposes contextual information for the actor and the current message, such as:
 
   * factory methods to create child actors (:meth:`actorOf`)

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

@@ -49,6 +49,13 @@ The match statement which forms the bulk of the body is of type ``Decider``,
 which is a ``PartialFunction[Throwable, Directive]``. This
 is the piece which maps child failure types to their corresponding directives.
 
+.. note::
+
+  If the strategy is declared inside the supervising actor (as opposed to
+  within a companion object) 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 ``sender`` of the failure message).
+
 Default Supervisor Strategy
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^