Merge pull request #1335 from akka/wip-3222-DeathPact-∂π

clean up DeathWatch semantics, see #3222

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

@@ -196,9 +196,10 @@ monitoring of an already terminated actor leads to the immediate generation of
 the :class:`Terminated` message.
 
 It is also possible to deregister from watching another actor’s liveliness
-using ``context.unwatch(target)``, but obviously this cannot guarantee
-non-reception of the :class:`Terminated` message because that may already have
-been queued.
+using ``getContext().unwatch(target)``. This works even if the
+:class:`Terminated` message has already been enqueued in the mailbox; after
+calling :meth:`unwatch` no :class:`Terminated` message for that actor will be
+processed anymore.
 
 Start Hook
 ----------

akka-docs/rst/project/migration-guide-2.1.x-2.2.x.rst

@@ -236,10 +236,39 @@ Instead, use actorSelection followed by identify request, and watch the verified
     case Terminated(`ref`) => // ...
   }
 
-
-
 Use ``watch`` instead of ``isTerminated``
 =========================================
 
 ``ActorRef.isTerminated`` is deprecated in favor of ``ActorContext.watch`` because
 ``isTerminated`` behaves differently for local and remote actors.
+
+DeathWatch Semantics are Simplified
+===================================
+
+DeathPactException is now Fatal
+-------------------------------
+
+Previously an unhandled :class:`Terminated` message which led to a
+:class:`DeathPactException` to the thrown would be answered with a ``Restart``
+directive by the default supervisor strategy. This is not intuitive given the
+name of the exception and the Erlang linking feature by which it was inspired.
+The default strategy has thus be changed to return ``Stop`` in this case.
+
+It can be argued that previously the actor would likely run into a restart loop
+because watching a terminated actor would lead to a :class:`DeathPactException`
+immediately again.
+
+Unwatching now Prevents Reception of Terminated
+-----------------------------------------------
+
+Previously calling :meth:`ActorContext.unwatch` would unregister lifecycle
+monitoring interest, but if the target actor had terminated already the
+:class:`Terminated` message had already been enqueued and would be received
+later—possibly leading to a :class:`DeathPactException`. This behavior has been
+modified such that the :class:`Terminated` message will be silently discarded
+if :meth:`unwatch` is called before processing the :class:`Terminated`
+message. Therefore the following is now safe::
+
+  context.stop(target)
+  context.unwatch(target)
+

akka-docs/rst/scala/actors.rst

@@ -310,9 +310,9 @@ monitoring of an already terminated actor leads to the immediate generation of
 the :class:`Terminated` message.
 
 It is also possible to deregister from watching another actor’s liveliness
-using ``context.unwatch(target)``, but obviously this cannot guarantee
-non-reception of the :class:`Terminated` message because that may already have
-been queued.
+using ``context.unwatch(target)``. This works even if the :class:`Terminated`
+message has already been enqueued in the mailbox; after calling :meth:`unwatch`
+no :class:`Terminated` message for that actor will be processed anymore.
 
 Start Hook
 ----------