!per Make persistent failures fatal

* remove PersistentFailure and RecoveryFailure messages
* use stop instead of ActorKilledException
* adjust PersistentView
* adjust AtLeastOnceDeliveryFailureSpec
* adjust sharding
* add BackoffSupervisor

akka-docs/rst/scala/cluster-sharding.rst

@@ -265,7 +265,7 @@ the ``rememberEntities`` flag to true in ``ClusterShardingSettings`` when callin
 ``ClusterSharding.start``. When configured to remember entities, whenever a ``Shard`` 
 is rebalanced onto another node or recovers after a crash it will recreate all the
 entities which were previously running in that ``Shard``. To permanently stop entities, 
-a ``Passivate`` message must be sent to the parent the ``Shard``, otherwise the
+a ``Passivate`` message must be sent to the parent of the entity actor, otherwise the
 entity will be automatically restarted after the entity restart backoff specified in 
 the configuration.
 

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

@@ -100,6 +100,23 @@ object PersistenceDocSpec {
     }
   }
 
+  object Backoff {
+    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)
+      context.actorOf(props, name = "mySupervisor")
+      //#backoff
+    }
+
+  }
+
   object AtLeastOnce {
     //#at-least-once-example
     import akka.actor.{ Actor, ActorPath }
@@ -288,4 +305,4 @@ object PersistenceDocSpec {
     //#view-update
   }
 
-}
+}

akka-docs/rst/scala/persistence.rst

@@ -123,9 +123,14 @@ When persisting events with ``persist`` it is guaranteed that the persistent act
 the ``persist`` call and the execution(s) of the associated event handler. This also holds for multiple ``persist``
 calls in context of a single command.
 
-If persistence of an event fails, the persistent actor will be stopped by throwing :class:`ActorKilledException`.
-This can be customized by handling ``PersistenceFailure`` message in ``receiveCommand`` and/or defining 
-``supervisorStrategy`` in parent actor.
+If persistence of an event fails, ``onPersistFailure`` will be invoked (logging the error by default)
+and the actor will unconditionally be stopped. The reason that it cannot resume when persist fails
+is that it is unknown if the even was actually persisted or not, and therefore it is in an inconsistent
+state. Restarting on persistent failures will most likely fail anyway, since the journal is probably
+unavailable. It is better to stop the actor and after a back-off timeout start it again. The
+``akka.persistence.BackoffSupervisor`` actor is provided to support such restarts.
+
+.. includecode:: code/docs/persistence/PersistenceDocSpec.scala#backoff
 
 The easiest way to run this example yourself is to download `Typesafe Activator <http://www.typesafe.com/platform/getstarted>`_
 and open the tutorial named `Akka Persistence Samples with Scala <http://www.typesafe.com/activator/template/akka-sample-persistence-scala>`_.
@@ -201,9 +206,8 @@ and before any other received messages.
 
 .. includecode:: code/docs/persistence/PersistenceDocSpec.scala#recovery-completed
 
-If there is a problem with recovering the state of the actor from the journal, the actor will be 
-sent a :class:`RecoveryFailure` message that it can choose to handle in ``receiveRecover``. If the
-actor doesn't handle the :class:`RecoveryFailure` message it will be stopped by throwing :class:`ActorKilledException`.
+If there is a problem with recovering the state of the actor from the journal, the error will be logged and the
+actor will be stopped. 
 
 .. _persist-async-scala: