refactor to use KeyCopy

Author: zhangchiqing

storage/operation/pebbleimpl/iterator.go

@@ -67,6 +67,11 @@ func (i pebbleIterItem) Key() []byte {
 	return i.iter.Key()
 }
 
+// KeyCopy returns a copy of the key of the item, writing it to dst slice.
+func (i pebbleIterItem) KeyCopy(dst []byte) []byte {
+	return append(dst[:0], i.iter.Key()...)
+}
+
 func (i pebbleIterItem) Value(fn func([]byte) error) error {
 	val, err := i.iter.ValueAndErr()
 	if err != nil {

storage/operation/reads.go

@@ -28,7 +28,10 @@ type CreateFunc func() interface{}
 type HandleFunc func() error
 type IterationFunc func() (CheckFunc, CreateFunc, HandleFunc)
 
-// IterateKeysInPrefixRange will iterate over all keys with prefixes in the range [startPrefix, endPrefix] (both inclusive)
+// IterateKeysInPrefixRange will iterate over all entries in the database, where the key starts with a prefixes in
+// the range [startPrefix, endPrefix] (both inclusive). We require that startPrefix <= endPrefix (otherwise this
+// function errors). On every such key, the `check` function is called. If `check` errors, iteration is aborted.
+// No errors expected during normal operations.
 func IterateKeysInPrefixRange(startPrefix []byte, endPrefix []byte, check func(key []byte) error) func(storage.Reader) error {
 	return Iterate(startPrefix, endPrefix, func() (CheckFunc, CreateFunc, HandleFunc) {
 		return func(key []byte) (bool, error) {
@@ -164,8 +167,10 @@ func Retrieve(key []byte, entity interface{}) func(storage.Reader) error {
 	}
 }
 
-// FindHighestAtOrBelow finds the highest key with the given prefix and
-// height equal to or below the given height.
+// FindHighestAtOrBelow is for database entries that are indexed by block height. It is suitable to search
+// keys with the format prefix` + `height` (where "+" denotes concatenation of binary strings). The height
+// is encoded as Big-Endian (entries with numerically smaller height have lexicographically smaller key).
+// The function finds the *highest* key with the given prefix and height equal to or below the given height.
 func FindHighestAtOrBelow(prefix []byte, height uint64, entity interface{}) func(storage.Reader) error {
 	return func(r storage.Reader) error {
 		if len(prefix) == 0 {
@@ -180,9 +185,12 @@ func FindHighestAtOrBelow(prefix []byte, height uint64, entity interface{}) func
 		defer it.Close()
 
 		var highestKey []byte
+
 		// find highest value below the given height
 		for it.First(); it.Valid(); it.Next() {
-			highestKey = it.IterItem().Key()
+			// copy the key to avoid the underlying slices of the key
+			// being modified by the Next() call
+			highestKey = it.IterItem().KeyCopy(highestKey)
 		}
 
 		if len(highestKey) == 0 {

storage/operations.go

@@ -27,8 +27,9 @@ type Iterator interface {
 	// The next key-value pair might be invalid, so you should call Valid() to check.
 	Next()
 
-	// IterItem returns the current key-value pair, or nil if done.
-	// A best practice is always to call Valid() before calling IterItem.
+	// IterItem returns the current key-value pair, or nil if Valid returns false.
+	// Always to call Valid() before calling IterItem.
+	// Note, the returned item is only valid until the Next() method is called.
 	IterItem() IterItem
 
 	// Close closes the iterator. Iterator must be closed, otherwise it causes memory leak.
@@ -38,8 +39,16 @@ type Iterator interface {
 
 // IterItem is an interface for iterating over key-value pairs in a storage backend.
 type IterItem interface {
+	// Key returns the key of the current key-value pair
+	// Key is only valid until the Iterator.Next() method is called
+	// If you need to use it outside its validity, please use KeyCopy
 	Key() []byte
 
+	// KeyCopy returns a copy of the key of the item, writing it to dst slice.
+	// If nil is passed, or capacity of dst isn't sufficient, a new slice would be allocated and
+	// returned.
+	KeyCopy(dst []byte) []byte
+
 	// Value returns the value of the current key-value pair
 	// The reason it takes a function is to follow badgerDB's API pattern
 	// No errors expected during normal operation