sortedkv

Documentation

Overview

Package sortedkv defines a sorted key-value store abstraction. It is used by other persistence packages (like channel/persistence) to continuously save the state of the running program or load it upon startup. It is based on go-ethereum's https://github.com/ethereum/go-ethereum/ethdb and https://github.com/ethereum/go-ethereum/core/rawdb and is also inspired by perkeep.org/pkg/sorted

Index

• type Batch
• type Batcher
• type Database
  • func NewTable(db Database, prefix string) Database
• type Iterable
• type Iterator
• type NotFoundError
  • func (e *NotFoundError) Error() string
• type Reader
• type Writer

Types

type Batch

type Batch interface {
	Writer // Put and Delete

	// Apply performs all batched actions on the database.
	Apply() error

	// Reset resets the batch so that it doesn't contain any items and can be reused.
	Reset()
}

Batch is a write-only database that buffers changes to the underlying database until Apply() is called.

type Batcher

type Batcher interface {
	// NewBatch creates a Batch that will write to the Batcher.
	NewBatch() Batch
}

Batcher wraps the NewBatch method of a backing data store.

type Database

type Database interface {
	Reader
	Writer
	Batcher
	Iterable
	io.Closer
}

Database is a key-value store (not to be confused with SQL-like databases).

func NewTable

func NewTable(db Database, prefix string) Database

NewTable creates a new table.

type Iterable

type Iterable interface {
	// NewIterator creates a binary-alphabetical iterator over the entire keyspace
	// contained within the key-value database.
	NewIterator() Iterator

	// NewIteratorWithStart creates a binary-alphabetical iterator over a subset of
	// database content over a key range of [start, end). If start is empty, then
	// the iterator starts with the database's first entry. If end is empty, then
	// the iterator ends with the database's last entry.
	NewIteratorWithRange(start string, end string) Iterator

	// NewIteratorWithPrefix creates a binary-alphabetical iterator over a subset
	// of database content with a particular key prefix.
	NewIteratorWithPrefix(prefix string) Iterator
}

Iterable wraps the NewIterator methods of a backing data store.

type Iterator

type Iterator interface {
	// Next moves the iterator to the next key/value pair. It returns false if the
	// iterator is exhausted or closed, and true otherwise.
	Next() bool

	// Key returns the key of the current key/value pair, or "" if done.
	Key() string

	// Value returns the value of the current key/value pair, or "" if done.
	Value() string

	// ValueBytes returns the value of the current key/value pair, or nil if done. The
	// caller should not modify the contents of the returned slice, and its contents
	// may change on the next call to Next.
	ValueBytes() []byte

	// Close releases associated resources. It returns any accumulated error.
	// Exhausting all the key/value pairs is not considered to be an error.
	// Close can be called multiple times.
	Close() error
}

Iterator iterates over a data store's key/value pairs in ascending key order.

When it encounters an error, any Next() will return false and will yield no key/ value pairs. The error can be queried by calling the Error method. Calling Release is still necessary.

An iterator must be released after use, but it is not necessary to read an iterator until exhaustion. An iterator is not safe for concurrent use, but it is safe to use multiple iterators concurrently.

type NotFoundError

type NotFoundError struct {
	Key string
}

NotFoundError is returned whenever a key is not in the db.

func (*NotFoundError) Error

func (e *NotFoundError) Error() string

Error returns the error string.

type Reader

type Reader interface {
	// Has checks if a key is present in the store.
	Has(key string) (bool, error)

	// Get returns the value as string for given key if it is present in the store.
	Get(key string) (string, error)

	// GetBytes returns the value as []byte for given key if it is present in the store.
	GetBytes(key string) ([]byte, error)
}

Reader wraps the Has, Get and GetBytes methods of a key-value store.

type Writer

type Writer interface {
	// Put inserts the given value into the key-value store.
	// If the key is already present, it is overwritten and no error is returned.
	Put(key string, value string) error

	// PutBytes inserts the given value into the key-value store.
	// If the key is already present, it is overwritten and no error is returned.
	PutBytes(key string, value []byte) error

	// Delete removes the key from the key-value store.
	// If the key is not present, an error is returned
	Delete(key string) error
}

Writer wraps the Put and Delete methods of a key-value store.