diff --git a/akka-docs/general/addressing.rst b/akka-docs/general/addressing.rst index 94e571264d..424140ab96 100644 --- a/akka-docs/general/addressing.rst +++ b/akka-docs/general/addressing.rst @@ -247,6 +247,30 @@ Summary: ``actorOf`` vs. ``actorFor`` - ``actorFor`` only ever looks up an existing actor, i.e. does not create one. +Reusing Actor Paths +------------------- + +When an actor is terminated, its path will point to the dead letter mailbox, +DeathWatch will publish its final transition and in general it is not expected +to come back to life again (since the actor life cycle does not allow this). +While it is possible to create an actor at a later time with an identical +path—simply due to it being impossible to enforce the opposite without keeping +the set of all actors ever created available—this is not good practice: remote +actor references which “died” suddenly start to work again, but without any +guarantee of ordering between this transition and any other event, hence the +new inhabitant of the path may receive messages which were destined for the +previous tenant. + +It may be the right thing to do in very specific circumstances, but make sure +to confine the handling of this precisely to the actor’s supervisor, because +that is the only actor which can reliably detect proper deregistration of the +name, before which creation of the new child will fail. + +It may also be required during testing, when the test subject depends on being +instantiated at a specific path. In that case it is best to mock its supervisor +so that it will forward the Terminated message to the appropriate point in the +test procedure, enabling the latter to await proper deregistration of the name. + The Interplay with Remote Deployment ------------------------------------ diff --git a/akka-docs/java/untyped-actors.rst b/akka-docs/java/untyped-actors.rst index 89553f091a..38d2d4c430 100644 --- a/akka-docs/java/untyped-actors.rst +++ b/akka-docs/java/untyped-actors.rst @@ -506,6 +506,18 @@ termination of several actors: .. includecode:: code/akka/docs/actor/UntypedActorDocTestBase.java :include: import-gracefulStop,gracefulStop +When ``gracefulStop()`` returns successfully, the actor’s ``postStop()`` hook +will have been executed: there exists a happens-before edge between the end of +``postStop()`` and the return of ``gracefulStop()``. + +.. warning:: + + Keep in mind that an actor stopping and its name being deregistered are + separate events which happen asynchronously from each other. Therefore it may + be that you will find the name still in use after ``gracefulStop()`` + returned. In order to guarantee proper deregistration, only reuse names from + within a supervisor you control and only in response to a :class:`Terminated` + message, i.e. not for top-level actors. .. _UntypedActor.HotSwap: diff --git a/akka-docs/scala/actors.rst b/akka-docs/scala/actors.rst index fae84c080f..5374c8a37c 100644 --- a/akka-docs/scala/actors.rst +++ b/akka-docs/scala/actors.rst @@ -550,6 +550,18 @@ termination of several actors: .. includecode:: code/akka/docs/actor/ActorDocSpec.scala#gracefulStop +When ``gracefulStop()`` returns successfully, the actor’s ``postStop()`` hook +will have been executed: there exists a happens-before edge between the end of +``postStop()`` and the return of ``gracefulStop()``. + +.. warning:: + + Keep in mind that an actor stopping and its name being deregistered are + separate events which happen asynchronously from each other. Therefore it may + be that you will find the name still in use after ``gracefulStop()`` + returned. In order to guarantee proper deregistration, only reuse names from + within a supervisor you control and only in response to a :class:`Terminated` + message, i.e. not for top-level actors. .. _Actor.HotSwap: