github.com/evdatsion/aphelion-dpos-bft@v0.32.1/libs/db/types.go (about)

     1  package db
     2  
     3  // DBs are goroutine safe.
     4  type DB interface {
     5  
     6  	// Get returns nil iff key doesn't exist.
     7  	// A nil key is interpreted as an empty byteslice.
     8  	// CONTRACT: key, value readonly []byte
     9  	Get([]byte) []byte
    10  
    11  	// Has checks if a key exists.
    12  	// A nil key is interpreted as an empty byteslice.
    13  	// CONTRACT: key, value readonly []byte
    14  	Has(key []byte) bool
    15  
    16  	// Set sets the key.
    17  	// A nil key is interpreted as an empty byteslice.
    18  	// CONTRACT: key, value readonly []byte
    19  	Set([]byte, []byte)
    20  	SetSync([]byte, []byte)
    21  
    22  	// Delete deletes the key.
    23  	// A nil key is interpreted as an empty byteslice.
    24  	// CONTRACT: key readonly []byte
    25  	Delete([]byte)
    26  	DeleteSync([]byte)
    27  
    28  	// Iterate over a domain of keys in ascending order. End is exclusive.
    29  	// Start must be less than end, or the Iterator is invalid.
    30  	// A nil start is interpreted as an empty byteslice.
    31  	// If end is nil, iterates up to the last item (inclusive).
    32  	// CONTRACT: No writes may happen within a domain while an iterator exists over it.
    33  	// CONTRACT: start, end readonly []byte
    34  	Iterator(start, end []byte) Iterator
    35  
    36  	// Iterate over a domain of keys in descending order. End is exclusive.
    37  	// Start must be less than end, or the Iterator is invalid.
    38  	// If start is nil, iterates up to the first/least item (inclusive).
    39  	// If end is nil, iterates from the last/greatest item (inclusive).
    40  	// CONTRACT: No writes may happen within a domain while an iterator exists over it.
    41  	// CONTRACT: start, end readonly []byte
    42  	ReverseIterator(start, end []byte) Iterator
    43  
    44  	// Closes the connection.
    45  	Close()
    46  
    47  	// Creates a batch for atomic updates.
    48  	NewBatch() Batch
    49  
    50  	// For debugging
    51  	Print()
    52  
    53  	// Stats returns a map of property values for all keys and the size of the cache.
    54  	Stats() map[string]string
    55  }
    56  
    57  //----------------------------------------
    58  // Batch
    59  
    60  // Batch Close must be called when the program no longer needs the object.
    61  type Batch interface {
    62  	SetDeleter
    63  	Write()
    64  	WriteSync()
    65  	Close()
    66  }
    67  
    68  type SetDeleter interface {
    69  	Set(key, value []byte) // CONTRACT: key, value readonly []byte
    70  	Delete(key []byte)     // CONTRACT: key readonly []byte
    71  }
    72  
    73  //----------------------------------------
    74  // Iterator
    75  
    76  /*
    77  	Usage:
    78  
    79  	var itr Iterator = ...
    80  	defer itr.Close()
    81  
    82  	for ; itr.Valid(); itr.Next() {
    83  		k, v := itr.Key(); itr.Value()
    84  		// ...
    85  	}
    86  */
    87  type Iterator interface {
    88  
    89  	// The start & end (exclusive) limits to iterate over.
    90  	// If end < start, then the Iterator goes in reverse order.
    91  	//
    92  	// A domain of ([]byte{12, 13}, []byte{12, 14}) will iterate
    93  	// over anything with the prefix []byte{12, 13}.
    94  	//
    95  	// The smallest key is the empty byte array []byte{} - see BeginningKey().
    96  	// The largest key is the nil byte array []byte(nil) - see EndingKey().
    97  	// CONTRACT: start, end readonly []byte
    98  	Domain() (start []byte, end []byte)
    99  
   100  	// Valid returns whether the current position is valid.
   101  	// Once invalid, an Iterator is forever invalid.
   102  	Valid() bool
   103  
   104  	// Next moves the iterator to the next sequential key in the database, as
   105  	// defined by order of iteration.
   106  	//
   107  	// If Valid returns false, this method will panic.
   108  	Next()
   109  
   110  	// Key returns the key of the cursor.
   111  	// If Valid returns false, this method will panic.
   112  	// CONTRACT: key readonly []byte
   113  	Key() (key []byte)
   114  
   115  	// Value returns the value of the cursor.
   116  	// If Valid returns false, this method will panic.
   117  	// CONTRACT: value readonly []byte
   118  	Value() (value []byte)
   119  
   120  	// Close releases the Iterator.
   121  	Close()
   122  }
   123  
   124  // For testing convenience.
   125  func bz(s string) []byte {
   126  	return []byte(s)
   127  }
   128  
   129  // We defensively turn nil keys or values into []byte{} for
   130  // most operations.
   131  func nonNilBytes(bz []byte) []byte {
   132  	if bz == nil {
   133  		return []byte{}
   134  	}
   135  	return bz
   136  }