Documentation
¶
Overview ¶
Package kv provides some useful abstractions over local key-value storage.
go get github.com/google/note-maps/kv/...
The model implemented by kv maps entities, which are like identifiers, to component values, which can be any Go type. Entity is an alias for uint64, and components are defined by kvschema, a code generator. The code generator looks for types that define the Encoder and Decoder interfaces from this package and produces strongly typed code for storing and retrieving instances of those types as values.
Package kv also supports indexing. If a component value type, in addition to implementing Encoder and Decoder, also has one or more index methods, the generated code will also support looking up entities or loading entities in order according to each index. An index method must: have a name that starts with "Index", receive no arguments, and return a slice of a type that also implements Encoder and Decoder.
Examples are included in the "examples" subdirectory.
If `go generate` doesn't produce a kvschema.go file, or the resulting kvschema.go file does not include support for all the types you've defined, try `kvschema -v` to find out why.
Index ¶
- func ConcatByteSlices(bss ...[]byte) []byte
- type Component
- type DB
- type Decoder
- type Discarder
- type Encoder
- type Entity
- type EntitySlice
- func (es *EntitySlice) Decode(src []byte) error
- func (es EntitySlice) Encode() []byte
- func (es EntitySlice) Equal(o EntitySlice) bool
- func (es *EntitySlice) Insert(e Entity) bool
- func (es EntitySlice) Len() int
- func (es EntitySlice) Less(a, b int) bool
- func (es *EntitySlice) Remove(e Entity) bool
- func (es EntitySlice) Search(e Entity) int
- func (es EntitySlice) Sort()
- func (es EntitySlice) Swap(a, b int)
- type IndexCursor
- type Iterator
- type Partitioned
- type Prefix
- type String
- type StringSlice
- type Txn
- type TxnCommitDiscarder
- type TxnDiscarder
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ConcatByteSlices ¶
ConcatByteSlices returns a concatentation of the given byte slices.
ConcatByteSlices is intended for constructing keys from an optional prefix and a seqeunce of Encoder.Encode() values, especially when some of the given byte slices have already been shared with other modules and should not be mutated. It is also a convenient function for simply copying a single byte slice.
Types ¶
type Component ¶
type Component uint16
Component is a hard-coded and globally unique identifier for a component type.
Components are typically hard-coded constants.
type DB ¶
type DB interface {
// NewTxn returns a new TxnCommitDiscarder that optionally supports updates.
NewTxn(update bool) TxnCommitDiscarder
// Close releases any resources held by this DB and closes the connection.
Close() error
}
DB represents the functions a database connection should implement to be convenient for code that uses this package.
type Decoder ¶
Decoder is an interface implemented by any type that is to be retrieved from the key or value of a key-value pair.
type Encoder ¶
type Encoder interface {
Encode() []byte
}
Encoder is an interface implemented by any type that is to be stored in the key or value of a key-value pair.
type Entity ¶
type Entity uint64
Entity is an identifier that can be associated with Go values via Components, and
Entities are typically created through Txn.Alloc().
type EntitySlice ¶
type EntitySlice []Entity
EntitySlice implements sorting and searching for slices of Entity as well as sort order preserving insertion and removal operations.
func (*EntitySlice) Decode ¶
func (es *EntitySlice) Decode(src []byte) error
Decode decodes src into es.
func (EntitySlice) Encode ¶
func (es EntitySlice) Encode() []byte
Encode encodes es into a new slice of bytes.
func (EntitySlice) Equal ¶
func (es EntitySlice) Equal(o EntitySlice) bool
Equal returns true if and only if the contents of es match the contents of o.
func (*EntitySlice) Insert ¶
func (es *EntitySlice) Insert(e Entity) bool
Insert adds e to es if it is not already included without disrupting the sorted ordering of es, and returns true if and only if e was not already present.
If es is not already sorted, the results are undefined.
func (EntitySlice) Len ¶
func (es EntitySlice) Len() int
Len returns len(es).
Len exists only to implement sort.Interface.
func (EntitySlice) Less ¶
func (es EntitySlice) Less(a, b int) bool
Less returns true if and only if es[a] < es[b].
Less exists only to implement sort.Interface.
func (*EntitySlice) Remove ¶
func (es *EntitySlice) Remove(e Entity) bool
Remove removes e from es if it is present without disrupting the sorted ordering of es, and returns true if and only if e was there to be removed.
If es is not already sorted, the results are undefined.
func (EntitySlice) Search ¶
func (es EntitySlice) Search(e Entity) int
Search returns the index of the first element of es that is greater than or equal to e.
In other words, if e is an element of es, then es[es.Search(e)] == e. However, if all elements in es are less than e, then es.Search(e) == len(e).
If es is not sorted, the results are undefined.
func (EntitySlice) Sort ¶
func (es EntitySlice) Sort()
Sort sorts the values of es in ascending order.
func (EntitySlice) Swap ¶
func (es EntitySlice) Swap(a, b int)
Swap swaps the values of es[a] and es[b].
Swap exists only to implement sort.Interface.
type IndexCursor ¶
IndexCursor describes a location within an index, to track the position of an iterator within that index.
type Iterator ¶
type Iterator interface {
// Iterators must be discarded when no longer in use.
Discarder
// Seek moves the iterator to the key-value pair that matches the given key.
//
// If there is no such key-value pair, Seek moves to the item with first key
// after the given key.
Seek(key []byte)
// Next moves to the iterator to the next key-value pair.
Next()
// Valid returns true if the iterator is at a valid key-value pair.
Valid() bool
// Key returns the key of the iterator's current key-value pair.
//
// May panic if Valid() returns false.
Key() []byte
// Value calls f with the value of the iterator's current key-value pair.
//
// May panic if Valid() returns false.
Value(f func([]byte) error) error
}
Iterator supports iteration over key-value pairs.
type Partitioned ¶
Partitioned combines a Txn with a partition identified by an Entity in order to provide useful common functions.
func (Partitioned) AllComponentEntities ¶
func (t Partitioned) AllComponentEntities(c Component, start *Entity, n int) (es []Entity, err error)
AllComponentEntities returns the first n entities that have values associated with c, beginning with the first entity greater than or equal to *start.
A nil start value will be interpreted as a pointer to zero.
A value of n less than or equal to zero will be interpretted as the largest possible value.
func (Partitioned) DeletePartition ¶
func (t Partitioned) DeletePartition() error
DeletePartition deletes all keys in the currently selected partition.
func (Partitioned) EntitiesByComponentIndex ¶
func (s Partitioned) EntitiesByComponentIndex(c, ix Component, cursor *IndexCursor, n int) (es []Entity, err error)
EntitiesByComponentIndex returns entities with c values ordered by their ix values.
Reading begins at cursor, and ends when the length of the returned Entity slice is less than n. When reading is not complete, cursor is updated such that using it in a subequent call to EntitiesByComponentIndex would return the next n entities.
type Prefix ¶
type Prefix []byte
Prefix is a convenience type for constructing keys through concatenation.
func (Prefix) AppendComponent ¶
AppendComponent appends c to p and returns the result.
func (Prefix) ConcatEntity ¶
ConcatEntity creates a new Prefix that contains p followed by e.
func (Prefix) ConcatEntityComponent ¶
ConcatEntityComponent creates a new Prefix that contains p followed by e and c.
type String ¶
type String string
String is an alias for string that implements the Encoder and Decoder interfaces.
type StringSlice ¶
type StringSlice []String
StringSlice is a slice of strings that implements the Encoder and Decoder interfaces.
func (*StringSlice) Decode ¶
func (ss *StringSlice) Decode(src []byte) error
Decode decodes src into s.
func (StringSlice) Encode ¶
func (ss StringSlice) Encode() []byte
Encode encodes s into a new slice of bytes.
type Txn ¶
type Txn interface {
// Alloc should never return the same Entity value twice until the space of
// possible Entity values is exhausted.
//
// Alloc cannot be implemented through Get and Set operations on the Txn
// interface itself because independent concurrent transactions require
// mutually unique Entity values, and the Txn interface maybe implemented
// by a transaction type.
Alloc() (Entity, error)
// Set stores key and value in the underlying key-value store.
Set(key, value []byte) error
// Delete deletes key and its value from the underlying key-value store.
Delete(key []byte) error
// Get finds the value associated with key in the underlying key-value store
// and passes it to f.
//
// If the key does not an exist, this is not an error: Get may or may not
// pass an empty slice to f.
//
// In any case, if f returns an error, then Get must also return an error.
Get(key []byte, f func([]byte) error) error
// PrefixIterator returns an iterator over all key-value pairs with keys
// matching the given prefix.
//
// The initial state of the PrefixIterator is not valid: use or Next() or
// Seek() to move the iterator to a valid key-value pair.
//
// The resulting iterator considers all valid keys as relative to the given
// prefix, so for prefix {1,2} an underlying key {1,2,3,4} will be visible
// through this iterator as merely {3,4}.
PrefixIterator(prefix []byte) Iterator
}
Txn represents the functions a key-value store transaction must implement in order to be used as a backing transaction in this package.
type TxnCommitDiscarder ¶
type TxnCommitDiscarder interface {
TxnDiscarder
// Commit commits the mutations performed through this Txn to the backing store.
Commit() error
}
TxnCommitDiscarder adds a Commit method to the Txn and Discarder interfaces.
A typical use of TxnCommitDiscarder is to track a transaction that supports mutations.
type TxnDiscarder ¶
TxnDiscarder combines the Txn and Discarder interfaces.
A typical use of TxnDiscarder might be for a transaction that does not support mutations.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package badger providers a Badger-backed implementation of kv.Txn.
|
Package badger providers a Badger-backed implementation of kv.Txn. |
|
cmd
|
|
|
kvschema/bindata
Package bindata Code generated by go-bindata.
|
Package bindata Code generated by go-bindata. |
|
examples
|
|
|
docs
Package docs defines a schema for storing documents in a kv.Txn.
|
Package docs defines a schema for storing documents in a kv.Txn. |
|
Package kvtest provides some utilities to help test packages that use kv.
|
Package kvtest provides some utilities to help test packages that use kv. |
|
Package memory provides an in-memory implementation of kv.Txn.
|
Package memory provides an in-memory implementation of kv.Txn. |