#15654 point out explicit actor lifecycle

akka-docs/rst/general/actors.rst

@@ -10,9 +10,13 @@ encounter while implementing it. For a more in depth reference with all the
 details please refer to
 :ref:`Actors (Scala) <actors-scala>` and :ref:`Untyped Actors (Java) <untyped-actors-java>`.
 
-An actor is a container for `State`_, `Behavior`_, a `Mailbox`_, `Children`_
+An actor is a container for `State`_, `Behavior`_, a `Mailbox`_, `Child Actors`_
 and a `Supervisor Strategy`_. All of this is encapsulated behind an `Actor
-Reference`_. Finally, this happens `When an Actor Terminates`_.
+Reference`_. One noteworthy aspect is that actors have an explicit lifecycle,
+they are not automatically destroyed when no longer referenced; after having
+created one, it is your responsibility to make sure that it will eventually be
+terminated as well—which also gives you control over how resources are released
+`When an Actor Terminates`_.
 
 Actor Reference
 ---------------
@@ -99,8 +103,8 @@ dequeued message, there is no scanning the mailbox for the next matching one.
 Failure to handle a message will typically be treated as a failure, unless this
 behavior is overridden.
 
-Children
---------
+Child Actors
+------------
 
 Each actor is potentially a supervisor: if it creates children for delegating
 sub-tasks, it will automatically supervise them. The list of children is

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

@@ -293,6 +293,13 @@ 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.
 
+.. note::
+
+   It is important to note that Actors do not stop automatically when no longer
+   referenced, every Actor that is created must also explicitly be destroyed.
+   The only simplification is that stopping a parent Actor will also recursively
+   stop all the child Actors that this parent has created.
+
 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

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

@@ -249,6 +249,13 @@ name of the new incarnation will be the same as the previous one but the
 UIDs will differ. An actor can be stopped by the actor itself, another actor
 or the ``ActorSystem`` (see :ref:`stopping-actors-java`).
 
+.. note::
+
+   It is important to note that Actors do not stop automatically when no longer
+   referenced, every Actor that is created must also explicitly be destroyed.
+   The only simplification is that stopping a parent Actor will also recursively
+   stop all the child Actors that this parent has created.
+
 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

akka-docs/rst/scala/actors.rst

@@ -286,6 +286,13 @@ name of the new incarnation will be the same as the previous one but the
 UIDs will differ. An actor can be stopped by the actor itself, another actor
 or the ``ActorSystem`` (see :ref:`stopping-actors-scala`).
 
+.. note::
+
+   It is important to note that Actors do not stop automatically when no longer
+   referenced, every Actor that is created must also explicitly be destroyed.
+   The only simplification is that stopping a parent Actor will also recursively
+   stop all the child Actors that this parent has created.
+
 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