Namespace Akka.DistributedData

Classes

Changed

The data value is retrieved with Data using the typed key.

Delete

Send this message to the local Akka.DistributedData.Replicator to delete a data value for the given Key. The Akka.DistributedData.Replicator will reply with one of the IDeleteResponse messages.

DistributedData

Akka extension for convenient configuration and use of the Akka.DistributedData.Replicator. Configuration settings are defined in the akka.cluster.ddata section, see reference.conf.

Dsl

A helper class used to simplify creation of messages send through the Akka.DistributedData.Replicator.

Flag

Implements a boolean flag CRDT that is initialized to false and can be switched to true. true wins over false in merge.

This class is immutable, i.e. "modifying" methods return a new instance.

FlagKey

A typed key for Flag CRDT. Can be used to perform read/upsert/delete operations on correlated data type.

FlushChanges

Notify subscribers of changes now, otherwise they will be notified periodically with the configured notify-subscribers-interval.

GCounter

Implements a 'Growing Counter' CRDT, also called a 'G-Counter'.

It is described in the paper A comprehensive study of Convergent and Commutative Replicated Data Types.

A G-Counter is a increment-only counter (inspired by vector clocks) in which only increment and merge are possible. Incrementing the counter adds 1 to the count for the current node. Divergent histories are resolved by taking the maximum count for each node (like a vector clock merge). The value of the counter is the sum of all node counts.

This class is immutable, i.e. "modifying" methods return a new instance.

GCounterKey

A typed key for GCounter CRDT. Can be used to perform read/upsert/delete operations on correlated data type.

Get

Send this message to the local Akka.DistributedData.Replicator to retrieve a data value for the given key. The Replicator will reply with one of the IGetResponse messages.

The optional request context is included in the reply messages. This is a convenient way to pass contextual information (e.g. original sender) without having to use ask or maintain local correlation data structures.

GetFailure

The Get<T>(IKey<T>) request could not be fulfill according to the given IReadConsistency level and Timeout timeout.

GetKeyIds

GetKeysIdsResult

GetReplicaCount

Get current number of replicas, including the local replica. Will reply to sender with ReplicaCount.

GetSuccess

GSet

GSet helper methods.

GSet<T>

Implements a 'Add Set' CRDT, also called a 'G-Set'. You can't remove elements of a G-Set.

It is described in the paper A comprehensive study of Convergent and Commutative Replicated Data Types.

A G-Set doesn't accumulate any garbage apart from the elements themselves.

This class is immutable, i.e. "modifying" methods return a new instance.

GSetKey<T>

TBD

Key<T>

Key for the key-value data in Akka.DistributedData.Replicator. The type of the data value is defined in the key. KeySet are compared equal if the id strings are equal, i.e. use unique identifiers.

Specific classes are provided for the built in data types, e.g. ORSetKey<T>, and you can create your own keys.

LWWDictionary

A static class with various constructor methods for LWWDictionary<TKey, TValue>.

LWWDictionary<TKey, TValue>

Specialized LWWDictionary<TKey, TValue> with LWWRegister<T> values.

LWWRegister<T> relies on synchronized clocks and should only be used when the choice of value is not important for concurrent updates occurring within the clock skew. Instead of using timestamps based on DateTime.UtcNow.Ticks time it is possible to use a timestamp value based on something else, for example an increasing version number from a database record that is used for optimistic concurrency control. For first-write-wins semantics you can use the ReverseClock instead of the DefaultClock

This class is immutable, i.e. "modifying" methods return a new instance.

LWWDictionaryKey<TKey, TValue>

Typed key used to store LWWDictionary<TKey, TValue> replica inside current Akka.DistributedData.Replicator key-value store.

LWWRegister<T>

Implements a 'Last Writer Wins Register' CRDT, also called a 'LWW-Register'.

It is described in the paper A comprehensive study of Convergent and Commutative Replicated Data Types.

Merge takes the register with highest timestamp. Note that this relies on synchronized clocks. LWWRegister<T> should only be used when the choice of value is not important for concurrent updates occurring within the clock skew.

Merge takes the register updated by the node with lowest address (UniqueAddress is ordered) if the timestamps are exactly the same.

Instead of using timestamps based on DateTime.UtcNow time it is possible to use a timestamp value based on something else, for example an increasing version number from a database record that is used for optimistic concurrency control.

