Documentation
¶
Overview ¶
Package lww implements last-write-wins CRDT collections.
The HLC tag is the complete conflict-resolution rule: a higher tag wins. Therefore callers that reuse a replica ID must persist ClockState before a restart, just as they do for OR-Set.
Index ¶
- Variables
- type Map
- func (m *Map) ApplyDelta(delta MapDelta) error
- func (m *Map) ClockState() clock.State
- func (m *Map) Delete(key string) error
- func (m *Map) DeleteWithDelta(key string) (MapDelta, error)
- func (m *Map) Frontier() map[string]crdt.Tag
- func (m *Map) Get(key string) ([]byte, bool)
- func (m *Map) Keys() []string
- func (m *Map) MarshalBinary() ([]byte, error)
- func (m *Map) MarshalBinaryWithClockState() ([]byte, clock.State, error)
- func (m *Map) MarshalJSON() ([]byte, error)
- func (m *Map) Merge(other *Map) error
- func (m *Map) Set(key string, value []byte) error
- func (m *Map) SetWithDelta(key string, value []byte) (MapDelta, error)
- func (m *Map) Snapshot(frontier map[string]crdt.Tag) (snapshot.Snapshot, error)
- func (m *Map) SnapshotCurrentState() (snapshot.Snapshot, error)
- func (m *Map) State() crdt.StateSnapshot
- func (m *Map) UnmarshalBinary(data []byte) error
- func (m *Map) UnmarshalBinaryWithLimits(data []byte, limits frame.Limits) error
- type MapDelta
- type Set
- func (s *Set[T]) Add(value T) error
- func (s *Set[T]) ClockState() clock.State
- func (s *Set[T]) Contains(value T) bool
- func (s *Set[T]) Elements() []T
- func (s *Set[T]) MarshalJSON() ([]byte, error)
- func (s *Set[T]) Merge(other *Set[T]) error
- func (s *Set[T]) Remove(value T) error
- func (s *Set[T]) State() crdt.StateSnapshot
Constants ¶
This section is empty.
Variables ¶
var ( ErrInvalidReplicaID = errors.New("lww: invalid replica ID") ErrNilSet = errors.New("lww: nil set") ErrNilMap = errors.New("lww: nil map") ErrInvalidKey = errors.New("lww: invalid key") ErrInvalidDelta = errors.New("lww: invalid map delta") ErrInvalidSnapshot = errors.New("lww: invalid map snapshot") ErrTagConflict = errors.New("lww: conflicting values for one tag") )
Functions ¶
This section is empty.
Types ¶
type Map ¶
type Map struct {
// contains filtered or unexported fields
}
Map is a byte-value LWW map. Returning and accepting copies prevents a caller from modifying replicated state through a shared slice. Values are deliberately opaque; applications may use a deterministic JSON, protobuf, or domain codec above this type.
func NewMapFromSnapshot ¶
NewMapFromSnapshot restores a map and its HLC state. Snapshots without a clock state are rejected because they cannot safely reuse a replica ID.
func (*Map) ApplyDelta ¶
ApplyDelta joins a validated partial map state into m. It validates every entry and detects equal-tag conflicts before mutating the map or HLC.
func (*Map) ClockState ¶
func (*Map) DeleteWithDelta ¶
DeleteWithDelta removes key and returns the joinable delete delta.
func (*Map) Frontier ¶
Frontier returns the greatest map-entry tag per replica. The returned map is owned by the caller and includes delete tombstones.
func (*Map) Keys ¶
Keys returns the visible keys in lexical order, which keeps callers from accidentally depending on Go's randomized map iteration order.
func (*Map) MarshalBinary ¶
MarshalBinary returns the canonical framed LWW-Map state.
func (*Map) MarshalBinaryWithClockState ¶
MarshalBinaryWithClockState captures state and HLC state for atomic persistence before a replica ID is reused after restart.
func (*Map) MarshalJSON ¶ added in v1.0.5
MarshalJSON returns a diagnostic summary for structured logs. It omits map keys, values, tags, and clock state, and cannot restore the map.
func (*Map) SetWithDelta ¶
SetWithDelta writes a value and returns the joinable delta for this write.
func (*Map) Snapshot ¶
Snapshot creates an immutable map state snapshot with caller-supplied replication frontier and the local HLC state.
func (*Map) SnapshotCurrentState ¶
SnapshotCurrentState creates a snapshot whose frontier is derived from all visible and deleted map entries.
func (*Map) State ¶
func (m *Map) State() crdt.StateSnapshot
func (*Map) UnmarshalBinary ¶
UnmarshalBinary atomically replaces m with a valid complete LWW-Map state.
type MapDelta ¶
type MapDelta struct {
// contains filtered or unexported fields
}
MapDelta is a joinable partial LWW-Map state. Its contents are deliberately opaque so callers cannot mutate an entry after it has been handed to a replica or coalescer.
func UnmarshalMapDelta ¶
UnmarshalMapDelta decodes one bounded, canonical LWW-Map delta frame.
func UnmarshalMapDeltaWithLimits ¶
UnmarshalMapDeltaWithLimits decodes one bounded, canonical LWW-Map delta.
func (MapDelta) MarshalBinary ¶
MarshalBinary returns the canonical framed LWW-Map delta.
func (MapDelta) MarshalJSON ¶ added in v1.0.5
MarshalJSON returns a diagnostic summary for structured logs. It omits map keys, values, tags, and clock state and cannot be applied as a delta from JSON.
type Set ¶
type Set[T comparable] struct { // contains filtered or unexported fields }
Set is an LWW element set. Concurrent add/remove operations are resolved by the canonical Tag ordering, rather than by an implicit wall-clock tie rule.
func NewSetFromClock ¶
func NewSetFromClock[T comparable](state clock.State) (*Set[T], error)
func (*Set[T]) ClockState ¶
func (*Set[T]) MarshalJSON ¶ added in v1.0.5
MarshalJSON returns a diagnostic summary for structured logs. It omits elements, keys, values, tags, and clock state, and cannot restore the set.
func (*Set[T]) Merge ¶
Merge selects the highest tag for every element. It snapshots other before locking s, so reciprocal concurrent merges cannot deadlock.
func (*Set[T]) State ¶
func (s *Set[T]) State() crdt.StateSnapshot
Source Files