Update comments on nbtree stack struct.

petergeoghegan · petergeoghegan · commit 091bd6befcb7 · 2019-08-21T13:50:27.000-07:00
Adjust the struct comment that describes how page splits use their
descent stack to cascade up the tree from the leaf level.

In passing, fix up some unrelated nbtree comments that had typos or were
obsolete.
diff --git a/src/backend/access/nbtree/nbtsort.c b/src/backend/access/nbtree/nbtsort.c
@@ -953,7 +953,7 @@ _bt_buildadd(BTWriteState *wstate, BTPageState *state, IndexTuple itup)
 			 *
 			 * We don't try to bias our choice of split point to make it more
 			 * likely that _bt_truncate() can truncate away more attributes,
-			 * whereas the split point passed to _bt_split() is chosen much
+			 * whereas the split point used within _bt_split() is chosen much
 			 * more delicately.  Suffix truncation is mostly useful because it
 			 * improves space utilization for workloads with random
 			 * insertions.  It doesn't seem worthwhile to add logic for
diff --git a/src/backend/access/nbtree/nbtsplitloc.c b/src/backend/access/nbtree/nbtsplitloc.c
@@ -1060,7 +1060,7 @@ _bt_split_penalty(FindSplitData *state, SplitPoint *split)
 }
 
 /*
- * Subroutine to get a lastleft IndexTuple for a spit point from page
+ * Subroutine to get a lastleft IndexTuple for a split point from page
  */
 static inline IndexTuple
 _bt_split_lastleft(FindSplitData *state, SplitPoint *split)
@@ -1076,7 +1076,7 @@ _bt_split_lastleft(FindSplitData *state, SplitPoint *split)
 }
 
 /*
- * Subroutine to get a firstright IndexTuple for a spit point from page
+ * Subroutine to get a firstright IndexTuple for a split point from page
  */
 static inline IndexTuple
 _bt_split_firstright(FindSplitData *state, SplitPoint *split)
diff --git a/src/include/access/nbtree.h b/src/include/access/nbtree.h
@@ -406,8 +406,11 @@ typedef struct BTMetaPageData
  * BTStackData -- As we descend a tree, we push the location of pivot
  * tuples whose downlink we are about to follow onto a private stack.  If
  * we split a leaf, we use this stack to walk back up the tree and insert
- * data into its parent page at the correct location.  We may also have to
- * recursively split a grandparent of the leaf page (and so on).
+ * data into its parent page at the correct location.  We also have to
+ * recursively insert into the grandparent page if and when the parent page
+ * splits.  Our private stack can become stale due to concurrent page
+ * splits and page deletions, but it should never give us an irredeemably
+ * bad picture.
  */
 typedef struct BTStackData
 {

Original file line number	Diff line number	Diff line change
`@@ -953,7 +953,7 @@ _bt_buildadd(BTWriteState wstate, BTPageState state, IndexTuple itup)`
`953`	`953`	`*`
`954`	`954`	`* We don't try to bias our choice of split point to make it more`
`955`	`955`	`* likely that _bt_truncate() can truncate away more attributes,`
`956`		`- * whereas the split point passed to _bt_split() is chosen much`
	`956`	`+ * whereas the split point used within _bt_split() is chosen much`
`957`	`957`	`* more delicately. Suffix truncation is mostly useful because it`
`958`	`958`	`* improves space utilization for workloads with random`
`959`	`959`	`* insertions. It doesn't seem worthwhile to add logic for`