From af058cd8761c5b89352d884670576f93e99032c9 Mon Sep 17 00:00:00 2001 From: Pavel Kalinnikov Date: Thu, 20 Nov 2025 22:57:36 +0000 Subject: [PATCH] storage: clarify consistency as of when This commit clarifies in Engine.NewReader that consistent iterators are not that as of the NewReader() call time. This is already mentioned in the Reader interface comment, but it is easy to miss in the details. Worth calling it out in the NewReader comment directly because this is the user's entry point into "reading" and it proved easy to assume that this is where consistency happens. Epic: none Release note: none --- pkg/storage/engine.go | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/pkg/storage/engine.go b/pkg/storage/engine.go index 38ae34abd18e..c4e7e017bae6 100644 --- a/pkg/storage/engine.go +++ b/pkg/storage/engine.go @@ -594,6 +594,7 @@ type Reader interface { visitSharedFile func(sst *pebble.SharedSSTMeta) error, visitExternalFile func(sst *pebble.ExternalFile) error, ) error + // ConsistentIterators returns true if the Reader implementation guarantees // that the different iterators constructed by this Reader will see the same // underlying Engine state. This is not true about Batch writes: new iterators @@ -963,6 +964,11 @@ type Engine interface { // All iterators created from a read-only engine are guaranteed to provide a // consistent snapshot of the underlying engine. See the comment on the // Reader interface and the Reader.ConsistentIterators method. + // + // NB: consistent iterators are not as of when NewReader is called. They are + // as of the time when the first iterator is created (often, this is when the + // first read happens if iterators are not used directly), or earlier if + // Reader.PinEngineStateForIterators is called. NewReader(durability DurabilityRequirement) Reader // NewReadOnly returns a new instance of a ReadWriter that wraps this // engine, and with the given durability requirement. This wrapper panics