The GiST README says:
If the F_FOLLOW_RIGHT flag is not set, a scan compares the NSN on the
child and the LSN it saw in the parent. If NSN < LSN, the scan looked
at the parent page before the downlink was inserted, so it should
follow the rightlink. Otherwise the scan saw the downlink in the
parent page, and will/did follow that as usual.
While the code does this (in gistget.c):
if (!XLogRecPtrIsInvalid(pageItem->data.parentlsn) &&
(GistFollowRight(page) ||
pageItem->data.parentlsn < GistPageGetNSN(page)) &&
opaque->rightlink != InvalidBlockNumber /* sanity check */ )
{
/* There was a page split, follow right link to add pages */
Note the comparison on LSN and NSN. The code seems correct, but the
README got it backwards.
The narrow fix would be to change the "NSN < LSN" to "LSN < NSN" in the
README. But I propose the attached patch to reword the sentence a little
more.
--
Heikki Linnakangas
Neon (https://neon.tech)
diff --git a/src/backend/access/gist/README b/src/backend/access/gist/README
index efb2730e18..8015ff19f0 100644
--- a/src/backend/access/gist/README
+++ b/src/backend/access/gist/README
@@ -271,10 +271,10 @@ should be visited too. When split inserts the downlink to the parent, it
clears the F_FOLLOW_RIGHT flag in the child, and sets the NSN field in the
child page header to match the LSN of the insertion on the parent. If the
F_FOLLOW_RIGHT flag is not set, a scan compares the NSN on the child and the
-LSN it saw in the parent. If NSN < LSN, the scan looked at the parent page
-before the downlink was inserted, so it should follow the rightlink. Otherwise
-the scan saw the downlink in the parent page, and will/did follow that as
-usual.
+LSN it saw in the parent. If the child's NSN is greater than the LSN seen on
+the parent, the scan looked at the parent page before the downlink was
+inserted, so it should follow the rightlink. Otherwise the scan saw the
+downlink in the parent page, and will/did follow that as usual.
A scan can't normally see a page with the F_FOLLOW_RIGHT flag set, because
a page split keeps the child pages locked until the downlink has been inserted
