Merge pull request #17828 from ktoso/wip-nested-persist-ktoso

~per #15640 support nested persist calls

akka-docs/rst/scala/code/docs/persistence/PersistenceDocSpec.scala

@@ -280,6 +280,103 @@ object PersistenceDocSpec {
     //#defer-caller
   }
 
+  object NestedPersists {
+
+    class MyPersistentActor extends PersistentActor {
+      override def persistenceId = "my-stable-persistence-id"
+
+      override def receiveRecover: Receive = {
+        case _ => // handle recovery here
+      }
+
+      //#nested-persist-persist
+      override def receiveCommand: Receive = {
+        case c: String =>
+          sender() ! c
+
+          persist(s"$c-1-outer") { outer1 =>
+            sender() ! outer1
+            persist(s"$c-1-inner") { inner1 =>
+              sender() ! inner1
+            }
+          }
+
+          persist(s"$c-2-outer") { outer2 =>
+            sender() ! outer2
+            persist(s"$c-2-inner") { inner2 =>
+              sender() ! inner2
+            }
+          }
+      }
+      //#nested-persist-persist
+    }
+
+    //#nested-persist-persist-caller
+    persistentActor ! "a"
+    persistentActor ! "b"
+
+    // order of received messages:
+    // a
+    // a-outer-1
+    // a-outer-2
+    // a-inner-1
+    // a-inner-2
+    // and only then process "b"
+    // b
+    // b-outer-1
+    // b-outer-2
+    // b-inner-1
+    // b-inner-2
+
+    //#nested-persist-persist-caller
+
+
+    class MyPersistAsyncActor extends PersistentActor {
+      override def persistenceId = "my-stable-persistence-id"
+
+      override def receiveRecover: Receive = {
+        case _ => // handle recovery here
+      }
+
+      //#nested-persistAsync-persistAsync
+      override def receiveCommand: Receive = {
+        case c: String =>
+          sender() ! c
+          persistAsync(c + "-outer-1") { outer ⇒
+            sender() ! outer
+            persistAsync(c + "-inner-1") { inner ⇒ sender() ! inner }
+          }
+          persistAsync(c + "-outer-2") { outer ⇒
+            sender() ! outer
+            persistAsync(c + "-inner-2") { inner ⇒ sender() ! inner }
+          }
+      }
+    //#nested-persistAsync-persistAsync
+    }
+
+    //#nested-persistAsync-persistAsync-caller
+    persistentActor ! "a"
+    persistentActor ! "b"
+
+    // order of received messages:
+    // a
+    // b
+    // a-outer-1
+    // a-outer-2
+    // b-outer-1
+    // b-outer-2
+    // a-inner-1
+    // a-inner-2
+    // b-inner-1
+    // b-inner-2
+
+    // which can be seen as the following causal relationship:
+    // a -> a-outer-1 -> a-outer-2 -> a-inner-1 -> a-inner-2
+    // b -> b-outer-1 -> b-outer-2 -> b-inner-1 -> b-inner-2
+
+    //#nested-persistAsync-persistAsync-caller
+  }
+
   object View {
     import akka.actor.Props