update comments for Get method

Author: zhangchiqing

storage/operation/badgerimpl/reader.go

@@ -28,8 +28,9 @@ func (noopCloser) Close() error { return nil }
 //
 // The caller should not modify the contents of the returned slice, but it is
 // safe to modify the contents of the argument after Get returns. The
-// returned slice will remain valid until the returned Closer is closed. On
-// success, the caller MUST call closer.Close() or a memory leak will occur.
+// returned slice will remain valid until the returned Closer is closed.
+// when err == nil, the caller MUST call closer.Close() or a memory leak will occur.
+// when err != nil, then the caller io.Closer is nil, and should not be called
 func (b dbReader) Get(key []byte) ([]byte, io.Closer, error) {
 	tx := b.db.NewTransaction(false)
 	defer tx.Discard()

storage/operation/pebbleimpl/reader.go

@@ -30,8 +30,9 @@ func (noopCloser) Close() error { return nil }
 //
 // The caller should not modify the contents of the returned slice, but it is
 // safe to modify the contents of the argument after Get returns. The
-// returned slice will remain valid until the returned Closer is closed. On
-// success, the caller MUST call closer.Close() or a memory leak will occur.
+// returned slice will remain valid until the returned Closer is closed.
+// when err == nil, the caller MUST call closer.Close() or a memory leak will occur.
+// when err != nil, then the caller io.Closer is nil, and should not be called
 func (b dbReader) Get(key []byte) ([]byte, io.Closer, error) {
 	value, closer, err := b.db.Get(key)
 

storage/operation/reads.go

@@ -121,28 +121,39 @@ func Traverse(prefix []byte, iterFunc IterationFunc, opt storage.IteratorOption)
 	return Iterate(prefix, prefix, iterFunc, opt)
 }
 
-// Exists returns true if a key exists in the database.
+// Exists takes a key and a pointer to an a boolean variable `keyExists` as inputs and returns an function.
+// When this returned function is executed (and only then), it will write into the `keyExists` whether
+// the key exists.
 // No errors are expected during normal operation.
 func Exists(key []byte, keyExists *bool) func(storage.Reader) error {
 	return func(r storage.Reader) error {
-		_, closer, err := r.Get(key)
+		exists, err := KeyExists(r, key)
 		if err != nil {
-			// the key does not exist in the database
-			if errors.Is(err, storage.ErrNotFound) {
-				*keyExists = false
-				return nil
-			}
-			// exception while checking for the key
-			return irrecoverable.NewExceptionf("could not load data: %w", err)
+			return err
 		}
-		defer closer.Close()
-
-		// the key does exist in the database
-		*keyExists = true
+		*keyExists = exists
 		return nil
 	}
 }
 
+// KeyExists returns true if a key exists in the database.
+// No errors are expected during normal operation.
+func KeyExists(r storage.Reader, key []byte) (bool, error) {
+	_, closer, err := r.Get(key)
+	if err != nil {
+		// the key does not exist in the database
+		if errors.Is(err, storage.ErrNotFound) {
+			return false, nil
+		}
+		// exception while checking for the key
+		return false, irrecoverable.NewExceptionf("could not load data: %w", err)
+	}
+	defer closer.Close()
+
+	// the key does exist in the database
+	return true, nil
+}
+
 // Retrieve will retrieve the binary data under the given key from the database
 // and decode it into the given entity. The provided entity needs to be a
 // pointer to an initialized entity of the correct type.

storage/operations.go

@@ -72,8 +72,9 @@ type Reader interface {
 	//
 	// The caller should not modify the contents of the returned slice, but it is
 	// safe to modify the contents of the `key` argument after Get returns. The
-	// returned slice will remain valid until the returned Closer is closed. On
-	// success, the caller MUST call closer.Close() or a memory leak will occur.
+	// returned slice will remain valid until the returned Closer is closed.
+	// when err == nil, the caller MUST call closer.Close() or a memory leak will occur.
+	// when err != nil, then the caller io.Closer is nil, and should not be called
 	Get(key []byte) (value []byte, closer io.Closer, err error)
 
 	// NewIter returns a new Iterator for the given key prefix range [startPrefix, endPrefix], both inclusive.