barrel_vv (barrel_docdb v1.0.0)

View Source

Version vectors: per-writer-node high-water marks.

A document's version vector maps each node id to the highest HLC this replica has seen from that node for the document. Comparing two vectors decides how replicated writes relate:

  • dominates: the remote saw everything we have and more, so its version fast-forwards ours.
  • dominated / eq: we already cover the remote version; it is stored as superseded history, not applied.
  • concurrent: a real conflict; last-write-wins by barrel_version:compare/2 picks the winner and the loser is retained as a conflict sibling.

contains/2 answers the replication diff question: does this replica already cover a given version?

Summary

Types

vv/0

NodeId -> highest HLC seen from that node.

Functions

bump(VV, _)

Record a version in the vector (monotonic: never goes backward).

compare(A, B)

Relate two vectors.

contains(VV, _)

Does the vector cover a version (same or newer HLC from that node)? This is the replication "have" test.

decode(Bin)

Decode an encoded vector (the input must be exactly one encoded vector).

decode_prefix(_)

Decode an encoded vector from the head of the input and return the remaining bytes (history entries append an optional TLV tail after the VV).

encode(VV)

Deterministic binary encoding (entries sorted by node id): <<Count:16, [NodeLen:8, Node/binary, Hlc:12/binary] ...>>.

merge(A, B)

Pointwise maximum of two vectors.

new()

The empty vector.

Types

vv/0

-type vv() :: #{binary() => barrel_hlc:timestamp()}.

NodeId -> highest HLC seen from that node.

Functions

bump(VV, _)

-spec bump(vv(), barrel_version:version()) -> vv().

Record a version in the vector (monotonic: never goes backward).

compare(A, B)

-spec compare(vv(), vv()) -> eq | dominates | dominated | concurrent.

Relate two vectors.

contains(VV, _)

-spec contains(vv(), barrel_version:version()) -> boolean().

Does the vector cover a version (same or newer HLC from that node)? This is the replication "have" test.

decode(Bin)

-spec decode(binary()) -> vv().

Decode an encoded vector (the input must be exactly one encoded vector).

decode_prefix(_)

-spec decode_prefix(binary()) -> {vv(), binary()}.

Decode an encoded vector from the head of the input and return the remaining bytes (history entries append an optional TLV tail after the VV).

encode(VV)

-spec encode(vv()) -> binary().

Deterministic binary encoding (entries sorted by node id): <<Count:16, [NodeLen:8, Node/binary, Hlc:12/binary] ...>>.

merge(A, B)

-spec merge(vv(), vv()) -> vv().

Pointwise maximum of two vectors.

new()

-spec new() -> vv().

The empty vector.