xotl.crdt.base – Basic interfaces and API

Common interface for all CRDTs.

class xotl.crdt.base.CvRDT(*, process: xotl.crdt.base.Process)

Base class for Convergent Replicated Data Types.

Basically this documents the expectation of each CvRDT. Subclasses must implement the following methods and attributes.

User facing API

The methods and properties in this sub-section are those expected all CRDTs expose to the users. These must be programmed to keep the expected semantics of the CRDT.

This base class, only describe them in an abstract way, sub-classes must provide their own implementation.

value

The current value that is managed by this CRDT.

This could be any type of value. But you must never assume changes to the value will be of any effect. Each CRDT implements methods to properly update its value.

This is a read-only property.

Internal (coordination layer) CRDT API.

Every CvRDT must implement these methods to initialize and update its state upon requests from the coordination layer.

merge(other: xotl.crdt.base.CvRDT) → None

Update the CvRDT to account for the another replica’s state.

__le__(other)

Compares two replicas for ‘<=’ in the semilattice.

This is NOT a relation of the value.

__eq__(other) → bool

Compares two replicas for ‘==’ in the semilattice.

This is NOT a relation of the value.

Warning

The following two methods should only be used within the boundaries of a coordinated controlled layer. They may alter the internal state of CRDT in a way that could break the expected semantics unless you take measures to ensure it.

init() → None

Set the initial state of a newly create CRDT.

reset() → None

Reset the internal state of value, usually to the initial state.

class xotl.crdt.base.Process(name: str, order: int)

Represents a process or node that holds replicated objects.

We require (for some CRDTs) that processes are uniquely named and totally ordered across the cluster. So when adding/removing a process you should take measures for not reusing old names.

Transmitting and receiving the CRDT state

The following two functions allow for CRDT to be transmitted from one process to another and/or saved in a file. They use pickle; which means you’re responsible for enforcing the required security.

xotl.crdt.base.get_state(crdt: xotl.crdt.base.CvRDT) → bytes

Dumps the crdt in a way that is amenable for transmission/storage.

xotl.crdt.base.from_state(state: bytes) → xotl.crdt.base.CvRDT

Reconstruct the CRDT from its dumped state.

state should be the result of calling get_state(). The following property should always hold:

assert crdt == from_state(get_state(crdt))