kv

Documentation

Overview

Package kv provides an abstraction of a non-transactional key/value store.

Index

• func RunBenchmarks(b *testing.B, store BinaryStore)
• func RunTests(t *testing.T, store BinaryStore)
• type BinaryKeyspace
• type BinaryRangeFunc
• type BinaryStore
  • func WithTelemetry(s BinaryStore, p trace.TracerProvider, m metric.MeterProvider, l *slog.Logger) BinaryStore
• type Keyspace
• type RangeFunc
• type Store
  • func NewMarshalingStore[K, V any](s BinaryStore, km marshaler.Marshaler[K], vm marshaler.Marshaler[V]) Store[K, V]

Functions

func RunBenchmarks

func RunBenchmarks(
	b *testing.B,
	store BinaryStore,
)

RunBenchmarks runs benchmarks against a BinaryStore implementation.

func RunTests

func RunTests(
	t *testing.T,
	store BinaryStore,
)

RunTests runs tests that confirm a BinaryStore implementation behaves correctly.

Types

type BinaryKeyspace

type BinaryKeyspace = Keyspace[[]byte, []byte]

A BinaryKeyspace is an isolated collection of binary key/value pairs.

Keys in a binary keyspace cannot be an empty slice.

type BinaryRangeFunc

type BinaryRangeFunc = RangeFunc[[]byte, []byte]

A BinaryRangeFunc is a function used to range over the key/value pairs in a BinaryKeyspace.

If err is non-nil, ranging stops and err is propagated up the stack. Otherwise, if ok is false, ranging stops without any error being propagated.

type BinaryStore

type BinaryStore = Store[[]byte, []byte]

BinaryStore is a collection of keyspaces that map opaque binary keys to binary values.

func WithTelemetry

func WithTelemetry(
	s BinaryStore,
	p trace.TracerProvider,
	m metric.MeterProvider,
	l *slog.Logger,
) BinaryStore

WithTelemetry returns a BinaryStore that adds telemetry to s.

type Keyspace

type Keyspace[K, V any] interface {
	// Name returns the name of the keyspace.
	Name() string

	// Get returns the value associated with k.
	//
	// If the key does not exist v is the zero-value of V.
	Get(ctx context.Context, k K) (v V, err error)

	// Has returns true if k is present in the keyspace.
	Has(ctx context.Context, k K) (ok bool, err error)

	// Set associates a value with k.
	//
	// If v is the zero-value of V (or equivalent), the key is deleted.
	Set(ctx context.Context, k K, v V) error

	// Range invokes fn for each key in the keyspace in an undefined order.
	Range(ctx context.Context, fn RangeFunc[K, V]) error

	// Close closes the keyspace.
	Close() error
}

A Keyspace is an isolated collection of key/value pairs.

type RangeFunc

type RangeFunc[K, V any] func(ctx context.Context, k K, v V) (ok bool, err error)

A RangeFunc is a function used to range over the key/value pairs in a Keyspace.

If err is non-nil, ranging stops and err is propagated up the stack. Otherwise, if ok is false, ranging stops without any error being propagated.

type Store

type Store[K, V any] interface {
	// Open returns the keyspace with the given name.
	Open(ctx context.Context, name string) (Keyspace[K, V], error)
}

Store is a collection of keyspaces that map keys of type K to values of type V.

func NewMarshalingStore

func NewMarshalingStore[K, V any](
	s BinaryStore,
	km marshaler.Marshaler[K],
	vm marshaler.Marshaler[V],
) Store[K, V]

NewMarshalingStore returns a new Store that marshals/unmarshals records of type T to/from an underlying BinaryStore.