#19246 Auto and manual reset and BackoffOptions.

Also moved `TransparantExponentialBackoffSupervisor` to `akka.pattern` (renamed to `BackoffOnRestartSupervisor`)

akka-docs/rst/scala/code/docs/pattern/BackoffSupervisorDocSpec.scala

@@ -4,28 +4,99 @@
 
 package docs.pattern
 
-import akka.actor.{ ActorSystem, Props }
-import akka.pattern.BackoffSupervisor
+import akka.actor.{ ActorSystem, Props, OneForOneStrategy, SupervisorStrategy }
+import akka.pattern.{ Backoff, BackoffSupervisor }
 import akka.testkit.TestActors.EchoActor
 
 class BackoffSupervisorDocSpec {
 
-  class BackoffSupervisorDocSpecExample {
+  class BackoffSupervisorDocSpecExampleStop {
     val system: ActorSystem = ???
     import scala.concurrent.duration._
 
-    //#backoff
+    //#backoff-stop
     val childProps = Props(classOf[EchoActor])
 
     val supervisor = BackoffSupervisor.props(
-      childProps,
-      childName = "myEcho",
-      minBackoff = 3.seconds,
-      maxBackoff = 30.seconds,
-      randomFactor = 0.2) // adds 20% "noise" to vary the intervals slightly
+      Backoff.onStop(
+        childProps,
+        childName = "myEcho",
+        minBackoff = 3.seconds,
+        maxBackoff = 30.seconds,
+        randomFactor = 0.2 // adds 20% "noise" to vary the intervals slightly
+        ))
 
     system.actorOf(supervisor, name = "echoSupervisor")
-    //#backoff
+    //#backoff-stop
   }
 
+  class BackoffSupervisorDocSpecExampleFail {
+    val system: ActorSystem = ???
+    import scala.concurrent.duration._
+
+    //#backoff-fail
+    val childProps = Props(classOf[EchoActor])
+
+    val supervisor = BackoffSupervisor.props(
+      Backoff.onFailure(
+        childProps,
+        childName = "myEcho",
+        minBackoff = 3.seconds,
+        maxBackoff = 30.seconds,
+        randomFactor = 0.2 // adds 20% "noise" to vary the intervals slightly
+        ))
+
+    system.actorOf(supervisor, name = "echoSupervisor")
+    //#backoff-fail
+  }
+
+  class BackoffSupervisorDocSpecExampleStopOptions {
+    val system: ActorSystem = ???
+    import scala.concurrent.duration._
+
+    val childProps = Props(classOf[EchoActor])
+
+    //#backoff-custom-stop
+    val supervisor = BackoffSupervisor.props(
+      Backoff.onStop(
+        childProps,
+        childName = "myEcho",
+        minBackoff = 3.seconds,
+        maxBackoff = 30.seconds,
+        randomFactor = 0.2 // adds 20% "noise" to vary the intervals slightly
+        ).withManualReset // the child must send BackoffSupervisor.Reset to its parent
+        .withDefaultStoppingStrategy // Stop at any Exception thrown
+        )
+    //#backoff-custom-stop
+
+    system.actorOf(supervisor, name = "echoSupervisor")
+  }
+
+  class BackoffSupervisorDocSpecExampleFailureOptions {
+    val system: ActorSystem = ???
+    import scala.concurrent.duration._
+
+    val childProps = Props(classOf[EchoActor])
+
+    //#backoff-custom-fail
+    val supervisor = BackoffSupervisor.props(
+      Backoff.onFailure(
+        childProps,
+        childName = "myEcho",
+        minBackoff = 3.seconds,
+        maxBackoff = 30.seconds,
+        randomFactor = 0.2 // adds 20% "noise" to vary the intervals slightly
+        ).withAutoReset(10.seconds) // the child must send BackoffSupervisor.Reset to its parent
+        .withSupervisorStrategy(
+          OneForOneStrategy() {
+            case _: MyException ⇒ SupervisorStrategy.Restart
+            case _              ⇒ SupervisorStrategy.Escalate
+          }))
+    //#backoff-custom-fail
+
+    system.actorOf(supervisor, name = "echoSupervisor")
+  }
+
+  case class MyException(msg: String) extends Exception(msg)
+
 }

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

@@ -5,7 +5,7 @@
 package docs.persistence
 
 import akka.actor._
-import akka.pattern.BackoffSupervisor
+import akka.pattern.{ Backoff, BackoffSupervisor }
 import akka.persistence._
 import akka.stream.ActorMaterializer
 import akka.stream.scaladsl.{ Source, Sink, Flow }
@@ -85,17 +85,18 @@ object PersistenceDocSpec {
     }
   }
 
-  object Backoff {
+  object BackoffOnStop {
     abstract class MyActor extends Actor {
       import PersistAsync.MyPersistentActor
       //#backoff
       val childProps = Props[MyPersistentActor]
       val props = BackoffSupervisor.props(
-        childProps,
-        childName = "myActor",
-        minBackoff = 3.seconds,
-        maxBackoff = 30.seconds,
-        randomFactor = 0.2)
+        Backoff.onStop(
+          childProps,
+          childName = "myActor",
+          minBackoff = 3.seconds,
+          maxBackoff = 30.seconds,
+          randomFactor = 0.2))
       context.actorOf(props, name = "mySupervisor")
       //#backoff
     }