Restructure indexscan API (index_beginscan, index_getnext) per

yesterday's proposal to pghackers.  Also remove unnecessary parameters
to heap_beginscan, heap_rescan.  I modified pg_proc.h to reflect the
new numbers of parameters for the AM interface routines, but did not
force an initdb because nothing actually looks at those fields.

src/include/access/genam.h

@@ -1,13 +1,13 @@
 /*-------------------------------------------------------------------------
  *
  * genam.h
- *	  POSTGRES general access method definitions.
+ *	  POSTGRES generalized index access method definitions.
  *
  *
  * Portions Copyright (c) 1996-2001, PostgreSQL Global Development Group
  * Portions Copyright (c) 1994, Regents of the University of California
  *
- * $Id: genam.h,v 1.33 2002/03/26 19:16:17 tgl Exp $
+ * $Id: genam.h,v 1.34 2002/05/20 23:51:43 tgl Exp $
  *
  *-------------------------------------------------------------------------
  */
@@ -36,12 +36,9 @@ typedef bool (*IndexBulkDeleteCallback) (ItemPointer itemptr, void *state);
 typedef struct SysScanDescData
 {
 	Relation	heap_rel;		/* catalog being scanned */
-	Snapshot	snapshot;		/* time qual (normally SnapshotNow) */
 	Relation	irel;			/* NULL if doing heap scan */
 	HeapScanDesc scan;			/* only valid in heap-scan case */
 	IndexScanDesc iscan;		/* only valid in index-scan case */
-	HeapTupleData tuple;		/* workspace for indexscan */
-	Buffer		buffer;			/* working state for indexscan */
 } SysScanDescData;
 
 typedef SysScanDescData *SysScanDesc;
@@ -54,22 +51,27 @@ extern Relation index_open(Oid relationId);
 extern Relation index_openrv(const RangeVar *relation);
 extern Relation index_openr(const char *sysRelationName);
 extern void index_close(Relation relation);
-extern InsertIndexResult index_insert(Relation relation,
-			 Datum *datum, char *nulls,
+extern InsertIndexResult index_insert(Relation indexRelation,
+			 Datum *datums, char *nulls,
 			 ItemPointer heap_t_ctid,
-			 Relation heapRel);
-extern IndexScanDesc index_beginscan(Relation relation, bool scanFromEnd,
-				uint16 numberOfKeys, ScanKey key);
-extern void index_rescan(IndexScanDesc scan, bool scanFromEnd, ScanKey key);
+			 Relation heapRelation);
+
+extern IndexScanDesc index_beginscan(Relation heapRelation,
+									 Relation indexRelation,
+									 Snapshot snapshot,
+									 int nkeys, ScanKey key);
+extern void index_rescan(IndexScanDesc scan, ScanKey key);
 extern void index_endscan(IndexScanDesc scan);
 extern void index_markpos(IndexScanDesc scan);
 extern void index_restrpos(IndexScanDesc scan);
