DeltaCrdt Documentation

To use DeltaCrdt in your Elixir project, add the delta_crdt package to your deps list in mix.exs.

def deps do
  [
    {:delta_crdt, "~> 0.6.3"}
  ]
end

This example demonstrates how to initialize two Delta CRDT nodes, link them as neighbors to enable replication, and perform basic key/value operations like put, read, take, and get.

# start 2 Delta CRDTs
{:ok, crdt1} = DeltaCrdt.start_link(DeltaCrdt.AWLWWMap)
{:ok, crdt2} = DeltaCrdt.start_link(DeltaCrdt.AWLWWMap)

# make them aware of each other
DeltaCrdt.set_neighbours(crdt1, [crdt2])

# show the initial value
DeltaCrdt.read(crdt1)
%{}

# add a key/value in crdt1
DeltaCrdt.put(crdt1, "CRDT", "is magic!")
DeltaCrdt.put(crdt1, "magic", "is awesome!")

# read it after it has been replicated to crdt2
DeltaCrdt.read(crdt2)
%{"CRDT" => "is magic!", "magic" => "is awesome!"}

# get only a subset of keys
DeltaCrdt.take(crdt2, ["magic"])
%{"magic" => "is awesome!"}

# get one value
DeltaCrdt.get(crdt2, "magic")
"is awesome!"

DeltaCrdt publishes the following telemetry metric to track synchronization completion:

• [:delta_crdt, :sync, :done]

Use DeltaCrdt.AWLWWMap.read/1 (or its variants) to retrieve the current resolved state of the map. The read function resolves conflicts by selecting the value with the highest timestamp for each key.

Available signatures:

• read(crdt): Returns a map of all resolved key/value pairs.
• read(crdt, keys): Returns a map containing only the specified keys.
• read(crdt, key): Returns a map containing only the single specified key.

# Get all values
all_values = DeltaCrdt.AWLWWMap.read(crdt)

# Get specific keys
subset = DeltaCrdt.AWLWWMap.read(crdt, ["key1", "key2"])

# Get a single key
single = DeltaCrdt.AWLWWMap.read(crdt, "key1")

Retrieve data from the CRDT using the following methods:

• get(crdt, key, timeout): Returns the value for a specific key, or nil if the key does not exist.
• take(crdt, keys, timeout): Returns a list of [{key, value}] tuples for the requested keys.
• to_map(crdt, timeout): Returns the entire state of the CRDT as a map.

# Get one value
val = DeltaCrdt.get(crdt, "my_key")

# Get a subset of keys
subset = DeltaCrdt.take(crdt, ["k1", "k2"])

# Get everything
full_map = DeltaCrdt.to_map(crdt)

Use DeltaCrdt.start_link/2 to initialize a new Delta CRDT process. You must provide a CRDT module (e.g., DeltaCrdt.AWLWWMap) that defines the data structure's logic. The process is linked to the calling process.

Configuration Options

• :sync_interval: Time in milliseconds between synchronization attempts with neighbours. Default is 200. (Note: values below 100 will trigger a warning).
• :on_diffs: A function or module/function/args tuple invoked on every diff.
• :max_sync_size: Maximum number of items to sync in one batch. Default is 200.
• :name: The name of the GenServer process.
• :storage_module: A module implementing the DeltaCrdt.Storage behaviour.

{:ok, crdt} = DeltaCrdt.start_link(DeltaCrdt.AWLWWMap, sync_interval: 3, name: :my_crdt)

You can use DeltaCrdt.child_spec/1 to integrate a CRDT node into an Elixir supervision tree. You must provide the :crdt module in the options.

children = [
  {DeltaCrdt, [crdt: DeltaCrdt.AWLWWMap, name: :my_crdt_map]}
]

# Example child spec usage
DeltaCrdt.child_spec(crdt: DeltaCrdt.AWLWWMap, name: :my_crdt_map)

To enable communication and state synchronization between CRDT nodes, use DeltaCrdt.set_neighbours/2.

Important: This function sets up unidirectional synchronization. To achieve bidirectional syncing (the standard use case), you must call the function for every node in the relationship. For example, to sync c1 and c2 bidirectionally, you must call:

DeltaCrdt.set_neighbours(c1, [c2])
DeltaCrdt.set_neighbours(c2, [c1])

DeltaCrdt.set_neighbours(crdt1, [crdt2, crdt3])

Use DeltaCrdt.AWLWWMap.add(key, value, i, state) to insert or update a value.

Parameters:

• key: The key to associate with the value.
• value: The value to store.
• i: The identifier for the node/replica performing the operation.
• state: The current DeltaCrdt.AWLWWMap struct.

Note: This operation uses System.monotonic_time(:nanosecond) internally to handle the Last-Write-Wins resolution.

new_state = DeltaCrdt.AWLWWMap.add("my_key", "my_value", replica_id, current_state)