Documentation

Index

Constants

View Source
const (
	DelimiterSegmentLength = -1
	VariadicSegmentLength  = 0
)

Variables

View Source
var (
	ErrInvalidLengthStorage        = fmt.Errorf("proto: negative length found during unmarshaling")
	ErrIntOverflowStorage          = fmt.Errorf("proto: integer overflow")
	ErrUnexpectedEndOfGroupStorage = fmt.Errorf("proto: unexpected end of group")
)

Functions

func AddTreePrintTree

func AddTreePrintTree(edge string, tree treeprint.Tree, rwt KVCallbackIterableReader)

func CompareKeys

func CompareKeys(k1, k2 []byte) int

    Sorts the keys as if they were compared lexicographically with their KeyOrder prepended

    func EnsureKeyFormatStore

    func EnsureKeyFormatStore(ks interface{}) ([][]byte, error)

      Checks that a struct containing KeyFormat fields has no collisions on prefix and so acts as a sane 'KeyFormatStore'

      func KeyOrder

      func KeyOrder(key []byte) int

        KeyOrder maps []byte{} -> -1, []byte(nil) -> 1, and everything else to 0. This encodes the assumptions of the KVIterator domain endpoints

        func NormaliseDomain

        func NormaliseDomain(low, high []byte) ([]byte, []byte)

          NormaliseDomain encodes the assumption that when nil is used as a lower bound is interpreted as low rather than high

          Types

          type ByteSlicable

          type ByteSlicable interface {
          	Bytes() []byte
          }

          type CommitID

          type CommitID struct {
          	Version              int64    `protobuf:"varint,1,opt,name=Version,proto3" json:"Version,omitempty"`
          	Hash                 []byte   `protobuf:"bytes,2,opt,name=Hash,proto3" json:"Hash,omitempty"`
          	XXX_NoUnkeyedLiteral struct{} `json:"-"`
          	XXX_unrecognized     []byte   `json:"-"`
          	XXX_sizecache        int32    `json:"-"`
          }

            This is the object that is stored in the leaves of the commitsTree - it captures the sub-tree hashes so that the commitsTree's hash becomes a mixture of the hashes of all the sub-trees.

            func (*CommitID) Descriptor

            func (*CommitID) Descriptor() ([]byte, []int)

            func (*CommitID) GetHash

            func (m *CommitID) GetHash() []byte

            func (*CommitID) GetVersion

            func (m *CommitID) GetVersion() int64

            func (*CommitID) Marshal

            func (m *CommitID) Marshal() (dAtA []byte, err error)

            func (*CommitID) MarshalBinary

            func (cid *CommitID) MarshalBinary() ([]byte, error)

            func (*CommitID) MarshalTo

            func (m *CommitID) MarshalTo(dAtA []byte) (int, error)

            func (*CommitID) MarshalToSizedBuffer

            func (m *CommitID) MarshalToSizedBuffer(dAtA []byte) (int, error)

            func (*CommitID) ProtoMessage

            func (*CommitID) ProtoMessage()

            func (*CommitID) Reset

            func (m *CommitID) Reset()

            func (*CommitID) Size

            func (m *CommitID) Size() (n int)

            func (CommitID) String

            func (cid CommitID) String() string

            func (*CommitID) Unmarshal

            func (m *CommitID) Unmarshal(dAtA []byte) error

            func (*CommitID) UnmarshalBinary

            func (cid *CommitID) UnmarshalBinary(data []byte) error

            func (*CommitID) XXX_DiscardUnknown

            func (m *CommitID) XXX_DiscardUnknown()

            func (*CommitID) XXX_Marshal

            func (m *CommitID) XXX_Marshal(b []byte, deterministic bool) ([]byte, error)

            func (*CommitID) XXX_Merge

            func (m *CommitID) XXX_Merge(src proto.Message)

            func (*CommitID) XXX_MessageName

            func (*CommitID) XXX_MessageName() string

            func (*CommitID) XXX_Size

            func (m *CommitID) XXX_Size() int

            func (*CommitID) XXX_Unmarshal

            func (m *CommitID) XXX_Unmarshal(b []byte) error

            type ForestOption

            type ForestOption func(*ImmutableForest)
            var WithOverwriting ForestOption = func(imf *ImmutableForest) { imf.overwriting = true }

            type ForestReader

            type ForestReader interface {
            	Reader(prefix []byte) (KVCallbackIterableReader, error)
            }

              Access the read path of a forest

              type ImmutableForest

              type ImmutableForest struct {
              	// contains filtered or unexported fields
              }

                ImmutableForest contains much of the implementation for MutableForest yet it's external API is immutable

                func NewImmutableForest

                func NewImmutableForest(commitsTree KVCallbackIterableReader, treeDB dbm.DB, cacheSize int,
                	options ...ForestOption) (*ImmutableForest, error)

                func (*ImmutableForest) Dump

                func (imf *ImmutableForest) Dump() string

                func (*ImmutableForest) Iterate

                func (imf *ImmutableForest) Iterate(start, end []byte, ascending bool, fn func(prefix []byte, tree KVCallbackIterableReader) error) error

                func (*ImmutableForest) Reader

                func (imf *ImmutableForest) Reader(prefix []byte) (KVCallbackIterableReader, error)

                  Get the tree at prefix for making reads

                  type ImmutableTree

                  type ImmutableTree struct {
                  	*iavl.ImmutableTree
                  }

                  func (*ImmutableTree) Get

                  func (imt *ImmutableTree) Get(key []byte) ([]byte, error)

                  func (*ImmutableTree) Has

                  func (imt *ImmutableTree) Has(key []byte) (bool, error)

                  func (*ImmutableTree) Iterate

                  func (imt *ImmutableTree) Iterate(start, end []byte, ascending bool, fn func(key []byte, value []byte) error) error

                  type KVCallbackIterable

                  type KVCallbackIterable interface {
                  	// low must be lexicographically less than high. high is exclusive unless it is nil in which case it is inclusive.
                  	// ascending == false reverses order.
                  	Iterate(low, high []byte, ascending bool, fn func(key []byte, value []byte) error) error
                  }

                    Provides the native iteration for IAVLTree

                    type KVCallbackIterableReader

                    type KVCallbackIterableReader interface {
                    	KVReader
                    	KVCallbackIterable
                    }

                    type KVIterable

                    type KVIterable interface {
                    	// Iterator over a domain of keys in ascending order. high is exclusive.
                    	// low must be less than high, or the Iterator is invalid.
                    	// Iterator must be closed by caller.
                    	// To iterate over entire domain, use store.Iterator(nil, nil)
                    	// CONTRACT: No writes may happen within a domain while an iterator exists over it.
                    	Iterator(low, high []byte) (KVIterator, error)
                    
                    	// Iterator over a domain of keys in descending order. high is exclusive.
                    	//  must be less than high, or the Iterator is invalid.
                    	// Iterator must be closed by caller.
                    	// CONTRACT: No writes may happen within a domain while an iterator exists over it.
                    	ReverseIterator(low, high []byte) (KVIterator, error)
                    }

                      This is partially extracted from Cosmos SDK for alignment but is more minimal, we should suggest this becomes an embedded interface

                      type KVIterableReader

                      type KVIterableReader interface {
                      	KVReader
                      	KVIterable
                      }

                      type KVIterator

                      type KVIterator = dbm.Iterator

                      type KVReader

                      type KVReader interface {
                      	// Get returns nil iff key doesn't exist. Panics on nil key.
                      	Get(key []byte) ([]byte, error)
                      	// Has checks if a key exists. Panics on nil key.
                      	Has(key []byte) (bool, error)
                      }

                      type KVReaderWriter

                      type KVReaderWriter interface {
                      	KVReader
                      	KVWriter
                      }

                        KVStore is a simple interface to get/set data

                        type KVStore

                        type KVStore interface {
                        	KVReaderWriter
                        	KVIterable
                        }

                        type KVWriter

                        type KVWriter interface {
                        	// Set sets the key. Panics on nil key.
                        	Set(key, value []byte) error
                        	// Delete deletes the key. Panics on nil key.
                        	Delete(key []byte) error
                        }

                        type KeyFormat

                        type KeyFormat struct {
                        	// contains filtered or unexported fields
                        }

                          Provides a fixed-width lexicographically sortable []byte key format

                          func NewKeyFormat

                          func NewKeyFormat(prefix string, layout ...int) (*KeyFormat, error)

                            Create a []byte key format based on a single byte prefix and fixed width key segments each of whose length is specified by by the corresponding element of layout. A final segment length of 0 can be used to indicate a variadic final element that may be of arbitrary length.

                            For example, to store keys that could index some objects by a version number and their SHA256 hash using the form: 'c<version uint64><hash [32]byte>' then you would define the KeyFormat with:

                            var keyFormat = NewKeyFormat('c', 8, 32)
                            

                            Then you can create a key with:

                            func ObjectKey(version uint64, objectBytes []byte) []byte {
                            	hasher := sha256.New()
                            	hasher.Sum(nil)
                            	return keyFormat.Key(version, hasher.Sum(nil))
                            }}
                            

                            func (*KeyFormat) Fix

                            func (kf *KeyFormat) Fix(args ...interface{}) (*KeyFormat, error)

                              Fixes the first args many segments as the prefix of a new KeyFormat by using the args to generate a key that becomes that prefix. Any remaining unassigned segments become the layout of the new KeyFormat.

                              func (*KeyFormat) Iterator

                              func (kf *KeyFormat) Iterator(iterable KVIterable, start, end []byte, reverse ...bool) (KVIterator, error)

                                Returns an iterator over the underlying iterable using this KeyFormat's prefix. This is to support proper iteration over the prefix in the presence of nil start or end which requests iteration to the inclusive edges of the domain. An optional argument for reverse can be passed to get reverse iteration.

                                func (*KeyFormat) Key

                                func (kf *KeyFormat) Key(args ...interface{}) ([]byte, error)

                                  Format the args passed into the key format - will panic if the arguments passed do not match the length of the segment to which they correspond. When called with no arguments returns the raw prefix (useful as a start element of the entire keys space when sorted lexicographically).

                                  func (*KeyFormat) KeyBytes

                                  func (kf *KeyFormat) KeyBytes(segments ...[]byte) ([]byte, error)

                                    Format the byte segments into the key format - will panic if the segment lengths do not match the layout.

                                    func (*KeyFormat) KeyNoPrefix

                                    func (kf *KeyFormat) KeyNoPrefix(args ...interface{}) (Prefix, error)

                                      Like Key but removes the prefix string

                                      func (*KeyFormat) Layout

                                      func (kf *KeyFormat) Layout() []int

                                      func (*KeyFormat) NumSegments

                                      func (kf *KeyFormat) NumSegments() int

                                      func (*KeyFormat) Prefix

                                      func (kf *KeyFormat) Prefix() Prefix

                                        Return the Key as a prefix - may just be the literal prefix, or an entire key

                                        func (*KeyFormat) Scan

                                        func (kf *KeyFormat) Scan(key []byte, args ...interface{}) error

                                          Extracts the segments into the values pointed to by each of args. Each arg must be a pointer to int64, uint64, or []byte, and the width of the args must match layout.

                                          func (*KeyFormat) ScanBytes

                                          func (kf *KeyFormat) ScanBytes(key []byte) [][]byte

                                            Reads out the bytes associated with each segment of the key format from key.

                                            func (*KeyFormat) ScanNoPrefix

                                            func (kf *KeyFormat) ScanNoPrefix(key []byte, args ...interface{}) error

                                              Like Scan but adds expects a key with the KeyFormat's prefix trimmed

                                              func (*KeyFormat) String

                                              func (kf *KeyFormat) String() string

                                              func (*KeyFormat) Unprefixed

                                              func (kf *KeyFormat) Unprefixed() *KeyFormat

                                              type MustKeyFormat

                                              type MustKeyFormat struct {
                                              	KeyFormat
                                              }

                                                MustKeyFormat for panicking early when a KeyFormat does not parse

                                                func NewMustKeyFormat

                                                func NewMustKeyFormat(prefix string, layout ...int) *MustKeyFormat

                                                func (*MustKeyFormat) Fix

                                                func (kf *MustKeyFormat) Fix(args ...interface{}) *MustKeyFormat

                                                func (*MustKeyFormat) Key

                                                func (kf *MustKeyFormat) Key(args ...interface{}) []byte

                                                func (*MustKeyFormat) KeyBytes

                                                func (kf *MustKeyFormat) KeyBytes(segments ...[]byte) []byte

                                                func (*MustKeyFormat) KeyNoPrefix

                                                func (kf *MustKeyFormat) KeyNoPrefix(args ...interface{}) Prefix

                                                func (*MustKeyFormat) Unprefixed

                                                func (kf *MustKeyFormat) Unprefixed() *MustKeyFormat

                                                type MutableForest

                                                type MutableForest struct {
                                                
                                                	// Much of the implementation of MutableForest is contained in ImmutableForest which is embedded here and used
                                                	// mutable via its private API. This embedded instance holds a reference to commitsTree above.
                                                	*ImmutableForest
                                                	// contains filtered or unexported fields
                                                }

                                                func NewMutableForest

                                                func NewMutableForest(db dbm.DB, cacheSize int) (*MutableForest, error)

                                                func (*MutableForest) Delete

                                                func (muf *MutableForest) Delete(prefix []byte) (*CommitID, error)

                                                  Delete a tree - if the tree exists will return the CommitID of the latest saved version

                                                  func (*MutableForest) GetImmutable

                                                  func (muf *MutableForest) GetImmutable(version int64) (*ImmutableForest, error)

                                                  func (*MutableForest) Hash

                                                  func (muf *MutableForest) Hash() []byte

                                                    Get the current global hash for all trees in this forest

                                                    func (*MutableForest) IterateRWTree

                                                    func (muf *MutableForest) IterateRWTree(start, end []byte, ascending bool, fn func(prefix []byte, tree *RWTree) error) error

                                                    func (*MutableForest) Load

                                                    func (muf *MutableForest) Load(version int64) error

                                                      Load mutable forest from database

                                                      func (*MutableForest) Save

                                                      func (muf *MutableForest) Save() (hash []byte, version int64, _ error)

                                                      func (*MutableForest) Version

                                                      func (muf *MutableForest) Version() int64

                                                        Get the current global version for all versions of all trees in this forest

                                                        func (*MutableForest) Writer

                                                        func (muf *MutableForest) Writer(prefix []byte) (*RWTree, error)

                                                          Calls to writer should be serialised as should writes to the tree

                                                          type MutableTree

                                                          type MutableTree struct {
                                                          	*iavl.MutableTree
                                                          }

                                                            We wrap IAVL's tree types in order to implement standard DB interface and iteration helpers

                                                            func NewMutableTree

                                                            func NewMutableTree(db dbm.DB, cacheSize int) (*MutableTree, error)

                                                            func (*MutableTree) Get

                                                            func (mut *MutableTree) Get(key []byte) ([]byte, error)

                                                            func (*MutableTree) GetImmutable

                                                            func (mut *MutableTree) GetImmutable(version int64) (*ImmutableTree, error)

                                                            func (*MutableTree) Has

                                                            func (mut *MutableTree) Has(key []byte) (bool, error)

                                                            func (*MutableTree) Iterate

                                                            func (mut *MutableTree) Iterate(start, end []byte, ascending bool, fn func(key []byte, value []byte) error) error

                                                            func (*MutableTree) IterateWriteTree

                                                            func (mut *MutableTree) IterateWriteTree(start, end []byte, ascending bool, fn func(key []byte, value []byte) error) error

                                                            func (*MutableTree) Load

                                                            func (mut *MutableTree) Load(version int64, overwriting bool) error

                                                            type Prefix

                                                            type Prefix []byte

                                                            func NewPrefix

                                                            func NewPrefix(bs []byte) Prefix

                                                            func (Prefix) Above

                                                            func (p Prefix) Above() []byte

                                                              Get the lexicographical sibling above this prefix (i.e. the fixed length integer plus one)

                                                              func (Prefix) Below

                                                              func (p Prefix) Below() []byte

                                                                Get the lexicographical sibling below this prefix (i.e. the fixed length integer minus one)

                                                                func (Prefix) CallbackIterable

                                                                func (p Prefix) CallbackIterable(source KVCallbackIterable) *prefixCallbackIterable

                                                                func (Prefix) HexString

                                                                func (p Prefix) HexString() string

                                                                func (Prefix) Iterable

                                                                func (p Prefix) Iterable(source KVIterable) KVIterable

                                                                func (Prefix) Iterator

                                                                func (p Prefix) Iterator(iteratorFn func(start, end []byte) (dbm.Iterator, error), start, end []byte) (KVIterator, error)

                                                                func (Prefix) Key

                                                                func (p Prefix) Key(key []byte) []byte

                                                                func (Prefix) Length

                                                                func (p Prefix) Length() int

                                                                func (Prefix) Store

                                                                func (p Prefix) Store(source KVStore) KVStore

                                                                func (Prefix) String

                                                                func (p Prefix) String() string

                                                                func (Prefix) Suffix

                                                                func (p Prefix) Suffix(key []byte) []byte

                                                                type PrefixDB

                                                                type PrefixDB struct {
                                                                	// contains filtered or unexported fields
                                                                }

                                                                func NewPrefixDB

                                                                func NewPrefixDB(db dbm.DB, prefix string) *PrefixDB

                                                                func (*PrefixDB) Close

                                                                func (pdb *PrefixDB) Close() error

                                                                func (*PrefixDB) Delete

                                                                func (pdb *PrefixDB) Delete(key []byte) error

                                                                func (*PrefixDB) DeleteSync

                                                                func (pdb *PrefixDB) DeleteSync(key []byte) error

                                                                func (*PrefixDB) Get

                                                                func (pdb *PrefixDB) Get(key []byte) ([]byte, error)

                                                                  DB implementation

                                                                  func (*PrefixDB) Has

                                                                  func (pdb *PrefixDB) Has(key []byte) (bool, error)

                                                                  func (*PrefixDB) Iterator

                                                                  func (pdb *PrefixDB) Iterator(low, high []byte) (KVIterator, error)

                                                                  func (*PrefixDB) NewBatch

                                                                  func (pdb *PrefixDB) NewBatch() dbm.Batch

                                                                  func (*PrefixDB) Print

                                                                  func (pdb *PrefixDB) Print() error

                                                                  func (*PrefixDB) ReverseIterator

                                                                  func (pdb *PrefixDB) ReverseIterator(low, high []byte) (KVIterator, error)

                                                                  func (*PrefixDB) Set

                                                                  func (pdb *PrefixDB) Set(key, value []byte) error

                                                                  func (*PrefixDB) SetSync

                                                                  func (pdb *PrefixDB) SetSync(key, value []byte) error

                                                                  func (*PrefixDB) Stats

                                                                  func (pdb *PrefixDB) Stats() map[string]string

                                                                  type RWTree

                                                                  type RWTree struct {
                                                                  
                                                                  	// Read-only tree serving previous state
                                                                  	*ImmutableTree
                                                                  	// contains filtered or unexported fields
                                                                  }

                                                                    RWTree provides an abstraction over IAVL that maintains separate read and write paths. Reads are routed to the most recently saved version of the tree - which provides immutable access. Writes are routed to a working tree that is mutable. On save the working tree is saved to DB, frozen, and replaces the previous immutable read tree.

                                                                    func NewRWTree

                                                                    func NewRWTree(db dbm.DB, cacheSize int) (*RWTree, error)

                                                                      Creates a concurrency safe version of an IAVL tree whereby reads are routed to the last saved tree. Writes must be serialised (as they are within a commit for example).

                                                                      func (*RWTree) Delete

                                                                      func (rwt *RWTree) Delete(key []byte) ([]byte, bool)

                                                                      func (*RWTree) Dump

                                                                      func (rwt *RWTree) Dump() string

                                                                      func (*RWTree) GetImmutable

                                                                      func (rwt *RWTree) GetImmutable(version int64) (*ImmutableTree, error)

                                                                      func (*RWTree) IterateWriteTree

                                                                      func (rwt *RWTree) IterateWriteTree(start, end []byte, ascending bool, fn func(key []byte, value []byte) error) error

                                                                      func (*RWTree) Load

                                                                      func (rwt *RWTree) Load(version int64, overwriting bool) error

                                                                        Tries to load the execution state from DB, returns nil with no error if no state found

                                                                        func (*RWTree) Save

                                                                        func (rwt *RWTree) Save() ([]byte, int64, error)

                                                                          Save the current write tree making writes accessible from read tree.

                                                                          func (*RWTree) Set

                                                                          func (rwt *RWTree) Set(key, value []byte) bool

                                                                          func (*RWTree) Updated

                                                                          func (rwt *RWTree) Updated() bool

                                                                            Returns true if there have been any writes since last save

                                                                            type SortOrder

                                                                            type SortOrder byte
                                                                            const (
                                                                            	AscendingSort SortOrder = iota
                                                                            	DescendingSort
                                                                            )