tableam: Support for an index build's initial table scan(s).

To support building indexes over tables of different AMs, the scans to
do so need to be routed through the table AM.  While moving a fair
amount of code, nearly all the changes are just moving code to below a
callback.

Currently the range based interface wouldn't make much sense for non
block based table AMs. But that seems aceptable for now.

Author: Andres Freund
Discussion: https://postgr.es/m/20180703070645.wchpu5muyto5n647@alap3.anarazel.de

Author: anarazel

contrib/amcheck/verify_nbtree.c

@@ -23,9 +23,9 @@
  */
 #include "postgres.h"
 
-#include "access/heapam.h"
 #include "access/htup_details.h"
 #include "access/nbtree.h"
+#include "access/table.h"
 #include "access/tableam.h"
 #include "access/transam.h"
 #include "access/xact.h"
@@ -142,7 +142,7 @@ static void bt_tuple_present_callback(Relation index, HeapTuple htup,
 						  Datum *values, bool *isnull,
 						  bool tupleIsAlive, void *checkstate);
 static IndexTuple bt_normalize_tuple(BtreeCheckState *state,
-						   IndexTuple itup);
+				   IndexTuple itup);
 static bool bt_rootdescend(BtreeCheckState *state, IndexTuple itup);
 static inline bool offset_is_negative_infinity(BTPageOpaque opaque,
 							OffsetNumber offset);
