Akka.Persistence plugin enables stateful actors to persist their internal state so that it can be recovered when an actor is started, restarted after a CLR crash or by a supervisor, or migrated in a cluster. The key concept behind Akka persistence is that only changes to an actor's internal state are persisted but never its current state directly (except for optional snapshots). These changes are only ever appended to storage, nothing is ever mutated, which allows for very high transaction rates and efficient replication. Stateful actors are recovered by replaying stored changes to these actors from which they can rebuild internal state. This can be either the full history of changes or starting from a snapshot which can dramatically reduce recovery times. Akka persistence also provides point-to-point communication with at-least-once message delivery semantics.
Akka.Persistence features are available through new set of actor base classes:
UntypedPersistentActor- is a persistent, stateful actor. It is able to persist events to a journal and can react to them in a thread-safe manner. It can be used to implement both command as well as event sourced actors. When a persistent actor is started or restarted, journaled messages are replayed to that actor so that it can recover internal state from these messages.
PersistentViewis a persistent, stateful actor that receives journaled messages that have been written by another persistent actor. A view itself does not journal new messages, instead, it updates internal state only from a persistent actor's replicated message stream. Note:
AtLeastOnceDeliveryActor- is an actor which sends messages with at-least-once delivery semantics to destinations, also in case of sender and receiver CLR crashes.
AsyncWriteJournalstores the sequence of messages sent to a persistent actor. An application can control which messages are journaled and which are received by the persistent actor without being journaled. Journal maintains highestSequenceNr that is increased on each message. The storage backend of a journal is pluggable. By default it uses an in-memory message stream and is NOT a persistent storage.
SnapshotStoreis used to persist snapshots of either persistent actor's or view's internal state. They can be used to reduce recovery times in case when a lot of events needs to be replayed for specific persistent actor. Storage backend of the snapshot store is pluggable. By default it uses local file system.
ReceivePersistentActor- receive actor version of
AtLeastOnceDeliveryReceiveActor- receive actor version of
Unlike the default
UntypedPersistentActor and its derivatives requires the setup of a few more additional members:
PersistenceIdis a persistent actor's identifier that doesn't change across different actor incarnations. It's used to retrieve an event stream required by the persistent actor to recover its internal state.
OnRecoveris a method invoked during an actor's recovery cycle. Incoming objects may be user-defined events as well as system messages, for example
SnapshotOfferwhich is used to deliver latest actor state saved in the snapshot store.
OnCommandis an equivalent of the basic
Receivemethod of default Akka.NET actors.
Persistent actors also offer a set of specialized members:
PersistAsyncmethods can be used to send events to the event journal in order to store them inside. The second argument is a callback invoked when the journal confirms that events have been stored successfully.
DeferAsyncis used to perform various operations after events will be persisted and their callback handlers will be invoked. Unlike the persist methods, defer won't store an event in persistent storage. Defer method may NOT be invoked in case when the actor is restarted even though the journal will successfully persist events sent.
DeleteMessageswill order attached journal to remove part of its events. It can be only physical deletion, when the messages are removed physically from the journal.
LoadSnapshotwill send a request to the snapshot store to resend the current actor's snapshot.
SaveSnapshotwill send the current actor's internal state as a snapshot to be saved by the configured snapshot store.
DeleteSnapshotsmethods may be used to specify snapshots to be removed from the snapshot store in cases where they are no longer needed.
OnReplaySuccessis a virtual method which will be called when the recovery cycle ends successfully.
OnReplayFailureis a virtual method which will be called when the recovery cycle fails unexpectedly from some reason.
IsRecoveringproperty determines if the current actor is performing a recovery cycle at the moment.
SnapshotSequenceNrproperty may be used to determine the sequence number used for marking persisted events. This value changes in a monotonically increasing manner.
In case a manual recovery cycle initialization is necessary, it may be invoked by sending a
Recover message to a persistent actor.