1 /*------------------------------------------------------------------------- 2 * 3 * genam.h 4 * POSTGRES generalized index access method definitions. 5 * 6 * 7 * Portions Copyright (c) 1996-2018, PostgreSQL Global Development Group 8 * Portions Copyright (c) 1994, Regents of the University of California 9 * 10 * src/include/access/genam.h 11 * 12 *------------------------------------------------------------------------- 13 */ 14 #ifndef GENAM_H 15 #define GENAM_H 16 17 #include "access/sdir.h" 18 #include "access/skey.h" 19 #include "nodes/tidbitmap.h" 20 #include "storage/lockdefs.h" 21 #include "utils/relcache.h" 22 #include "utils/snapshot.h" 23 24 /* We don't want this file to depend on execnodes.h. */ 25 struct IndexInfo; 26 27 /* 28 * Struct for statistics returned by ambuild 29 */ 30 typedef struct IndexBuildResult 31 { 32 double heap_tuples; /* # of tuples seen in parent table */ 33 double index_tuples; /* # of tuples inserted into index */ 34 } IndexBuildResult; 35 36 /* 37 * Struct for input arguments passed to ambulkdelete and amvacuumcleanup 38 * 39 * num_heap_tuples is accurate only when estimated_count is false; 40 * otherwise it's just an estimate (currently, the estimate is the 41 * prior value of the relation's pg_class.reltuples field). It will 42 * always just be an estimate during ambulkdelete. 43 */ 44 typedef struct IndexVacuumInfo 45 { 46 Relation index; /* the index being vacuumed */ 47 bool analyze_only; /* ANALYZE (without any actual vacuum) */ 48 bool estimated_count; /* num_heap_tuples is an estimate */ 49 int message_level; /* ereport level for progress messages */ 50 double num_heap_tuples; /* tuples remaining in heap */ 51 BufferAccessStrategy strategy; /* access strategy for reads */ 52 } IndexVacuumInfo; 53 54 /* 55 * Struct for statistics returned by ambulkdelete and amvacuumcleanup 56 * 57 * This struct is normally allocated by the first ambulkdelete call and then 58 * passed along through subsequent ones until amvacuumcleanup; however, 59 * amvacuumcleanup must be prepared to allocate it in the case where no 60 * ambulkdelete calls were made (because no tuples needed deletion). 61 * Note that an index AM could choose to return a larger struct 62 * of which this is just the first field; this provides a way for ambulkdelete 63 * to communicate additional private data to amvacuumcleanup. 64 * 65 * Note: pages_removed is the amount by which the index physically shrank, 66 * if any (ie the change in its total size on disk). pages_deleted and 67 * pages_free refer to free space within the index file. Some index AMs 68 * may compute num_index_tuples by reference to num_heap_tuples, in which 69 * case they should copy the estimated_count field from IndexVacuumInfo. 70 */ 71 typedef struct IndexBulkDeleteResult 72 { 73 BlockNumber num_pages; /* pages remaining in index */ 74 BlockNumber pages_removed; /* # removed during vacuum operation */ 75 bool estimated_count; /* num_index_tuples is an estimate */ 76 double num_index_tuples; /* tuples remaining */ 77 double tuples_removed; /* # removed during vacuum operation */ 78 BlockNumber pages_deleted; /* # unused pages in index */ 79 BlockNumber pages_free; /* # pages available for reuse */ 80 } IndexBulkDeleteResult; 81 82 /* Typedef for callback function to determine if a tuple is bulk-deletable */ 83 typedef bool (*IndexBulkDeleteCallback) (ItemPointer itemptr, void *state); 84 85 /* struct definitions appear in relscan.h */ 86 typedef struct IndexScanDescData *IndexScanDesc; 87 typedef struct SysScanDescData *SysScanDesc; 88 89 typedef struct ParallelIndexScanDescData *ParallelIndexScanDesc; 90 91 /* 92 * Enumeration specifying the type of uniqueness check to perform in 93 * index_insert(). 94 * 95 * UNIQUE_CHECK_YES is the traditional Postgres immediate check, possibly 96 * blocking to see if a conflicting transaction commits. 97 * 98 * For deferrable unique constraints, UNIQUE_CHECK_PARTIAL is specified at 99 * insertion time. The index AM should test if the tuple is unique, but 100 * should not throw error, block, or prevent the insertion if the tuple 101 * appears not to be unique. We'll recheck later when it is time for the 102 * constraint to be enforced. The AM must return true if the tuple is 103 * known unique, false if it is possibly non-unique. In the "true" case 104 * it is safe to omit the later recheck. 105 * 106 * When it is time to recheck the deferred constraint, a pseudo-insertion 107 * call is made with UNIQUE_CHECK_EXISTING. The tuple is already in the 108 * index in this case, so it should not be inserted again. Rather, just 109 * check for conflicting live tuples (possibly blocking). 110 */ 111 typedef enum IndexUniqueCheck 112 { 113 UNIQUE_CHECK_NO, /* Don't do any uniqueness checking */ 114 UNIQUE_CHECK_YES, /* Enforce uniqueness at insertion time */ 115 UNIQUE_CHECK_PARTIAL, /* Test uniqueness, but no error */ 116 UNIQUE_CHECK_EXISTING /* Check if existing tuple is unique */ 117 } IndexUniqueCheck; 118 119 120 /* Nullable "ORDER BY col op const" distance */ 121 typedef struct IndexOrderByDistance 122 { 123 double value; 124 bool isnull; 125 } IndexOrderByDistance; 126 127 /* 128 * generalized index_ interface routines (in indexam.c) 129 */ 130 131 /* 132 * IndexScanIsValid 133 * True iff the index scan is valid. 134 */ 135 #define IndexScanIsValid(scan) PointerIsValid(scan) 136 137 extern Relation index_open(Oid relationId, LOCKMODE lockmode); 138 extern void index_close(Relation relation, LOCKMODE lockmode); 139 140 extern bool index_insert(Relation indexRelation, 141 Datum *values, bool *isnull, 142 ItemPointer heap_t_ctid, 143 Relation heapRelation, 144 IndexUniqueCheck checkUnique, 145 struct IndexInfo *indexInfo); 146 147 extern IndexScanDesc index_beginscan(Relation heapRelation, 148 Relation indexRelation, 149 Snapshot snapshot, 150 int nkeys, int norderbys); 151 extern IndexScanDesc index_beginscan_bitmap(Relation indexRelation, 152 Snapshot snapshot, 153 int nkeys); 154 extern void index_rescan(IndexScanDesc scan, 155 ScanKey keys, int nkeys, 156 ScanKey orderbys, int norderbys); 157 extern void index_endscan(IndexScanDesc scan); 158 extern void index_markpos(IndexScanDesc scan); 159 extern void index_restrpos(IndexScanDesc scan); 160 extern Size index_parallelscan_estimate(Relation indexrel, Snapshot snapshot); 161 extern void index_parallelscan_initialize(Relation heaprel, Relation indexrel, 162 Snapshot snapshot, ParallelIndexScanDesc target); 163 extern void index_parallelrescan(IndexScanDesc scan); 164 extern IndexScanDesc index_beginscan_parallel(Relation heaprel, 165 Relation indexrel, int nkeys, int norderbys, 166 ParallelIndexScanDesc pscan); 167 extern ItemPointer index_getnext_tid(IndexScanDesc scan, 168 ScanDirection direction); 169 extern HeapTuple index_fetch_heap(IndexScanDesc scan); 170 extern HeapTuple index_getnext(IndexScanDesc scan, ScanDirection direction); 171 extern int64 index_getbitmap(IndexScanDesc scan, TIDBitmap *bitmap); 172 173 extern IndexBulkDeleteResult *index_bulk_delete(IndexVacuumInfo *info, 174 IndexBulkDeleteResult *stats, 175 IndexBulkDeleteCallback callback, 176 void *callback_state); 177 extern IndexBulkDeleteResult *index_vacuum_cleanup(IndexVacuumInfo *info, 178 IndexBulkDeleteResult *stats); 179 extern bool index_can_return(Relation indexRelation, int attno); 180 extern RegProcedure index_getprocid(Relation irel, AttrNumber attnum, 181 uint16 procnum); 182 extern FmgrInfo *index_getprocinfo(Relation irel, AttrNumber attnum, 183 uint16 procnum); 184 185 /* 186 * index access method support routines (in genam.c) 187 */ 188 extern IndexScanDesc RelationGetIndexScan(Relation indexRelation, 189 int nkeys, int norderbys); 190 extern void IndexScanEnd(IndexScanDesc scan); 191 extern char *BuildIndexValueDescription(Relation indexRelation, 192 Datum *values, bool *isnull); 193 194 /* 195 * heap-or-index access to system catalogs (in genam.c) 196 */ 197 extern SysScanDesc systable_beginscan(Relation heapRelation, 198 Oid indexId, 199 bool indexOK, 200 Snapshot snapshot, 201 int nkeys, ScanKey key); 202 extern HeapTuple systable_getnext(SysScanDesc sysscan); 203 extern bool systable_recheck_tuple(SysScanDesc sysscan, HeapTuple tup); 204 extern void systable_endscan(SysScanDesc sysscan); 205 extern SysScanDesc systable_beginscan_ordered(Relation heapRelation, 206 Relation indexRelation, 207 Snapshot snapshot, 208 int nkeys, ScanKey key); 209 extern HeapTuple systable_getnext_ordered(SysScanDesc sysscan, 210 ScanDirection direction); 211 extern void systable_endscan_ordered(SysScanDesc sysscan); 212 213 #endif /* GENAM_H */ 214