From d2ef2e208c2d92da968616c0d1ad8d41abfc5d6e Mon Sep 17 00:00:00 2001
From: Roland <rk@rkuhn.info>
Date: Fri, 22 Feb 2013 15:42:42 +0100
Subject: [PATCH] document availability of `sender` in supervisorStrategy

---
 .../scala/akka/actor/SupervisorMiscSpec.scala    | 16 ++++++++++++++++
 akka-docs/rst/java/fault-tolerance.rst           |  7 +++++++
 akka-docs/rst/java/untyped-actors.rst            | 12 ++++++++++++
 akka-docs/rst/scala/actors.rst                   | 12 ++++++++++++
 akka-docs/rst/scala/fault-tolerance.rst          |  7 +++++++
 5 files changed, 54 insertions(+)

diff --git a/akka-actor-tests/src/test/scala/akka/actor/SupervisorMiscSpec.scala b/akka-actor-tests/src/test/scala/akka/actor/SupervisorMiscSpec.scala
index 52b50491ee..444f5087da 100644
--- a/akka-actor-tests/src/test/scala/akka/actor/SupervisorMiscSpec.scala
+++ b/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"
+    }
   }
 }
diff --git a/akka-docs/rst/java/fault-tolerance.rst b/akka-docs/rst/java/fault-tolerance.rst
index 9cb9d234fd..74b5a0cb5f 100644
--- a/akka-docs/rst/java/fault-tolerance.rst
+++ b/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
 ------------------------------
 
diff --git a/akka-docs/rst/java/untyped-actors.rst b/akka-docs/rst/java/untyped-actors.rst
index ddbe1d0d4d..c05f2e7bce 100644
--- a/akka-docs/rst/java/untyped-actors.rst
+++ b/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`)
diff --git a/akka-docs/rst/scala/actors.rst b/akka-docs/rst/scala/actors.rst
index e913164a58..e00d3895fc 100644
--- a/akka-docs/rst/scala/actors.rst
+++ b/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`)
diff --git a/akka-docs/rst/scala/fault-tolerance.rst b/akka-docs/rst/scala/fault-tolerance.rst
index 6b6559e647..9a2d36fbe1 100644
--- a/akka-docs/rst/scala/fault-tolerance.rst
+++ b/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
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^