Fix obsolete _bt_first comments.

_bt_first doesn't necessarily hold onto a buffer pin on success exit.
Fix header comments that claimed that we'll always hold onto a pin.

Oversight in commit 2ed5b87f96.

diff --git a/src/backend/access/nbtree/nbtsearch.c b/src/backend/access/nbtree/nbtsearch.c
index d6023732c9bcdc7fa1386d27b1ed24700f1ac2a0..1608dd49d5721705befba9c32794bc7d0033d5d1 100644 (file)
--- a/src/backend/access/nbtree/nbtsearch.c
+++ b/src/backend/access/nbtree/nbtsearch.c
@@ -862,14 +862,15 @@ _bt_compare(Relation rel,
  *     We need to be clever about the direction of scan, the search
  *     conditions, and the tree ordering.  We find the first item (or,
  *     if backwards scan, the last item) in the tree that satisfies the
- *     qualifications in the scan key.  On success exit, the page containing
- *     the current index tuple is pinned but not locked, and data about
- *     the matching tuple(s) on the page has been loaded into so->currPos.
+ *     qualifications in the scan key.  On success exit, data about the
+ *     matching tuple(s) on the page has been loaded into so->currPos.  We'll
+ *     drop all locks and hold onto a pin on page's buffer, except when
+ *     _bt_drop_lock_and_maybe_pin dropped the pin to avoid blocking VACUUM.
  *     scan->xs_heaptid is set to the heap TID of the current tuple, and if
  *     requested, scan->xs_itup points to a copy of the index tuple.
  *
  * If there are no matching items in the index, we return false, with no
- * pins or locks held.
+ * pins or locks held.  so->currPos will remain invalid.
  *
  * Note that scan->keyData[], and the so->keyData[] scankey built from it,
  * are both search-type scankeys (see nbtree/README for more about this).
@@ -1470,6 +1471,8 @@ _bt_next(IndexScanDesc scan, ScanDirection dir)
    BTScanOpaque so = (BTScanOpaque) scan->opaque;
    BTScanPosItem *currItem;
 
+   Assert(BTScanPosIsValid(so->currPos));
+
    /*
     * Advance to next tuple on current page; or if there's no more, try to
     * step to the next page with data.