@@ -387,10 +387,10 @@ bt_check_every_level(Relation rel, Relation heaprel, bool heapkeyspace,
 
 		/*
 		 * Register our own snapshot in !readonly case, rather than asking
-		 * IndexBuildHeapScan() to do this for us later.  This needs to happen
-		 * before index fingerprinting begins, so we can later be certain that
-		 * index fingerprinting should have reached all tuples returned by
-		 * IndexBuildHeapScan().
+		 * table_index_build_scan() to do this for us later.  This needs to
+		 * happen before index fingerprinting begins, so we can later be
+		 * certain that index fingerprinting should have reached all tuples
+		 * returned by table_index_build_scan().
 		 *
 		 * In readonly case, we also check for problems with missing
 		 * downlinks. A second Bloom filter is used for this.
@@ -525,18 +525,19 @@ bt_check_every_level(Relation rel, Relation heaprel, bool heapkeyspace,
 		}
 
 		/*
-		 * Create our own scan for IndexBuildHeapScan(), rather than getting
-		 * it to do so for us.  This is required so that we can actually use
-		 * the MVCC snapshot registered earlier in !readonly case.
+		 * Create our own scan for table_index_build_scan(), rather than
+		 * getting it to do so for us.  This is required so that we can
+		 * actually use the MVCC snapshot registered earlier in !readonly
+		 * case.
 		 *
-		 * Note that IndexBuildHeapScan() calls heap_endscan() for us.
+		 * Note that table_index_build_scan() calls heap_endscan() for us.
 		 */
-		scan = table_beginscan_strat(state->heaprel, /* relation */
+		scan = table_beginscan_strat(state->heaprel,	/* relation */
 									 snapshot,	/* snapshot */
-									 0,	/* number of keys */
+									 0, /* number of keys */
 									 NULL,	/* scan key */
 									 true,	/* buffer access strategy OK */
-									 true);	/* syncscan OK? */
+									 true); /* syncscan OK? */
 
 		/*
 		 * Scan will behave as the first scan of a CREATE INDEX CONCURRENTLY
@@ -565,8 +566,8 @@ bt_check_every_level(Relation rel, Relation heaprel, bool heapkeyspace,
 			 RelationGetRelationName(state->rel),
 			 RelationGetRelationName(state->heaprel));
 
-		IndexBuildHeapScan(state->heaprel, state->rel, indexinfo, true,
-						   bt_tuple_present_callback, (void *) state, scan);
+		table_index_build_scan(state->heaprel, state->rel, indexinfo, true,
+							   bt_tuple_present_callback, (void *) state, scan);
 
 		ereport(DEBUG1,
 				(errmsg_internal("finished verifying presence of " INT64_FORMAT " tuples from table \"%s\" with bitset %.2f%% set",
@@ -814,7 +815,7 @@ bt_check_level_from_leftmost(BtreeCheckState *state, BtreeLevel level)
  *   (Limited to heapallindexed readonly callers.)
  *
  * This is also where heapallindexed callers use their Bloom filter to
- * fingerprint IndexTuples for later IndexBuildHeapScan() verification.
+ * fingerprint IndexTuples for later table_index_build_scan() verification.
  *
  * Note:  Memory allocated in this routine is expected to be released by caller
  * resetting state->targetcontext.
@@ -1776,7 +1777,7 @@ bt_downlink_missing_check(BtreeCheckState *state)
 }
 
 /*
- * Per-tuple callback from IndexBuildHeapScan, used to determine if index has
+ * Per-tuple callback from table_index_build_scan, used to determine if index has
  * all the entries that definitely should have been observed in leaf pages of
  * the target index (that is, all IndexTuples that were fingerprinted by our
  * Bloom filter).  All heapallindexed checks occur here.
@@ -1801,7 +1802,7 @@ bt_downlink_missing_check(BtreeCheckState *state)
  * verification, just in case it's a cross-page invariant issue, though that
  * isn't particularly likely.
  *
- * IndexBuildHeapScan() expects to be able to find the root tuple when a
+ * table_index_build_scan() expects to be able to find the root tuple when a
  * heap-only tuple (the live tuple at the end of some HOT chain) needs to be
  * indexed, in order to replace the actual tuple's TID with the root tuple's
  * TID (which is what we're actually passed back here).  The index build heap
@@ -1817,7 +1818,7 @@ bt_downlink_missing_check(BtreeCheckState *state)
  * setting will probably also leave the index in a corrupt state before too
  * long, the problem is nonetheless that there is heap corruption.)
  *
- * Heap-only tuple handling within IndexBuildHeapScan() works in a way that
+ * Heap-only tuple handling within table_index_build_scan() works in a way that
  * helps us to detect index tuples that contain the wrong values (values that
  * don't match the latest tuple in the HOT chain).  This can happen when there
  * is no superseding index tuple due to a faulty assessment of HOT safety,

contrib/bloom/blinsert.c

@@ -14,6 +14,7 @@
 
 #include "access/genam.h"
 #include "access/generic_xlog.h"
+#include "access/tableam.h"
 #include "catalog/index.h"
 #include "miscadmin.h"
 #include "storage/bufmgr.h"
@@ -69,7 +70,7 @@ initCachedPage(BloomBuildState *buildstate)
 }
 
 /*
- * Per-tuple callback from IndexBuildHeapScan.
+ * Per-tuple callback for table_index_build_scan.
  */
 static void
 bloomBuildCallback(Relation index, HeapTuple htup, Datum *values,
@@ -141,9 +142,9 @@ blbuild(Relation heap, Relation index, IndexInfo *indexInfo)
 	initCachedPage(&buildstate);
 
 	/* Do the heap scan */
-	reltuples = IndexBuildHeapScan(heap, index, indexInfo, true,
-								   bloomBuildCallback, (void *) &buildstate,
-								   NULL);
+	reltuples = table_index_build_scan(heap, index, indexInfo, true,
+									   bloomBuildCallback, (void *) &buildstate,
+									   NULL);
 
 	/* Flush last page if needed (it will be, unless heap was empty) */
 	if (buildstate.count > 0)

doc/src/sgml/indexam.sgml

@@ -238,7 +238,7 @@ ambuild (Relation heapRelation,
    but is empty.  It must be filled in with whatever fixed data the
    access method requires, plus entries for all tuples already existing
    in the table.  Ordinarily the <function>ambuild</function> function will call
-   <function>IndexBuildHeapScan()</function> to scan the table for existing tuples
+   <function>table_index_build_scan()</function> to scan the table for existing tuples
    and compute the keys that need to be inserted into the index.
    The function must return a palloc'd struct containing statistics about
    the new index.

src/backend/access/brin/brin.c

@@ -23,6 +23,7 @@
 #include "access/reloptions.h"
 #include "access/relscan.h"
 #include "access/table.h"
+#include "access/tableam.h"
 #include "access/xloginsert.h"
 #include "catalog/index.h"
 #include "catalog/pg_am.h"
@@ -587,7 +588,7 @@ brinendscan(IndexScanDesc scan)
 }
 
 /*
- * Per-heap-tuple callback for IndexBuildHeapScan.
+ * Per-heap-tuple callback for table_index_build_scan.
  *
  * Note we don't worry about the page range at the end of the table here; it is
  * present in the build state struct after we're called the last time, but not
@@ -718,8 +719,8 @@ brinbuild(Relation heap, Relation index, IndexInfo *indexInfo)
 	 * Now scan the relation.  No syncscan allowed here because we want the
 	 * heap blocks in physical order.
 	 */
-	reltuples = IndexBuildHeapScan(heap, index, indexInfo, false,
-								   brinbuildCallback, (void *) state, NULL);
+	reltuples = table_index_build_scan(heap, index, indexInfo, false,
+									   brinbuildCallback, (void *) state, NULL);
 
 	/* process the final batch */
 	form_and_insert_tuple(state);
@@ -1230,13 +1231,14 @@ summarize_range(IndexInfo *indexInfo, BrinBuildState *state, Relation heapRel,
 	 * short of brinbuildCallback creating the new index entry.
 	 *
 	 * Note that it is critical we use the "any visible" mode of
-	 * IndexBuildHeapRangeScan here: otherwise, we would miss tuples inserted
-	 * by transactions that are still in progress, among other corner cases.
+	 * table_index_build_range_scan here: otherwise, we would miss tuples
+	 * inserted by transactions that are still in progress, among other corner
+	 * cases.
 	 */
 	state->bs_currRangeStart = heapBlk;
-	IndexBuildHeapRangeScan(heapRel, state->bs_irel, indexInfo, false, true,
-							heapBlk, scanNumBlks,
-							brinbuildCallback, (void *) state, NULL);
+	table_index_build_range_scan(heapRel, state->bs_irel, indexInfo, false, true,
+								 heapBlk, scanNumBlks,
+								 brinbuildCallback, (void *) state, NULL);
 
 	/*
 	 * Now we update the values obtained by the scan with the placeholder

src/backend/access/gin/gininsert.c

@@ -17,6 +17,7 @@
 #include "access/gin_private.h"
 #include "access/ginxlog.h"
 #include "access/xloginsert.h"
+#include "access/tableam.h"
 #include "catalog/index.h"
 #include "miscadmin.h"
 #include "storage/bufmgr.h"
@@ -394,8 +395,9 @@ ginbuild(Relation heap, Relation index, IndexInfo *indexInfo)
 	 * Do the heap scan.  We disallow sync scan here because dataPlaceToPage
 	 * prefers to receive tuples in TID order.
 	 */
-	reltuples = IndexBuildHeapScan(heap, index, indexInfo, false,
-								   ginBuildCallback, (void *) &buildstate, NULL);
+	reltuples = table_index_build_scan(heap, index, indexInfo, false,
+									   ginBuildCallback, (void *) &buildstate,
+									   NULL);
 
 	/* dump remaining entries to the index */
 	oldCtx = MemoryContextSwitchTo(buildstate.tmpCtx);

src/backend/access/gist/gistbuild.c

@@ -19,6 +19,7 @@
 #include "access/genam.h"
 #include "access/gist_private.h"
 #include "access/gistxlog.h"
+#include "access/tableam.h"
 #include "access/xloginsert.h"
 #include "catalog/index.h"
 #include "miscadmin.h"
@@ -204,8 +205,9 @@ gistbuild(Relation heap, Relation index, IndexInfo *indexInfo)
 	/*
 	 * Do the heap scan.
 	 */
-	reltuples = IndexBuildHeapScan(heap, index, indexInfo, true,
-								   gistBuildCallback, (void *) &buildstate, NULL);
+	reltuples = table_index_build_scan(heap, index, indexInfo, true,
+									   gistBuildCallback,
+									   (void *) &buildstate, NULL);
 
 	/*
 	 * If buffering was used, flush out all the tuples that are still in the
@@ -454,7 +456,7 @@ calculatePagesPerBuffer(GISTBuildState *buildstate, int levelStep)
 }
 
 /*
- * Per-tuple callback from IndexBuildHeapScan.
+ * Per-tuple callback for table_index_build_scan.
  */
 static void
 gistBuildCallback(Relation index,

src/backend/access/hash/hash.c

@@ -21,6 +21,7 @@
 #include "access/hash.h"
 #include "access/hash_xlog.h"
 #include "access/relscan.h"
+#include "access/tableam.h"
 #include "catalog/index.h"
 #include "commands/vacuum.h"
 #include "miscadmin.h"
@@ -159,8 +160,9 @@ hashbuild(Relation heap, Relation index, IndexInfo *indexInfo)
 	buildstate.heapRel = heap;
 
 	/* do the heap scan */
-	reltuples = IndexBuildHeapScan(heap, index, indexInfo, true,
-								   hashbuildCallback, (void *) &buildstate, NULL);
+	reltuples = table_index_build_scan(heap, index, indexInfo, true,
+									   hashbuildCallback,
+									   (void *) &buildstate, NULL);
 
 	if (buildstate.spool)
 	{
@@ -190,7 +192,7 @@ hashbuildempty(Relation index)
 }
 
 /*
- * Per-tuple callback from IndexBuildHeapScan
+ * Per-tuple callback for table_index_build_scan
  */
 static void
 hashbuildCallback(Relation index,