Documentation
¶
Overview ¶
Package kv provides an abstraction of a non-transactional key/value store.
Index ¶
- func IsConflict(err error) bool
- func RunBenchmarks(b *testing.B, store BinaryStore)
- func RunTests(t *testing.T, store BinaryStore)
- type BinaryInterceptor
- type BinaryKeyspace
- type BinaryRangeFunc
- type BinaryStore
- type ConflictError
- type Interceptor
- type Keyspace
- type RangeFunc
- type Revision
- type Store
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func IsConflict ¶ added in v0.14.0
IsConflict returns true if err is caused by ConflictError.
func RunBenchmarks ¶ added in v0.6.0
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 BinaryInterceptor ¶ added in v0.13.0
type BinaryInterceptor = Interceptor[[]byte, []byte]
BinaryInterceptor is an Interceptor that can be used to intercept operations on a BinaryKeyspace.
type BinaryKeyspace ¶ added in v0.8.0
A BinaryKeyspace is an isolated collection of binary key/value pairs.
Keys in a binary keyspace cannot be an empty slice.
type BinaryRangeFunc ¶ added in v0.8.0
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 ¶ added in v0.8.0
BinaryStore is a collection of keyspaces that map opaque binary keys to binary values.
func WithTelemetry ¶ added in v0.2.1
func WithTelemetry( s BinaryStore, p trace.TracerProvider, m metric.MeterProvider, l log.LoggerProvider, ) BinaryStore
WithTelemetry returns a BinaryStore that adds telemetry to s.
type ConflictError ¶ added in v0.14.0
type ConflictError[K any] struct { // Keyspace is the name of the keyspace in which the conflict occurred. Keyspace string // Key is the key on which the conflict occurred. Key K // Revision is the (incorrect) revision supplied to [Keyspace.Set]. Revision Revision }
ConflictError is returned by [Keyspace.Set] if the supplied revision does not match the key's actual revision.
func (ConflictError[K]) Error ¶ added in v0.14.0
func (e ConflictError[K]) Error() string
type Interceptor ¶ added in v0.13.0
type Interceptor[K, V any] struct { // contains filtered or unexported fields }
Interceptor defines functions that are invoked around keyspace operations.
func (*Interceptor[K, V]) AfterSet ¶ added in v0.13.0
func (i *Interceptor[K, V]) AfterSet(fn func(keyspace string, k K, v V, r *Revision) error)
AfterSet sets the function that is invoked after a key/value pair is set.
func (*Interceptor[K, V]) BeforeOpen ¶ added in v0.13.0
func (i *Interceptor[K, V]) BeforeOpen(fn func(name string) error)
BeforeOpen sets the function that is invoked before a Keyspace is opened.
type Keyspace ¶
type Keyspace[K, V any] interface { // Name returns the name of the keyspace. Name() string // Get returns the value associated with k. // // r is a monotonically increasing revision number that changes each time // the value associated with k is modified. // // If the key does not exist v is the zero-value of V and r is zero. Get(ctx context.Context, k K) (v V, r Revision, 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. // // r is the current revision number for k. If k is not present in the // keyspace, its current revision is zero. If r does not match the current // revision, a [ConflictError] occurs. // // On success, the new revision number is always r + 1. Set(ctx context.Context, k K, v V, r Revision) error // SetUnconditional associates a value with k, regardless of its current // revision. // // It is equivalent to calling Set with the current revision number, but // offers no optimistic concurrency control. // // If v is the zero-value of V (or equivalent), the key is deleted. SetUnconditional(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 ¶
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.
k is the key, v is the value, and r is the current revision.
type Revision ¶ added in v0.15.0
type Revision uint64
Revision is the "version" or "generation" of a key/value pair within a Keyspace. A non-existent key is always at revsion 0.
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 ¶ added in v0.8.0
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 key/value pairs to/from an underlying BinaryStore.
func WithInterceptor ¶ added in v0.13.0
func WithInterceptor[K, V any](s Store[K, V], in *Interceptor[K, V]) Store[K, V]
WithInterceptor returns a Store that invokes the functions defined by the given Interceptor when performing operations on s.
Source Files