github.com/MetalBlockchain/metalgo@v1.11.9/database/iterator.go (about)

     1  // Copyright (C) 2019-2024, Ava Labs, Inc. All rights reserved.
     2  // See the file LICENSE for licensing terms.
     3  
     4  // For ease of implementation, our database's interface matches Ethereum's
     5  // database implementation. This was to allow use to use Geth code as is for the
     6  // EVM chain.
     7  
     8  package database
     9  
    10  var _ Iterator = (*IteratorError)(nil)
    11  
    12  // Iterator iterates over a database's key/value pairs.
    13  //
    14  // When it encounters an error any seek will return false and will yield no key/
    15  // value pairs. The error can be queried by calling the Error method. Calling
    16  // Release is still necessary.
    17  //
    18  // An iterator must be released after use, but it is not necessary to read an
    19  // iterator until exhaustion. An iterator is not safe for concurrent use, but it
    20  // is safe to use multiple iterators concurrently.
    21  type Iterator interface {
    22  	// Next moves the iterator to the next key/value pair. It returns whether
    23  	// the iterator successfully moved to a new key/value pair.
    24  	// The iterator may return false if the underlying database has been closed
    25  	// before the iteration has completed, in which case future calls to Error()
    26  	// must return [ErrClosed].
    27  	Next() bool
    28  
    29  	// Error returns any accumulated error. Exhausting all the key/value pairs
    30  	// is not considered to be an error.
    31  	// Error should be called after all key/value pairs have been exhausted ie.
    32  	// after Next() has returned false.
    33  	Error() error
    34  
    35  	// Key returns the key of the current key/value pair, or nil if done.
    36  	// If the database is closed, must still report the current contents.
    37  	// Behavior is undefined after Release is called.
    38  	Key() []byte
    39  
    40  	// Value returns the value of the current key/value pair, or nil if done.
    41  	// If the database is closed, must still report the current contents.
    42  	// Behavior is undefined after Release is called.
    43  	Value() []byte
    44  
    45  	// Release releases associated resources. Release should always succeed and
    46  	// can be called multiple times without causing error.
    47  	Release()
    48  }
    49  
    50  // Iteratee wraps the NewIterator methods of a backing data store.
    51  type Iteratee interface {
    52  	// NewIterator creates an iterator over the entire keyspace contained within
    53  	// the key-value database.
    54  	NewIterator() Iterator
    55  
    56  	// NewIteratorWithStart creates an iterator over a subset of database
    57  	// content starting at a particular initial key.
    58  	NewIteratorWithStart(start []byte) Iterator
    59  
    60  	// NewIteratorWithPrefix creates an iterator over a subset of database
    61  	// content with a particular key prefix.
    62  	NewIteratorWithPrefix(prefix []byte) Iterator
    63  
    64  	// NewIteratorWithStartAndPrefix creates an iterator over a subset of
    65  	// database content with a particular key prefix starting at a specified
    66  	// key.
    67  	NewIteratorWithStartAndPrefix(start, prefix []byte) Iterator
    68  }
    69  
    70  // IteratorError does nothing and returns the provided error
    71  type IteratorError struct {
    72  	Err error
    73  }
    74  
    75  func (*IteratorError) Next() bool {
    76  	return false
    77  }
    78  
    79  func (i *IteratorError) Error() error {
    80  	return i.Err
    81  }
    82  
    83  func (*IteratorError) Key() []byte {
    84  	return nil
    85  }
    86  
    87  func (*IteratorError) Value() []byte {
    88  	return nil
    89  }
    90  
    91  func (*IteratorError) Release() {}