Documentation
¶
Overview ¶
Package set implements set CRDT primitives.
Index ¶
- Variables
- type ElementCodec
- type ORSet
- func (s *ORSet[T]) Add(element T) (ORSetDelta[T], error)
- func (s *ORSet[T]) ApplyDelta(delta ORSetDelta[T]) error
- func (s *ORSet[T]) ClockState() clock.State
- func (s *ORSet[T]) Compact(stableFrontier map[string]crdt.Tag) (int, error)
- func (s *ORSet[T]) CompactTombstones(acknowledged []crdt.Tag) (int, error)
- func (s *ORSet[T]) Contains(element T) bool
- func (s *ORSet[T]) Elements() []T
- func (s *ORSet[T]) Frontier() map[string]crdt.Tag
- func (s *ORSet[T]) MarshalBinary() ([]byte, error)
- func (s *ORSet[T]) MarshalBinaryWithClockState() ([]byte, clock.State, error)
- func (s *ORSet[T]) Merge(other *ORSet[T]) error
- func (s *ORSet[T]) Remove(element T) (ORSetDelta[T], error)
- func (s *ORSet[T]) Snapshot(frontier map[string]crdt.Tag) (snapshot.Snapshot, error)
- func (s *ORSet[T]) SnapshotCurrentState() (snapshot.Snapshot, error)
- func (s *ORSet[T]) State() crdt.StateSnapshot
- func (s *ORSet[T]) TombstoneTags() []crdt.Tag
- func (s *ORSet[T]) UnmarshalBinary(data []byte) error
- func (s *ORSet[T]) UnmarshalBinaryWithLimits(data []byte, limits frame.DecoderLimits) error
- type ORSetDelta
Constants ¶
This section is empty.
Variables ¶
var ( ErrInvalidCodec = errors.New("set: invalid element codec") ErrNilORSet = errors.New("set: nil OR-Set") ErrCodecMismatch = errors.New("set: codec ID mismatch") ErrInvalidDelta = errors.New("set: invalid OR-Set delta") ErrInvalidFrontier = errors.New("set: invalid frontier") ErrInvalidSnapshot = errors.New("set: invalid OR-Set snapshot") )
Functions ¶
This section is empty.
Types ¶
type ElementCodec ¶
type ElementCodec[T comparable] interface { ID() string Marshal(T) ([]byte, error) Unmarshal([]byte) (T, error) }
ElementCodec identifies and encodes one OR-Set element type. ID and encoded bytes must be stable across replicas that exchange state for the same set. Implementations must be safe for concurrent Marshal and Unmarshal calls and must return errors instead of panicking for invalid input.
type ORSet ¶
type ORSet[T comparable] struct { // contains filtered or unexported fields }
ORSet is an observed-remove, add-wins set. Each add receives a unique tag; remove operations tombstone only tags observed by that replica.
func NewORSet ¶
func NewORSet[T comparable](replicaID string, codec ElementCodec[T]) (*ORSet[T], error)
NewORSet creates an OR-Set for replicaID with codec.
func NewORSetFromClock ¶
func NewORSetFromClock[T comparable](clockState clock.State, codec ElementCodec[T]) (*ORSet[T], error)
NewORSetFromClock creates an OR-Set using a restored HLC state. Use this constructor when reusing a replica ID after restart.
func NewORSetFromSnapshot ¶
func NewORSetFromSnapshot[T comparable](saved snapshot.Snapshot, codec ElementCodec[T]) (*ORSet[T], error)
NewORSetFromSnapshot restores an OR-Set and its persisted local HLC state. Snapshots without a clock state are rejected because they cannot prove that this logical replica will not reuse a mutation tag after restart.
func (*ORSet[T]) Add ¶
func (s *ORSet[T]) Add(element T) (ORSetDelta[T], error)
Add inserts element and returns the add-tag delta.
func (*ORSet[T]) ApplyDelta ¶
func (s *ORSet[T]) ApplyDelta(delta ORSetDelta[T]) error
ApplyDelta joins delta into s. A delta already represented by s returns without advancing the local HLC or taking the receiver write lock.
func (*ORSet[T]) ClockState ¶
ClockState returns the state that must be persisted before this set's replica ID is reused after restart.
func (*ORSet[T]) Compact ¶
Compact removes tombstones that every active replica has acknowledged. The caller must provide a frontier whose every prefix is proven complete for every active replica. A greatest-observed-tag frontier from independently delivered, out-of-order deltas does not meet that requirement. Rejoining replicas must bootstrap from a post-compaction snapshot.
func (*ORSet[T]) CompactTombstones ¶
CompactTombstones removes exactly the supplied tombstones. It is safe for a coordinator that has independently proved acknowledgement for each tag; a tag that is not currently a tombstone is ignored. The input is completely validated before s is modified.
func (*ORSet[T]) Elements ¶
func (s *ORSet[T]) Elements() []T
Elements returns a copy of the currently visible elements. Its order is not specified; deterministic wire order is provided by the encoding layer.
func (*ORSet[T]) Frontier ¶
Frontier returns the greatest known tag for every replica in the current live-add and tombstone state. It is useful for diagnostics and for storing alongside a snapshot; the returned map is a copy. A frontier derived from independently delivered deltas is not, by itself, proof that every earlier tag was received, so it must not be used as a tombstone-GC acknowledgement unless the replication layer separately guarantees gap-free causal delivery.
func (*ORSet[T]) MarshalBinary ¶
MarshalBinary returns a deterministic framed representation of s. Element bytes, tags, and tombstones are all sorted, so map iteration cannot affect the result.
func (*ORSet[T]) MarshalBinaryWithClockState ¶
MarshalBinaryWithClockState returns an OR-Set state frame and the local HLC state required to reuse this replica ID safely after restart. Persist both values atomically. The returned frame and clock state do not alias s.
func (*ORSet[T]) Remove ¶
func (s *ORSet[T]) Remove(element T) (ORSetDelta[T], error)
Remove removes every tag for element that is currently observed by s and returns the tombstone delta. Concurrent, unknown adds survive the merge.
func (*ORSet[T]) Snapshot ¶
Snapshot returns an immutable OR-Set snapshot containing both its state frame and local HLC state. Persist the returned object atomically with the supplied frontier before restoring this replica ID.
func (*ORSet[T]) SnapshotCurrentState ¶
SnapshotCurrentState returns a snapshot with the frontier derived from the same OR-Set state. Use Snapshot when a replication layer has a broader, externally acknowledged frontier to persist instead.
func (*ORSet[T]) State ¶
func (s *ORSet[T]) State() crdt.StateSnapshot
State returns an immutable diagnostic summary.
func (*ORSet[T]) TombstoneTags ¶
TombstoneTags returns a sorted copy of every tombstone currently retained by s. It is intended for an acknowledgement protocol that confirms individual tombstones; callers cannot mutate the returned slice to change s.
func (*ORSet[T]) UnmarshalBinary ¶
UnmarshalBinary validates data completely before atomically replacing s's state. It only accepts the canonical order required by MarshalBinary.
func (*ORSet[T]) UnmarshalBinaryWithLimits ¶
func (s *ORSet[T]) UnmarshalBinaryWithLimits(data []byte, limits frame.DecoderLimits) error
UnmarshalBinaryWithLimits validates data completely before atomically replacing s's state using caller-supplied decoder limits.
type ORSetDelta ¶
type ORSetDelta[T comparable] struct { // contains filtered or unexported fields }
ORSetDelta is a joinable partial OR-Set state.
func UnmarshalORSetDelta ¶
func UnmarshalORSetDelta[T comparable](data []byte, codec ElementCodec[T]) (ORSetDelta[T], error)
UnmarshalORSetDelta validates and returns one OR-Set delta frame.
func UnmarshalORSetDeltaWithLimits ¶
func UnmarshalORSetDeltaWithLimits[T comparable](data []byte, codec ElementCodec[T], limits frame.DecoderLimits) (ORSetDelta[T], error)
UnmarshalORSetDeltaWithLimits validates and returns one OR-Set delta frame using caller-supplied decoder limits.
func (ORSetDelta[T]) MarshalBinary ¶
func (d ORSetDelta[T]) MarshalBinary(codec ElementCodec[T]) ([]byte, error)
MarshalBinary returns a deterministic framed representation of d using codec to identify and serialize its element type.
func (ORSetDelta[T]) Merge ¶
func (d ORSetDelta[T]) Merge(other ORSetDelta[T]) (ORSetDelta[T], error)
Merge joins other into d and returns a new delta without modifying either input delta.
Source Files