-extern RetrieveIndexResult index_getnext(IndexScanDesc scan,
-			  ScanDirection direction);
-extern IndexBulkDeleteResult *index_bulk_delete(Relation relation,
+extern HeapTuple index_getnext(IndexScanDesc scan, ScanDirection direction);
+extern bool index_getnext_indexitem(IndexScanDesc scan,
+									ScanDirection direction);
+
+extern IndexBulkDeleteResult *index_bulk_delete(Relation indexRelation,
 				  IndexBulkDeleteCallback callback,
 				  void *callback_state);
-extern RegProcedure index_cost_estimator(Relation relation);
+extern RegProcedure index_cost_estimator(Relation indexRelation);
 extern RegProcedure index_getprocid(Relation irel, AttrNumber attnum,
 				uint16 procnum);
 extern struct FmgrInfo *index_getprocinfo(Relation irel, AttrNumber attnum,
@@ -78,18 +80,18 @@ extern struct FmgrInfo *index_getprocinfo(Relation irel, AttrNumber attnum,
 /*
  * index access method support routines (in genam.c)
  */
-extern IndexScanDesc RelationGetIndexScan(Relation relation, bool scanFromEnd,
-					 uint16 numberOfKeys, ScanKey key);
+extern IndexScanDesc RelationGetIndexScan(Relation indexRelation,
+										  int nkeys, ScanKey key);
 extern void IndexScanEnd(IndexScanDesc scan);
 
 /*
  * heap-or-index access to system catalogs (in genam.c)
  */
-extern SysScanDesc systable_beginscan(Relation rel,
+extern SysScanDesc systable_beginscan(Relation heapRelation,
 									  const char *indexRelname,
 									  bool indexOK,
 									  Snapshot snapshot,
-									  unsigned nkeys, ScanKey key);
+									  int nkeys, ScanKey key);
 extern HeapTuple systable_getnext(SysScanDesc sysscan);
 extern void systable_endscan(SysScanDesc sysscan);
 

src/include/access/hash.h

@@ -7,7 +7,7 @@
  * Portions Copyright (c) 1996-2001, PostgreSQL Global Development Group
  * Portions Copyright (c) 1994, Regents of the University of California
  *
- * $Id: hash.h,v 1.45 2002/03/09 17:35:37 tgl Exp $
+ * $Id: hash.h,v 1.46 2002/05/20 23:51:43 tgl Exp $
  *
  * NOTES
  *		modeled after Margo Seltzer's hash implementation for unix.
@@ -306,8 +306,8 @@ extern void AtEOXact_hash(void);
 /* hashsearch.c */
 extern void _hash_search(Relation rel, int keysz, ScanKey scankey,
 			 Buffer *bufP, HashMetaPage metap);
-extern RetrieveIndexResult _hash_next(IndexScanDesc scan, ScanDirection dir);
-extern RetrieveIndexResult _hash_first(IndexScanDesc scan, ScanDirection dir);
+extern bool _hash_next(IndexScanDesc scan, ScanDirection dir);
+extern bool _hash_first(IndexScanDesc scan, ScanDirection dir);
 extern bool _hash_step(IndexScanDesc scan, Buffer *bufP, ScanDirection dir,
 		   Buffer metabuf);
 

src/include/access/heapam.h

@@ -7,7 +7,7 @@
  * Portions Copyright (c) 1996-2001, PostgreSQL Global Development Group
  * Portions Copyright (c) 1994, Regents of the University of California
  *
- * $Id: heapam.h,v 1.73 2002/03/26 19:16:17 tgl Exp $
+ * $Id: heapam.h,v 1.74 2002/05/20 23:51:43 tgl Exp $
  *
  *-------------------------------------------------------------------------
  */
@@ -16,6 +16,7 @@
 
 #include "access/htup.h"
 #include "access/relscan.h"
+#include "access/sdir.h"
 #include "access/tupmacs.h"
 #include "access/xlogutils.h"
 #include "nodes/primnodes.h"
@@ -145,12 +146,16 @@ extern Relation heap_openr(const char *sysRelationName, LOCKMODE lockmode);
 
 #define heap_close(r,l)  relation_close(r,l)
 
-extern HeapScanDesc heap_beginscan(Relation relation, int atend,
-			   Snapshot snapshot, unsigned nkeys, ScanKey key);
-extern void heap_rescan(HeapScanDesc scan, bool scanFromEnd, ScanKey key);
+extern HeapScanDesc heap_beginscan(Relation relation, Snapshot snapshot,
+								   int nkeys, ScanKey key);
+extern void heap_rescan(HeapScanDesc scan, ScanKey key);
 extern void heap_endscan(HeapScanDesc scan);
-extern HeapTuple heap_getnext(HeapScanDesc scandesc, int backw);
-extern void heap_fetch(Relation relation, Snapshot snapshot, HeapTuple tup, Buffer *userbuf, IndexScanDesc iscan);
+extern HeapTuple heap_getnext(HeapScanDesc scan, ScanDirection direction);
+
+extern void heap_fetch(Relation relation, Snapshot snapshot,
+					   HeapTuple tuple, Buffer *userbuf,
+					   PgStat_Info *pgstat_info);
+
 extern ItemPointer heap_get_latest_tid(Relation relation, Snapshot snapshot, ItemPointer tid);
 extern void setLastTid(const ItemPointer tid);
 extern Oid	heap_insert(Relation relation, HeapTuple tup);

src/include/access/itup.h

@@ -7,7 +7,7 @@
  * Portions Copyright (c) 1996-2001, PostgreSQL Global Development Group
  * Portions Copyright (c) 1994, Regents of the University of California
  *
- * $Id: itup.h,v 1.33 2001/11/05 17:46:31 momjian Exp $
+ * $Id: itup.h,v 1.34 2002/05/20 23:51:43 tgl Exp $
  *
  *-------------------------------------------------------------------------
  */
@@ -54,15 +54,6 @@ typedef struct InsertIndexResultData
 typedef InsertIndexResultData *InsertIndexResult;
 
 
-typedef struct RetrieveIndexResultData
-{
-	ItemPointerData index_iptr;
-	ItemPointerData heap_iptr;
-} RetrieveIndexResultData;
-
-typedef RetrieveIndexResultData *RetrieveIndexResult;
-
-
 /* ----------------
  *		externs
  * ----------------
@@ -147,8 +138,6 @@ extern IndexTuple index_formtuple(TupleDesc tupleDescriptor,
 				Datum *value, char *null);
 extern Datum nocache_index_getattr(IndexTuple tup, int attnum,
 					  TupleDesc tupleDesc, bool *isnull);
-extern RetrieveIndexResult FormRetrieveIndexResult(ItemPointer indexItemPointer,
-						ItemPointer heapItemPointer);
 extern void CopyIndexTuple(IndexTuple source, IndexTuple *target);
 
 #endif   /* ITUP_H */

src/include/access/nbtree.h

@@ -7,7 +7,7 @@
  * Portions Copyright (c) 1996-2001, PostgreSQL Global Development Group
  * Portions Copyright (c) 1994, Regents of the University of California
  *
- * $Id: nbtree.h,v 1.59 2001/11/05 17:46:31 momjian Exp $
+ * $Id: nbtree.h,v 1.60 2002/05/20 23:51:43 tgl Exp $
  *
  *-------------------------------------------------------------------------
  */
@@ -100,8 +100,8 @@ typedef struct BTScanOpaqueData
 	ItemPointerData mrkHeapIptr;
 	/* these fields are set by _bt_orderkeys(), which see for more info: */
 	bool		qual_ok;		/* false if qual can never be satisfied */
-	uint16		numberOfKeys;	/* number of scan keys */
-	uint16		numberOfRequiredKeys;	/* number of keys that must be
+	int			numberOfKeys;	/* number of scan keys */
+	int			numberOfRequiredKeys;	/* number of keys that must be
 										 * matched to continue the scan */
 	ScanKey		keyData;		/* array of scan keys */
 } BTScanOpaqueData;
@@ -366,8 +366,8 @@ extern OffsetNumber _bt_binsrch(Relation rel, Buffer buf, int keysz,
 			ScanKey scankey);
 extern int32 _bt_compare(Relation rel, int keysz, ScanKey scankey,
 			Page page, OffsetNumber offnum);
-extern RetrieveIndexResult _bt_next(IndexScanDesc scan, ScanDirection dir);
-extern RetrieveIndexResult _bt_first(IndexScanDesc scan, ScanDirection dir);
+extern bool _bt_next(IndexScanDesc scan, ScanDirection dir);
+extern bool _bt_first(IndexScanDesc scan, ScanDirection dir);
 extern bool _bt_step(IndexScanDesc scan, Buffer *bufP, ScanDirection dir);
 
 /*

src/include/access/relscan.h

@@ -1,13 +1,13 @@
 /*-------------------------------------------------------------------------
  *
  * relscan.h
- *	  POSTGRES internal relation scan descriptor definitions.
+ *	  POSTGRES relation scan descriptor definitions.
  *
  *
  * Portions Copyright (c) 1996-2001, PostgreSQL Global Development Group
  * Portions Copyright (c) 1994, Regents of the University of California
  *
- * $Id: relscan.h,v 1.25 2001/11/05 17:46:31 momjian Exp $
+ * $Id: relscan.h,v 1.26 2002/05/20 23:51:43 tgl Exp $
  *
  *-------------------------------------------------------------------------
  */
@@ -19,42 +19,54 @@
 
 typedef struct HeapScanDescData
 {
-	Relation	rs_rd;			/* pointer to relation descriptor */
+	/* scan parameters */
+	Relation	rs_rd;			/* heap relation descriptor */
+	Snapshot	rs_snapshot;	/* snapshot to see */
+	int			rs_nkeys;		/* number of scan keys */
+	ScanKey		rs_key;			/* array of scan key descriptors */
+
+	/* scan current state */
 	HeapTupleData rs_ctup;		/* current tuple in scan, if any */
 	Buffer		rs_cbuf;		/* current buffer in scan, if any */
 	/* NB: if rs_cbuf is not InvalidBuffer, we hold a pin on that buffer */
-	ItemPointerData rs_mctid;	/* marked tid, if any */
-	Snapshot	rs_snapshot;	/* snapshot to see */
-	uint16		rs_nkeys;		/* number of scan keys to select tuples */
-	ScanKey		rs_key;			/* key descriptors */
+	ItemPointerData rs_mctid;	/* marked scan position, if any */
 
 	PgStat_Info rs_pgstat_info; /* statistics collector hook */
 } HeapScanDescData;
 
 typedef HeapScanDescData *HeapScanDesc;
 
+
 typedef struct IndexScanDescData
 {
-	Relation	relation;		/* relation descriptor */
+	/* scan parameters */
+	Relation	heapRelation;	/* heap relation descriptor, or NULL */
+	Relation	indexRelation;	/* index relation descriptor */
+	Snapshot	xs_snapshot;	/* snapshot to see */
+	int			numberOfKeys;	/* number of scan keys */
+	ScanKey		keyData;		/* array of scan key descriptors */
+
+	/* scan current state */
 	void	   *opaque;			/* access-method-specific info */
 	ItemPointerData currentItemData;	/* current index pointer */
-	ItemPointerData currentMarkData;	/* marked current pointer */
-	uint8		flags;			/* scan position flags */
-	bool		scanFromEnd;	/* restart scan at end? */
-	uint16		numberOfKeys;	/* number of scan keys to select tuples */
-	ScanKey		keyData;		/* key descriptors */
-	FmgrInfo	fn_getnext;		/* cached lookup info for am's getnext fn */
+	ItemPointerData currentMarkData;	/* marked position, if any */
+	/*
+	 * xs_ctup/xs_cbuf are valid after a successful index_getnext.
+	 * After index_getnext_indexitem, xs_ctup.t_self contains the
+	 * heap tuple TID from the index entry, but its other fields are
+	 * not valid.
+	 */
+	HeapTupleData xs_ctup;		/* current heap tuple, if any */
+	Buffer		xs_cbuf;		/* current heap buffer in scan, if any */
+	/* NB: if xs_cbuf is not InvalidBuffer, we hold a pin on that buffer */
+
+	FmgrInfo	fn_getnext;		/* cached lookup info for AM's getnext fn */
 
 	PgStat_Info xs_pgstat_info; /* statistics collector hook */
 } IndexScanDescData;
 
 typedef IndexScanDescData *IndexScanDesc;
 
-/* IndexScanDesc flag bits (none of these are actually used currently) */
-#define ScanUnmarked			0x01
-#define ScanUncheckedPrevious	0x02
-#define ScanUncheckedNext		0x04
-
 
 /* ----------------
  *		IndexScanDescPtr is used in the executor where we have to

src/include/access/rtree.h

@@ -7,7 +7,7 @@
  * Portions Copyright (c) 1996-2001, PostgreSQL Global Development Group
  * Portions Copyright (c) 1994, Regents of the University of California
  *
- * $Id: rtree.h,v 1.27 2001/11/05 17:46:31 momjian Exp $
+ * $Id: rtree.h,v 1.28 2002/05/20 23:51:43 tgl Exp $
  *
  *-------------------------------------------------------------------------
  */
@@ -71,7 +71,7 @@ typedef struct RTreeScanOpaqueData
 	struct RTSTACK *s_stack;
 	struct RTSTACK *s_markstk;
 	uint16		s_flags;
-	uint16		s_internalNKey;
+	int			s_internalNKey;
 	ScanKey		s_internalKey;
 } RTreeScanOpaqueData;