interval

Documentation

Overview

Package interval provides revision-bound persistent interval sets. Sets are immutable: every mutation returns a new root while older roots remain safe for concurrent readers.

Index

• Constants
• Variables
• type Entry
• type Options
• type QueryOptions
• type Result
• type Set
  • func New[T any](revision uint64, length int64, options Options) (*Set[T], error)
  • func (s *Set[T]) All(ctx context.Context, options QueryOptions) (Result[T], error)
  • func (s *Set[T]) At(ctx context.Context, offset int64, options QueryOptions) (Result[T], error)
  • func (s *Set[T]) Get(id string) (Entry[T], bool)
  • func (s *Set[T]) Intersect(ctx context.Context, start, end int64, options QueryOptions) (Result[T], error)
  • func (s *Set[T]) Len() int64
  • func (s *Set[T]) Put(entry Entry[T]) (*Set[T], error)
  • func (s *Set[T]) PutAll(ctx context.Context, entries []Entry[T]) (*Set[T], error)
  • func (s *Set[T]) Remove(id string) (*Set[T], bool, error)
  • func (s *Set[T]) RemoveAll(ctx context.Context, ids []string) (*Set[T], bool, error)
  • func (s *Set[T]) Revision() uint64
  • func (s *Set[T]) Stats() Stats
  • func (s *Set[T]) Transform(ctx context.Context, changes coordinate.ChangeMap) (*Set[T], error)
• type Stats

Constants

const (
	DefaultMaxEntries = 1_048_576
	MaximumEntries    = 16_777_216
	DefaultMaxIDBytes = 4 << 10
	MaximumIDBytes    = 1 << 20
	DefaultMaxResults = 100_000
	MaximumResults    = 1_000_000
)

Variables

var (
	ErrInvalidContext   = errors.New("interval: nil context")
	ErrInvalidOptions   = errors.New("interval: invalid options")
	ErrInvalidSet       = errors.New("interval: invalid set")
	ErrInvalidEntry     = errors.New("interval: invalid entry")
	ErrInvalidRange     = errors.New("interval: invalid range")
	ErrRevisionMismatch = errors.New("interval: revision mismatch")
	ErrLengthMismatch   = errors.New("interval: document length mismatch")
	ErrLimitExceeded    = errors.New("interval: configured limit exceeded")
)

Types

type Entry

type Entry[T any] struct {
	ID    string
	Range coordinate.AnchoredRange
	Layer int64
	Value T
}

Entry attaches an opaque value and host-defined layer to one anchored byte range. ID is the stable update/removal key.

type Options

type Options struct {
	MaxEntries int
	MaxIDBytes int
	MaxResults int
}

type QueryOptions

type QueryOptions struct {
	MaxResults int
}

type Result

type Result[T any] struct {
	Entries  []Entry[T]
	Complete bool
}

type Set

type Set[T any] struct {
	// contains filtered or unexported fields
}

Set is one immutable interval-set revision.

func New

func New[T any](revision uint64, length int64, options Options) (*Set[T], error)

func (*Set[T]) All

func (s *Set[T]) All(ctx context.Context, options QueryOptions) (Result[T], error)

func (*Set[T]) At

func (s *Set[T]) At(ctx context.Context, offset int64, options QueryOptions) (Result[T], error)

At returns spans containing offset and zero-width entries exactly at it.

func (*Set[T]) Get

func (s *Set[T]) Get(id string) (Entry[T], bool)

func (*Set[T]) Intersect

func (s *Set[T]) Intersect(
	ctx context.Context,
	start, end int64,
	options QueryOptions,
) (Result[T], error)

Intersect returns entries overlapping [start,end), plus zero-width entries whose point lies inside that range.

func (*Set[T]) Len

func (s *Set[T]) Len() int64

func (*Set[T]) Put

func (s *Set[T]) Put(entry Entry[T]) (*Set[T], error)

func (*Set[T]) PutAll

func (s *Set[T]) PutAll(ctx context.Context, entries []Entry[T]) (*Set[T], error)

PutAll atomically applies entries in input order. Repeated IDs use their final value.

func (*Set[T]) Remove

func (s *Set[T]) Remove(id string) (*Set[T], bool, error)

func (*Set[T]) RemoveAll

func (s *Set[T]) RemoveAll(ctx context.Context, ids []string) (*Set[T], bool, error)

RemoveAll atomically removes IDs. Missing and repeated IDs are harmless.

func (*Set[T]) Revision

func (s *Set[T]) Revision() uint64

func (*Set[T]) Stats

func (s *Set[T]) Stats() Stats

func (*Set[T]) Transform

func (s *Set[T]) Transform(ctx context.Context, changes coordinate.ChangeMap) (*Set[T], error)

Transform atomically moves every entry through one exact ChangeMap. Values are copied by ordinary Go assignment and never interpreted.

type Stats

type Stats struct {
	Revision   uint64
	ByteLength int64
	Entries    int
}