Clarify nbtree array exhaustion comments.

petergeoghegan · petergeoghegan · commit 81a25790f1f6 · 2024-10-30T13:43:49.000-04:00
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 5bf748b, which enhanced nbtree ScalarArrayOp execution.
diff --git 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);
 
