github.com/gnolang/gno@v0.0.0-20240520182011-228e9d0192ce/tm2/pkg/db/types.go (about)

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