github.com/petermattis/pebble@v0.0.0-20190905164901-ab51a2166067/internal/base/iterator.go (about)

     1  // Copyright 2019 The LevelDB-Go and Pebble Authors. All rights reserved. Use
     2  // of this source code is governed by a BSD-style license that can be found in
     3  // the LICENSE file.
     4  
     5  package base
     6  
     7  // InternalIterator iterates over a DB's key/value pairs in key order. Unlike
     8  // the Iterator interface, the returned keys are InternalKeys composed of the
     9  // user-key, a sequence number and a key kind. In forward iteration, key/value
    10  // pairs for identical user-keys are returned in descending sequence order. In
    11  // reverse iteration, key/value pairs for identical user-keys are returned in
    12  // ascending sequence order.
    13  //
    14  // An iterator must be closed after use, but it is not necessary to read an
    15  // iterator until exhaustion.
    16  //
    17  // An iterator is not necessarily goroutine-safe, but it is safe to use
    18  // multiple iterators concurrently, with each in a dedicated goroutine.
    19  //
    20  // It is also safe to use an iterator concurrently with modifying its
    21  // underlying DB, if that DB permits modification. However, the resultant
    22  // key/value pairs are not guaranteed to be a consistent snapshot of that DB
    23  // at a particular point in time.
    24  type InternalIterator interface {
    25  	// SeekGE moves the iterator to the first key/value pair whose key is greater
    26  	// than or equal to the given key. Returns the key and value if the iterator
    27  	// is pointing at a valid entry, and (nil, nil) otherwise.
    28  	SeekGE(key []byte) (*InternalKey, []byte)
    29  
    30  	// SeekPrefixGE moves the iterator to the first key/value pair whose key
    31  	// starts with the given prefix and is greater than or equal to the given
    32  	// key. Returns the key and value if the iterator is pointing at a valid
    33  	// entry, and (nil, nil) otherwise. Note that the iterator will still observe
    34  	// keys not matching the prefix. It is up to the user to check if the prefix
    35  	// matches, and iteration beyond the prefix is undefined.
    36  	SeekPrefixGE(prefix, key []byte) (*InternalKey, []byte)
    37  
    38  	// SeekLT moves the iterator to the last key/value pair whose key is less
    39  	// than the given key. Returns the key and value if the iterator is pointing
    40  	// at a valid entry, and (nil, nil) otherwise.
    41  	SeekLT(key []byte) (*InternalKey, []byte)
    42  
    43  	// First moves the iterator the the first key/value pair. Returns the key and
    44  	// value if the iterator is pointing at a valid entry, and (nil, nil)
    45  	// otherwise.
    46  	First() (*InternalKey, []byte)
    47  
    48  	// Last moves the iterator the the last key/value pair. Returns the key and
    49  	// value if the iterator is pointing at a valid entry, and (nil, nil)
    50  	// otherwise.
    51  	Last() (*InternalKey, []byte)
    52  
    53  	// Next moves the iterator to the next key/value pair. Returns the key and
    54  	// value if the iterator is pointing at a valid entry, and (nil, nil)
    55  	// otherwise.
    56  	Next() (*InternalKey, []byte)
    57  
    58  	// Prev moves the iterator to the previous key/value pair. Returns the key
    59  	// and value if the iterator is pointing at a valid entry, and (nil, nil)
    60  	// otherwise.
    61  	Prev() (*InternalKey, []byte)
    62  
    63  	// Key returns the encoded internal key of the current key/value pair, or nil
    64  	// if done. The caller should not modify the contents of the returned key,
    65  	// and its contents may change on the next call to Next.
    66  	Key() *InternalKey
    67  
    68  	// Value returns the value of the current key/value pair, or nil if done.
    69  	// The caller should not modify the contents of the returned slice, and
    70  	// its contents may change on the next call to Next.
    71  	Value() []byte
    72  
    73  	// Valid returns true if the iterator is positioned at a valid key/value pair
    74  	// and false otherwise.
    75  	Valid() bool
    76  
    77  	// Error returns any accumulated error.
    78  	Error() error
    79  
    80  	// Close closes the iterator and returns any accumulated error. Exhausting
    81  	// all the key/value pairs in a table is not considered to be an error.
    82  	// It is valid to call Close multiple times. Other methods should not be
    83  	// called after the iterator has been closed.
    84  	Close() error
    85  
    86  	// SetBounds sets the lower and upper bounds for the iterator. Note that the
    87  	// result of Next and Prev will be undefined until the iterator has been
    88  	// repositioned with SeekGE, SeekPrefixGE, SeekLT, First, or Last.
    89  	SetBounds(lower, upper []byte)
    90  }