From: Peter Geoghegan <pg@bowt.ie>
Date: Wed, 30 Oct 2024 17:43:49 +0000 (-0400)
Subject: Clarify nbtree array exhaustion comments.
X-Git-Url: http://git.postgresql.org/gitweb/?a=commitdiff_plain;h=81a25790f1f66319b4f088148b97dbb8badd4907;p=postgresql.git

Clarify nbtree array exhaustion comments.

Strictly speaking, we only need to make sure to leave the scan's array
keys in their final positions (final for the current scan direction) to
handle SAOP array exhaustion because btgettuple might only return a
subset of the items for the final page (final for the current scan
direction), before the scan changes direction.  While it's typical for
so->currPos to be invalidated shortly after the scan's arrays are first
exhausted, and while so->currPos invalidation does obviate the need to
leave the scan's arrays in any particular state, we can't rely on any of
that actually happening when handling array exhaustion.  Adjust comments
to make all of that a lot clearer.

Oversight in commit 5bf748b8, which enhanced nbtree ScalarArrayOp
execution.
---

diff --git a/src/backend/access/nbtree/nbtutils.c b/src/backend/access/nbtree/nbtutils.c
index 20227989c6d..14253ead8bd 100644
--- a/src/backend/access/nbtree/nbtutils.c
+++ b/src/backend/access/nbtree/nbtutils.c
@@ -1424,14 +1424,19 @@ _bt_advance_array_keys_increment(IndexScanDesc scan, ScanDirection dir)
 	}
 
 	/*
-	 * The array keys are now exhausted.  (There isn't actually a distinct
-	 * state that represents array exhaustion, since index scans don't always
-	 * end after btgettuple returns "false".)
+	 * The array keys are now exhausted.
 	 *
 	 * Restore the array keys to the state they were in immediately before we
 	 * were called.  This ensures that the arrays only ever ratchet in the
-	 * current scan direction.  Without this, scans would overlook matching
-	 * tuples if and when the scan's direction was subsequently reversed.
+	 * current scan direction.
+	 *
+	 * Without this, scans could overlook matching tuples when the scan
+	 * direction gets reversed just before btgettuple runs out of items to
+	 * return, but just after _bt_readpage prepares all the items from the
+	 * scan's final page in so->currPos.  When we're on the final page it is
+	 * typical for so->currPos to get invalidated once btgettuple finally
+	 * returns false, which'll effectively invalidate the scan's array keys.
+	 * That hasn't happened yet, though -- and in general it may never happen.
 	 */
 	_bt_start_array_keys(scan, -dir);