Merge pull request #1808 from krasserm/wip-3681-performance-improvements-krasserm

!per #3681 Performance and consistency improvements

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

@@ -225,4 +225,22 @@ trait PersistenceDocSpec {
       maxTimestamp = System.currentTimeMillis))
     //#snapshot-criteria
   }
+
+  new AnyRef {
+    import akka.actor.Props
+    //#batch-write
+    class MyProcessor extends Processor {
+      def receive = {
+        case Persistent("a", _) ⇒ // ...
+        case Persistent("b", _) ⇒ // ...
+      }
+    }
+
+    val system = ActorSystem("example")
+    val processor = system.actorOf(Props[MyProcessor])
+
+    processor ! PersistentBatch(Vector(Persistent("a"), Persistent("b")))
+    //#batch-write
+    system.shutdown()
+  }
 }

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

@@ -6,6 +6,7 @@ package docs.persistence
 
 //#plugin-imports
 import scala.concurrent.Future
+import scala.collection.immutable.Seq
 //#plugin-imports
 
 import com.typesafe.config._
@@ -69,6 +70,7 @@ class PersistencePluginDocSpec extends WordSpec {
 
 class MyJournal extends AsyncWriteJournal {
   def writeAsync(persistent: PersistentImpl): Future[Unit] = ???
+  def writeBatchAsync(persistentBatch: Seq[PersistentImpl]): Future[Unit] = ???
   def deleteAsync(persistent: PersistentImpl): Future[Unit] = ???
   def confirmAsync(processorId: String, sequenceNr: Long, channelId: String): Future[Unit] = ???
   def replayAsync(processorId: String, fromSequenceNr: Long, toSequenceNr: Long)(replayCallback: (PersistentImpl) ⇒ Unit): Future[Long] = ???

akka-docs/rst/scala/persistence.rst

@@ -331,6 +331,20 @@ The example also demonstrates how to change the processor's default behavior, de
 another behavior, defined by ``otherCommandHandler``, and back using ``context.become()`` and ``context.unbecome()``.
 See also the API docs of ``persist`` for further details.
 
+Batch writes
+============
+
+Applications may also send a batch of ``Persistent`` messages to a processor via a ``PersistentBatch`` message.
+
+.. includecode:: code/docs/persistence/PersistenceDocSpec.scala#batch-write
+
+``Persistent`` messages contained in a ``PersistentBatch`` message are written to the journal atomically but are
+received  by the processor separately (as ``Persistent`` messages). They are also replayed separately. Batch writes
+can not only increase the throughput of a processor but may also be necessary for consistency reasons. For example,
+in :ref:`event-sourcing`, all events that are generated and persisted by a single command are batch-written to the
+journal. The recovery of an ``EventsourcedProcessor`` will therefore never be done partially i.e. with only a subset
+of events persisted by a single command.
+
 Storage plugins
 ===============