diff --git a/akka-docs/rst/images/actor_lifecycle.png b/akka-docs/rst/images/actor_lifecycle.png new file mode 100644 index 0000000000..ba7d568cae Binary files /dev/null and b/akka-docs/rst/images/actor_lifecycle.png differ diff --git a/akka-docs/rst/images/actor_lifecycle.svg b/akka-docs/rst/images/actor_lifecycle.svg new file mode 100644 index 0000000000..cd555f3887 --- /dev/null +++ b/akka-docs/rst/images/actor_lifecycle.svg @@ -0,0 +1,500 @@ + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + ActorInstance + + NewInstance + + Restart + ● preRestart()called on old instance + + ● new instance replaces old● postRestart()called on new instance + Resume + + Actor incarnation + ● Belongs to a path● Has a UID● Has a Mailbox + actorOf(...) + ● path is reserved● random UID is assigned to incarnation● actor instance is created● preStart() is called on instance + Stop orcontext.stop() orPosionPill + ● postStop() is called on instance● Terminated is sent to watchers● path is allowed to be used again + ActorRef + ● Represents the incarnation● Hides the instance● Has a path● Has a UID + ActorPath + + Identify + ActorIdentity + + + + Empty path + + + + ActorSelection + ● Represents a path (or multiple with wildcards)● Allows resolving the underlying ActorRef by sending an Identify message + diff --git a/akka-docs/rst/java/untyped-actors.rst b/akka-docs/rst/java/untyped-actors.rst index c2220affe7..00cb8885cc 100644 --- a/akka-docs/rst/java/untyped-actors.rst +++ b/akka-docs/rst/java/untyped-actors.rst @@ -241,6 +241,41 @@ described in the following: The implementations shown above are the defaults provided by the :class:`UntypedActor` class. +Actor Lifecycle +--------------- + +.. image:: ../images/actor_lifecycle.png + :align: center + :width: 680 + +A path in an actor system represents a "place" which might be occupied +by a living actor. Initially (apart from system initialized actors) a path is +empty. When ``actorOf()`` is called it assigns an *incarnation* of the actor +described by the passed ``Props`` to the given path. An actor incarnation is +identified by the path *and a UID*. A restart only swaps the ``Actor`` +instance defined by the ``Props`` but the incarnation and hence the UID remains +the same. + +The lifecycle of an incarnation ends when the actor is stopped. At +that point the appropriate lifecycle events are called and watching actors +are notified of the termination. After the incarnation is stopped, the path can +be reused again by creating an actor with ``actorOf()``. In this case the +name of the new incarnation will be the same as the previous one but the +UIDs will differ. + +An ``ActorRef`` always represents an incarnation (path and UID) not just a +given path. Therefore if an actor is stopped and a new one with the same +name is created an ``ActorRef`` of the old incarnation will not point +to the new one. + +``ActorSelection`` on the other hand points to the path (or multiple paths +if wildcards are used) and is completely oblivious to which incarnation is currently +occupying it. ``ActorSelection`` cannot be watched for this reason. It is +possible to resolve the current incarnation's ``ActorRef`` living under the +path by sending an ``Identify`` message to the ``ActorSelection`` which +will be replied to with an ``ActorIdentity`` containing the correct reference +(see :ref:`actorSelection-java`). + .. _deathwatch-java: Lifecycle Monitoring aka DeathWatch diff --git a/akka-docs/rst/scala/actors.rst b/akka-docs/rst/scala/actors.rst index 2b9b83f604..c526d14e5b 100644 --- a/akka-docs/rst/scala/actors.rst +++ b/akka-docs/rst/scala/actors.rst @@ -330,6 +330,41 @@ described in the following: The implementations shown above are the defaults provided by the :class:`Actor` trait. +Actor Lifecycle +--------------- + +.. image:: ../images/actor_lifecycle.png + :align: center + :width: 680 + +A path in an actor system represents a "place" which might be occupied +by a living actor. Initially (apart from system initialized actors) a path is +empty. When ``actorOf()`` is called it assigns an *incarnation* of the actor +described by the passed ``Props`` to the given path. An actor incarnation is +identified by the path *and a UID*. A restart only swaps the ``Actor`` +instance defined by the ``Props`` but the incarnation and hence the UID remains +the same. + +The lifecycle of an incarnation ends when the actor is stopped. At +that point the appropriate lifecycle events are called and watching actors +are notified of the termination. After the incarnation is stopped, the path can +be reused again by creating an actor with ``actorOf()``. In this case the +name of the new incarnation will be the same as the previous one but the +UIDs will differ. + +An ``ActorRef`` always represents an incarnation (path and UID) not just a +given path. Therefore if an actor is stopped and a new one with the same +name is created an ``ActorRef`` of the old incarnation will not point +to the new one. + +``ActorSelection`` on the other hand points to the path (or multiple paths +if wildcards are used) and is completely oblivious to which incarnation is currently +occupying it. ``ActorSelection`` cannot be watched for this reason. It is +possible to resolve the current incarnation's ``ActorRef`` living under the +path by sending an ``Identify`` message to the ``ActorSelection`` which +will be replied to with an ``ActorIdentity`` containing the correct reference +(see :ref:`actorSelection-scala`). + .. _deathwatch-scala: Lifecycle Monitoring aka DeathWatch