For first-write-wins semantics you can use the ReverseClock instead of the [[LWWRegister#defaultClock]]

This class is immutable, i.e. "modifying" methods return a new instance.

LWWRegisterKey<T>

Key types for LWWRegister<T>

ModifyFailure

If the modify function of the Update throws an exception the reply message will be this ModifyFailure message. The original exception is included as Cause.

MultiVersionVector

NotFound

ORDictionary

ORDictionary<TKey, TValue>

Implements a 'Observed Remove Map' CRDT, also called a 'OR-Map'.

It has similar semantics as an ORSet<T>, but in case of concurrent updates the values are merged, and must therefore be IReplicatedData types themselves.

This class is immutable, i.e. "modifying" methods return a new instance.

ORDictionaryKey<TKey, TValue>

ORMultiValueDictionary<TKey, TValue>

An immutable multi-map implementation. This class wraps an ORDictionary<TKey, TValue> with an ORSet<T> for the map's value.

This class is immutable, i.e. "modifying" methods return a new instance.

ORMultiValueDictionaryKey<TKey, TValue>

ORSet

ORSet<T>

Implements a 'Observed Remove Set' CRDT, also called a 'OR-Set'. Elements can be added and removed any number of times. Concurrent add wins over remove.

It is not implemented as in the paper A comprehensive study of Convergent and Commutative Replicated Data Types. This is more space efficient and doesn't accumulate garbage for removed elements. It is described in the paper An optimized conflict-free replicated set The implementation is inspired by the Riak DT riak_dt_orswot.

The ORSet has a version vector that is incremented when an element is added to the set. The node -> count pair for that increment is stored against the element as its "birth dot". Every time the element is re-added to the set, its "birth dot" is updated to that of the node -> count version vector entry resulting from the add. When an element is removed, we simply drop it, no tombstones.

When an element exists in replica A and not replica B, is it because A added it and B has not yet seen that, or that B removed it and A has not yet seen that? In this implementation we compare the dot of the present element to the version vector in the Set it is absent from. If the element dot is not "seen" by the Set version vector, that means the other set has yet to see this add, and the item is in the merged Set. If the Set version vector dominates the dot, that means the other Set has removed this element already, and the item is not in the merged Set.

This class is immutable, i.e. "modifying" methods return a new instance.

ORSetKey<T>

PNCounter

Implements a 'Increment/Decrement Counter' CRDT, also called a 'PN-Counter'.

It is described in the paper A comprehensive study of Convergent and Commutative Replicated Data Types.

PN-Counters allow the counter to be incremented by tracking the increments (P) separate from the decrements (N). Both P and N are represented as two internal [[GCounter]]s. Merge is handled by merging the internal P and N counters. The value of the counter is the value of the P _counter minus the value of the N counter.

This class is immutable, i.e. "modifying" methods return a new instance.

PNCounterDictionary<TKey>

Map of named counters. Specialized ORDictionary<TKey, TValue> with PNCounter values. This class is immutable, i.e. "modifying" methods return a new instance.

PNCounterDictionaryKey<T>

PNCounterKey

ReadAll

ReadFrom

ReadLocal

ReadMajority

ReadMajorityPlus

ReadMajority but with the given number of Additional nodes added to the majority count. At most all nodes. Exiting nodes are excluded using ReadMajorityPlus because those are typically about to be removed and will not be able to respond.

ReplicaCount

Current number of replicas. Reply to GetReplicaCount.

ReplicationDeleteFailure

ReplicatorSettings

SingleVersionVector

StoreFailure

The local store or direct replication of the Update could not be fulfill according to the given IWriteConsistency due to durable store errors. This is only used for entries that have been configured to be durable.

The Update was still performed in memory locally and possibly replicated to some nodes, but it might not have been written to durable storage. It will eventually be disseminated to other replicas, unless the local replica crashes before it has been able to communicate with other replicas.

Register a subscriber that will be notified with a Changed message when the value of the given Key is changed. Current value is also sent as a Changed message to a new subscriber.

Subscribers will be notified periodically with the configured notify-subscribers-interval, and it is also possible to send an explicit FlushChanges message to the Akka.DistributedData.Replicator to notify the subscribers immediately.

The subscriber will automatically be unregistered if it is terminated.

If the key is deleted the subscriber is notified with a DataDeleted message.

Unsubscribe

Unregister a subscriber.

Update

Send this message to the local Akka.DistributedData.Replicator to update a data value for the given Key. The Akka.DistributedData.Replicator will reply with one of the IUpdateResponse messages.

The current data value for the Key is passed as parameter to the Modify function. It is null if there is no value for the Key, and otherwise Request. The function is supposed to return the new value of the data, which will then be replicated according to the given IWriteConsistency.

The Modify function is called by the <xref href="Akka.DistributedData.Replicator" data-throw-if-not-resolved="false"></xref> actor and must therefore be a pure function that only uses the data parameter and stable fields from enclosing scope. It must for example not access sender() reference of an enclosing actor.

UpdateSuccess

UpdateTimeout

The direct replication of the Update could not be fulfill according to the given IWriteConsistency level and Timeout.

The Update was still performed locally and possibly replicated to some nodes. It will eventually be disseminated to other replicas, unless the local replica crashes before it has been able to communicate with other replicas.

VersionVector

Representation of a Vector-based clock (counting clock), inspired by Lamport logical clocks. Based on code from VectorClock.

This class is immutable, i.e. "modifying" methods return a new instance.

WriteAll

WriteLocal

WriteMajority

WriteMajorityPlus

WriteMajority but with the given number of Additional nodes added to the majority count. At most all nodes. Exiting nodes are excluded using WriteMajorityPlus because those are typically about to be removed and will not be able to respond.

WriteTo

Interfaces

IDeleteResponse

A response for a possible Delete request message. It can be one of 3 possible cases:

DeleteSuccessReturned when data was deleted successfully.
ReplicationDeleteFailureReturned when delete operation ended with failure.
DataDeletedReturned when an operation attempted to delete already deleted data.

IDeltaReplicatedData

IReplicatedData with additional support for delta-CRDT replication. delta-CRDT is a way to reduce the need for sending the full state for updates. For example adding element 'c' and 'd' to set {'a', 'b'} would result in sending the delta {'c', 'd'} and merge that with the state on the receiving side, resulting in set {'a', 'b', 'c', 'd'}.

Learn more about this in the paper Delta State Replicated Data Types.

IDeltaReplicatedData<T, TDelta>

IReplicatedData<T> with additional support for delta-CRDT replication. delta-CRDT is a way to reduce the need for sending the full state for updates. For example adding element 'c' and 'd' to set {'a', 'b'} would result in sending the delta {'c', 'd'} and merge that with the state on the receiving side, resulting in set {'a', 'b', 'c', 'd'}.

Learn more about this in the paper Delta State Replicated Data Types.

IGetResponse

Common response interface on Get<T>(IKey<T>) request. It can take one of the tree possible values:

GetSuccess with the result of the request.
NotFound when a value for requested key didn't exist.
GetFailure when an exception happened when fulfilling the request.

IKey

Marker interface for all replicated key types in DData.

IKey<T>

TBD

IPruningState

IReadConsistency

IRemovedNodePruning

IRemovedNodePruning<T>

IReplicatedData that has support for pruning of data belonging to a specific node may implement this interface. When a node is removed from the cluster these methods will be used by the Akka.DistributedData.Replicator to collapse data from the removed node into some other node in the cluster.

IReplicatedData

IReplicatedData<T>

Interface for implementing a state based convergent replicated data type (CvRDT).

ReplicatedData types must be serializable with an Akka Serializer. It is highly recommended to implement a serializer with Protobuf or similar. The built in data types are marked with IReplicatedDataSerialization and serialized with ReplicatedDataSerializer.

Serialization of the data types are used in remote messages and also for creating message digests (SHA-1) to detect changes. Therefore it is important that the serialization produce the same bytes for the same content. For example sets and maps should be sorted deterministically in the serialization.

ReplicatedData types should be immutable, i.e. "modifying" methods should return a new instance.

UpdateSuccess when update has finished successfully with given write consistency withing provided time limit.
ModifyFailure if a Modify delegate has thrown a failure.
UpdateTimeout if a request couldn't complete withing given timeout and write consistency constraints.

Namespace Akka.DistributedData

Classes

Interfaces

Enums

Delegates