Documentation
¶
Overview ¶
Package list implements a generic, ordered Replicated Growable Array (RGA).
Each position holds one canonical caller-coded value. Positions, rather than offsets, are replicated, so duplicate and out-of-order delivery converge.
Index ¶
- Variables
- type Delta
- type ElementCodec
- type Options
- type Position
- type RGA
- func New[T any](replicaID string, codec ElementCodec[T]) (*RGA[T], error)
- func NewFromClock[T any](state clock.State, codec ElementCodec[T]) (*RGA[T], error)
- func NewFromClockWithOptions[T any](state clock.State, codec ElementCodec[T], options Options) (*RGA[T], error)
- func NewFromSnapshot[T any](saved snapshot.Snapshot, codec ElementCodec[T]) (*RGA[T], error)
- func NewFromSnapshotWithOptions[T any](saved snapshot.Snapshot, codec ElementCodec[T], options Options, ...) (*RGA[T], error)
- func NewWithOptions[T any](replicaID string, codec ElementCodec[T], options Options) (*RGA[T], error)
- func (r *RGA[T]) Append(values []T) (Delta, error)
- func (r *RGA[T]) ApplyDelta(delta Delta) error
- func (r *RGA[T]) At(offset int) (T, error)
- func (r *RGA[T]) ClockState() clock.State
- func (r *RGA[T]) CompactTombstones(tags []Position) (int, error)
- func (r *RGA[T]) Delete(offset, count int) (Delta, error)
- func (r *RGA[T]) Insert(offset int, values []T) (Delta, error)
- func (r *RGA[T]) MarshalBinary() ([]byte, error)
- func (r *RGA[T]) MarshalBinaryWithClockState() ([]byte, clock.State, error)
- func (r *RGA[T]) MarshalBinaryWithLimits(limits frame.DecoderLimits) ([]byte, error)
- func (r *RGA[T]) Merge(other *RGA[T]) error
- func (r *RGA[T]) MissingParents() []Position
- func (r *RGA[T]) PendingCount() int
- func (r *RGA[T]) Positions() []Position
- func (r *RGA[T]) SnapshotCurrentState() (snapshot.Snapshot, error)
- func (r *RGA[T]) State() crdt.StateSnapshot
- func (r *RGA[T]) TombstoneTags() []Position
- func (r *RGA[T]) UnmarshalBinary(data []byte) error
- func (r *RGA[T]) UnmarshalBinaryWithLimits(data []byte, limits frame.DecoderLimits) error
- func (r *RGA[T]) Values() ([]T, error)
Constants ¶
This section is empty.
Variables ¶
var ( ErrNilList = errors.New("list: nil RGA") ErrInvalidReplica = errors.New("list: invalid replica ID") ErrInvalidCodec = errors.New("list: invalid element codec") ErrRange = errors.New("list: range outside visible list") ErrInvalidDelta = errors.New("list: invalid RGA delta") ErrTagConflict = errors.New("list: conflicting node for one tag") ErrIncompleteState = errors.New("list: incomplete RGA state") ErrResourceLimit = errors.New("list: RGA resource limit exceeded") ErrUnsafeCompaction = errors.New("list: unsafe RGA tombstone compaction") )
Functions ¶
This section is empty.
Types ¶
type Delta ¶
type Delta struct {
// contains filtered or unexported fields
}
Delta is an opaque, joinable partial list state. It is constructed by local mutations or bounded frame decoding only.
func UnmarshalDelta ¶
func UnmarshalDelta[T any](data []byte, codec ElementCodec[T]) (Delta, error)
UnmarshalDelta decodes a bounded canonical list delta for codec.
func UnmarshalDeltaWithLimits ¶
func UnmarshalDeltaWithLimits[T any](data []byte, codec ElementCodec[T], limits frame.DecoderLimits) (Delta, error)
UnmarshalDeltaWithLimits decodes a bounded canonical list delta for codec.
func (Delta) MarshalBinary ¶
MarshalBinary returns one canonical list delta frame.
func (Delta) MarshalBinaryWithLimits ¶
func (d Delta) MarshalBinaryWithLimits(limits frame.DecoderLimits) ([]byte, error)
MarshalBinaryWithLimits returns a canonical bounded list delta frame.
type ElementCodec ¶
type ElementCodec[T any] interface { ID() string Marshal(T) ([]byte, error) Unmarshal([]byte) (T, error) }
ElementCodec defines one application value's canonical wire representation. Marshal must encode semantically equal values identically. The RGA verifies every locally created and remotely decoded value by a decode/re-encode round trip before it can enter replicated state.
type Options ¶
type Options struct {
MaxNodes int
MaxTombstones int
MaxPendingNodes int
MaxPendingBytes int
MaxValueBytes int
}
Options bounds retained list state. Applications receiving untrusted peers should set a group-appropriate bound rather than rely on process memory.
func DefaultOptions ¶
func DefaultOptions() Options
DefaultOptions returns conservative per-list retention limits.
type RGA ¶
type RGA[T any] struct { // contains filtered or unexported fields }
RGA is a generic collaborative list. Deletion retains a structural tombstone: an element deleted before its insertion arrives remains hidden when that insertion is eventually delivered.
func New ¶
func New[T any](replicaID string, codec ElementCodec[T]) (*RGA[T], error)
New constructs a list with default retention limits.
func NewFromClock ¶
NewFromClock restores a replica clock with default list limits.
func NewFromClockWithOptions ¶
func NewFromClockWithOptions[T any](state clock.State, codec ElementCodec[T], options Options) (*RGA[T], error)
NewFromClockWithOptions restores a replica clock. Persist its state atomically with a complete list snapshot before reusing a replica ID.
func NewFromSnapshot ¶
NewFromSnapshot restores a complete HLC-backed list snapshot.
func NewFromSnapshotWithOptions ¶
func NewFromSnapshotWithOptions[T any](saved snapshot.Snapshot, codec ElementCodec[T], options Options, limits frame.DecoderLimits) (*RGA[T], error)
NewFromSnapshotWithOptions restores a complete snapshot within caller retention and decoder limits.
func NewWithOptions ¶
func NewWithOptions[T any](replicaID string, codec ElementCodec[T], options Options) (*RGA[T], error)
NewWithOptions constructs a list with explicit retained-state limits.
func (*RGA[T]) ApplyDelta ¶
ApplyDelta atomically integrates a locally created or decoded delta.
func (*RGA[T]) ClockState ¶
ClockState returns the HLC state that must be persisted with a snapshot.
func (*RGA[T]) CompactTombstones ¶
CompactTombstones removes exactly requested tombstoned leaves. The caller must first obtain exact authenticated acknowledgements for one epoch, save a post-compaction checkpoint, and retire old deltas. Any retained child or unresolved dependent blocks the entire request.
func (*RGA[T]) Insert ¶
Insert inserts values before visible element offset. One value becomes one RGA position, even when its canonical encoding is large or multi-byte.
func (*RGA[T]) MarshalBinary ¶
MarshalBinary returns a canonical complete list state frame. Pending out-of-order dependencies are deliberately not serializable as a snapshot.
func (*RGA[T]) MarshalBinaryWithClockState ¶
MarshalBinaryWithClockState returns one complete frame and the HLC state that must be durably stored with it.
func (*RGA[T]) MarshalBinaryWithLimits ¶
func (r *RGA[T]) MarshalBinaryWithLimits(limits frame.DecoderLimits) ([]byte, error)
MarshalBinaryWithLimits returns a canonical complete list state constrained by caller-selected transport limits.
func (*RGA[T]) MissingParents ¶
MissingParents returns unique unresolved parent IDs in canonical order.
func (*RGA[T]) PendingCount ¶
PendingCount returns unresolved out-of-order nodes. Any non-zero value prevents a complete state snapshot from being emitted.
func (*RGA[T]) SnapshotCurrentState ¶
SnapshotCurrentState creates a complete HLC-backed list snapshot.
func (*RGA[T]) State ¶
func (r *RGA[T]) State() crdt.StateSnapshot
State returns an immutable diagnostic summary that contains no values, positions, clocks, or frame bytes.
func (*RGA[T]) TombstoneTags ¶
TombstoneTags returns every retained deletion identity in canonical order. It is an exact-acknowledgement input, never proof of safe collection.
func (*RGA[T]) UnmarshalBinary ¶
UnmarshalBinary validates a full list state before atomically replacing r.
func (*RGA[T]) UnmarshalBinaryWithLimits ¶
func (r *RGA[T]) UnmarshalBinaryWithLimits(data []byte, limits frame.DecoderLimits) error
UnmarshalBinaryWithLimits validates a bounded full state before atomically replacing r. It refuses incomplete states and non-canonical values.
Source Files