Merge pull request #24346 from akka/wip-22776-gracefulStop-patriknw

=typ Examples how to stop actor with cleanup (#22776)

akka-docs/src/main/paradox/actor-lifecycle-typed.md

@@ -0,0 +1,38 @@
+# Actor lifecycle
+
+TODO intro
+
+## Creating Actors
+
+TODO
+
+## Stopping Actors
+
+An actor can stop itself by returning `Behaviors.stopped` as the next behavior.
+
+Child actors can be forced to be stopped after it finishes processing its current message by using the
+`stop` method of the `ActorContext` from the parent actor. Only child actors can be stopped in that way.
+
+The child actors will be stopped as part of the shutdown procedure of the parent.
+
+The `PostStop` signal that results from stopping an actor can be used for cleaning up resources. Note that
+a behavior that handles such `PostStop` signal can optionally be defined as a parameter to `Behaviors.stopped`
+if different actions is needed when the actor gracefully stops itself from when it is stopped abruptly.
+
+Here is an illustrating example:
+
+Scala
+:  @@snip [IntroSpec.scala]($akka$/akka-actor-typed-tests/src/test/scala/docs/akka/typed/GracefulStopDocSpec.scala) {
+    #imports
+    #master-actor
+    #worker-actor
+    #graceful-shutdown
+  }
+
+Java
+:  @@snip [IntroSpec.scala]($akka$/akka-actor-typed-tests/src/test/java/jdocs/akka/typed/GracefulStopDocTest.java)  {
+   #imports
+   #master-actor
+   #worker-actor
+   #graceful-shutdown
+ }

akka-docs/src/main/paradox/index-typed.md

@@ -6,6 +6,7 @@
 
 * [actors](actors-typed.md)
 * [coexisting](coexisting.md)
+* [actor-lifecycle](actor-lifecycle-typed.md)
 * [fault-tolerance](fault-tolerance-typed.md)
 * [actor-discovery](actor-discovery-typed.md)
 * [cluster](cluster-typed.md)
@@ -13,4 +14,4 @@
 * [persistence](persistence-typed.md)
 * [testing](testing-typed.md)
 
-@@@
+@@@