PostgreSQL Source Code  git master
genam.h
Go to the documentation of this file.
1 /*-------------------------------------------------------------------------
2  *
3  * genam.h
4  * POSTGRES generalized index access method definitions.
5  *
6  *
7  * Portions Copyright (c) 1996-2024, 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 */
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, so it could
42  * even be -1). It will always just be an estimate during ambulkdelete.
43  */
44 typedef struct IndexVacuumInfo
45 {
46  Relation index; /* the index being vacuumed */
47  Relation heaprel; /* the heap relation the index belongs to */
48  bool analyze_only; /* ANALYZE (without any actual vacuum) */
49  bool report_progress; /* emit progress.h status reports */
50  bool estimated_count; /* num_heap_tuples is an estimate */
51  int message_level; /* ereport level for progress messages */
52  double num_heap_tuples; /* tuples remaining in heap */
53  BufferAccessStrategy strategy; /* access strategy for reads */
55 
56 /*
57  * Struct for statistics returned by ambulkdelete and amvacuumcleanup
58  *
59  * This struct is normally allocated by the first ambulkdelete call and then
60  * passed along through subsequent ones until amvacuumcleanup; however,
61  * amvacuumcleanup must be prepared to allocate it in the case where no
62  * ambulkdelete calls were made (because no tuples needed deletion).
63  * Note that an index AM could choose to return a larger struct
64  * of which this is just the first field; this provides a way for ambulkdelete
65  * to communicate additional private data to amvacuumcleanup.
66  *
67  * Note: pages_newly_deleted is the number of pages in the index that were
68  * deleted by the current vacuum operation. pages_deleted and pages_free
69  * refer to free space within the index file.
70  *
71  * Note: Some index AMs may compute num_index_tuples by reference to
72  * num_heap_tuples, in which case they should copy the estimated_count field
73  * from IndexVacuumInfo.
74  */
75 typedef struct IndexBulkDeleteResult
76 {
77  BlockNumber num_pages; /* pages remaining in index */
78  bool estimated_count; /* num_index_tuples is an estimate */
79  double num_index_tuples; /* tuples remaining */
80  double tuples_removed; /* # removed during vacuum operation */
81  BlockNumber pages_newly_deleted; /* # pages marked deleted by us */
82  BlockNumber pages_deleted; /* # pages marked deleted (could be by us) */
83  BlockNumber pages_free; /* # pages available for reuse */
85 
86 /* Typedef for callback function to determine if a tuple is bulk-deletable */
87 typedef bool (*IndexBulkDeleteCallback) (ItemPointer itemptr, void *state);
88 
89 /* struct definitions appear in relscan.h */
91 typedef struct SysScanDescData *SysScanDesc;
92 
94 
95 /*
96  * Enumeration specifying the type of uniqueness check to perform in
97  * index_insert().
98  *
99  * UNIQUE_CHECK_YES is the traditional Postgres immediate check, possibly
100  * blocking to see if a conflicting transaction commits.
101  *
102  * For deferrable unique constraints, UNIQUE_CHECK_PARTIAL is specified at
103  * insertion time. The index AM should test if the tuple is unique, but
104  * should not throw error, block, or prevent the insertion if the tuple
105  * appears not to be unique. We'll recheck later when it is time for the
106  * constraint to be enforced. The AM must return true if the tuple is
107  * known unique, false if it is possibly non-unique. In the "true" case
108  * it is safe to omit the later recheck.
109  *
110  * When it is time to recheck the deferred constraint, a pseudo-insertion
111  * call is made with UNIQUE_CHECK_EXISTING. The tuple is already in the
112  * index in this case, so it should not be inserted again. Rather, just
113  * check for conflicting live tuples (possibly blocking).
114  */
115 typedef enum IndexUniqueCheck
116 {
117  UNIQUE_CHECK_NO, /* Don't do any uniqueness checking */
118  UNIQUE_CHECK_YES, /* Enforce uniqueness at insertion time */
119  UNIQUE_CHECK_PARTIAL, /* Test uniqueness, but no error */
120  UNIQUE_CHECK_EXISTING, /* Check if existing tuple is unique */
122 
123 
124 /* Nullable "ORDER BY col op const" distance */
125 typedef struct IndexOrderByDistance
126 {
127  double value;
128  bool isnull;
130 
131 /*
132  * generalized index_ interface routines (in indexam.c)
133  */
134 
135 /*
136  * IndexScanIsValid
137  * True iff the index scan is valid.
138  */
139 #define IndexScanIsValid(scan) PointerIsValid(scan)
140 
141 extern Relation index_open(Oid relationId, LOCKMODE lockmode);
142 extern Relation try_index_open(Oid relationId, LOCKMODE lockmode);
143 extern void index_close(Relation relation, LOCKMODE lockmode);
144 
145 extern bool index_insert(Relation indexRelation,
146  Datum *values, bool *isnull,
147  ItemPointer heap_t_ctid,
148  Relation heapRelation,
149  IndexUniqueCheck checkUnique,
150  bool indexUnchanged,
151  struct IndexInfo *indexInfo);
152 extern void index_insert_cleanup(Relation indexRelation,
153  struct IndexInfo *indexInfo);
154 
155 extern IndexScanDesc index_beginscan(Relation heapRelation,
156  Relation indexRelation,
157  Snapshot snapshot,
158  int nkeys, int norderbys);
159 extern IndexScanDesc index_beginscan_bitmap(Relation indexRelation,
160  Snapshot snapshot,
161  int nkeys);
162 extern void index_rescan(IndexScanDesc scan,
163  ScanKey keys, int nkeys,
164  ScanKey orderbys, int norderbys);
165 extern void index_endscan(IndexScanDesc scan);
166 extern void index_markpos(IndexScanDesc scan);
167 extern void index_restrpos(IndexScanDesc scan);
168 extern Size index_parallelscan_estimate(Relation indexRelation, Snapshot snapshot);
169 extern void index_parallelscan_initialize(Relation heapRelation,
170  Relation indexRelation, Snapshot snapshot,
171  ParallelIndexScanDesc target);
172 extern void index_parallelrescan(IndexScanDesc scan);
174  Relation indexrel, int nkeys, int norderbys,
175  ParallelIndexScanDesc pscan);
177  ScanDirection direction);
178 struct TupleTableSlot;
179 extern bool index_fetch_heap(IndexScanDesc scan, struct TupleTableSlot *slot);
180 extern bool index_getnext_slot(IndexScanDesc scan, ScanDirection direction,
181  struct TupleTableSlot *slot);
182 extern int64 index_getbitmap(IndexScanDesc scan, TIDBitmap *bitmap);
183 
185  IndexBulkDeleteResult *istat,
187  void *callback_state);
189  IndexBulkDeleteResult *istat);
190 extern bool index_can_return(Relation indexRelation, int attno);
192  uint16 procnum);
194  uint16 procnum);
196  Oid *orderByTypes,
197  IndexOrderByDistance *distances,
198  bool recheckOrderBy);
200  Datum attoptions, bool validate);
201 
202 
203 /*
204  * index access method support routines (in genam.c)
205  */
206 extern IndexScanDesc RelationGetIndexScan(Relation indexRelation,
207  int nkeys, int norderbys);
208 extern void IndexScanEnd(IndexScanDesc scan);
209 extern char *BuildIndexValueDescription(Relation indexRelation,
210  const Datum *values, const bool *isnull);
212  Relation hrel,
213  Buffer ibuf,
214  OffsetNumber *itemnos,
215  int nitems);
216 
217 /*
218  * heap-or-index access to system catalogs (in genam.c)
219  */
220 extern SysScanDesc systable_beginscan(Relation heapRelation,
221  Oid indexId,
222  bool indexOK,
223  Snapshot snapshot,
224  int nkeys, ScanKey key);
225 extern HeapTuple systable_getnext(SysScanDesc sysscan);
226 extern bool systable_recheck_tuple(SysScanDesc sysscan, HeapTuple tup);
227 extern void systable_endscan(SysScanDesc sysscan);
229  Relation indexRelation,
230  Snapshot snapshot,
231  int nkeys, ScanKey key);
233  ScanDirection direction);
234 extern void systable_endscan_ordered(SysScanDesc sysscan);
235 
236 #endif /* GENAM_H */
int16 AttrNumber
Definition: attnum.h:21
uint32 BlockNumber
Definition: block.h:31
static Datum values[MAXATTR]
Definition: bootstrap.c:156
int Buffer
Definition: buf.h:23
unsigned short uint16
Definition: c.h:494
unsigned char bool
Definition: c.h:445
regproc RegProcedure
Definition: c.h:639
uint32 TransactionId
Definition: c.h:641
size_t Size
Definition: c.h:594
void systable_endscan(SysScanDesc sysscan)
Definition: genam.c:599
IndexBulkDeleteResult * index_vacuum_cleanup(IndexVacuumInfo *info, IndexBulkDeleteResult *istat)
Definition: indexam.c:772
Size index_parallelscan_estimate(Relation indexRelation, Snapshot snapshot)
Definition: indexam.c:458
struct IndexOrderByDistance IndexOrderByDistance
bool systable_recheck_tuple(SysScanDesc sysscan, HeapTuple tup)
Definition: genam.c:565
bool index_insert(Relation indexRelation, Datum *values, bool *isnull, ItemPointer heap_t_ctid, Relation heapRelation, IndexUniqueCheck checkUnique, bool indexUnchanged, struct IndexInfo *indexInfo)
Definition: indexam.c:213
bool(* IndexBulkDeleteCallback)(ItemPointer itemptr, void *state)
Definition: genam.h:87
void IndexScanEnd(IndexScanDesc scan)
Definition: genam.c:145
IndexUniqueCheck
Definition: genam.h:116
@ UNIQUE_CHECK_NO
Definition: genam.h:117
@ UNIQUE_CHECK_EXISTING
Definition: genam.h:120
@ UNIQUE_CHECK_PARTIAL
Definition: genam.h:119
@ UNIQUE_CHECK_YES
Definition: genam.h:118
void index_restrpos(IndexScanDesc scan)
Definition: indexam.c:433
IndexScanDesc index_beginscan_parallel(Relation heaprel, Relation indexrel, int nkeys, int norderbys, ParallelIndexScanDesc pscan)
Definition: indexam.c:544
struct IndexVacuumInfo IndexVacuumInfo
IndexScanDesc index_beginscan_bitmap(Relation indexRelation, Snapshot snapshot, int nkeys)
Definition: indexam.c:288
TransactionId index_compute_xid_horizon_for_tuples(Relation irel, Relation hrel, Buffer ibuf, OffsetNumber *itemnos, int nitems)
Definition: genam.c:294
void index_close(Relation relation, LOCKMODE lockmode)
Definition: indexam.c:177
bool index_can_return(Relation indexRelation, int attno)
Definition: indexam.c:791
struct IndexBuildResult IndexBuildResult
ItemPointer index_getnext_tid(IndexScanDesc scan, ScanDirection direction)
Definition: indexam.c:577
SysScanDesc systable_beginscan_ordered(Relation heapRelation, Relation indexRelation, Snapshot snapshot, int nkeys, ScanKey key)
Definition: genam.c:646
HeapTuple systable_getnext(SysScanDesc sysscan)
Definition: genam.c:506
FmgrInfo * index_getprocinfo(Relation irel, AttrNumber attnum, uint16 procnum)
Definition: indexam.c:863
IndexScanDesc index_beginscan(Relation heapRelation, Relation indexRelation, Snapshot snapshot, int nkeys, int norderbys)
Definition: indexam.c:257
RegProcedure index_getprocid(Relation irel, AttrNumber attnum, uint16 procnum)
Definition: indexam.c:829
bool index_getnext_slot(IndexScanDesc scan, ScanDirection direction, struct TupleTableSlot *slot)
Definition: indexam.c:676
void systable_endscan_ordered(SysScanDesc sysscan)
Definition: genam.c:736
HeapTuple systable_getnext_ordered(SysScanDesc sysscan, ScanDirection direction)
Definition: genam.c:711
void index_markpos(IndexScanDesc scan)
Definition: indexam.c:409
Relation try_index_open(Oid relationId, LOCKMODE lockmode)
Definition: indexam.c:152
void index_endscan(IndexScanDesc scan)
Definition: indexam.c:379
struct IndexBulkDeleteResult IndexBulkDeleteResult
IndexBulkDeleteResult * index_bulk_delete(IndexVacuumInfo *info, IndexBulkDeleteResult *istat, IndexBulkDeleteCallback callback, void *callback_state)
Definition: indexam.c:751
void index_parallelscan_initialize(Relation heapRelation, Relation indexRelation, Snapshot snapshot, ParallelIndexScanDesc target)
Definition: indexam.c:493
Relation index_open(Oid relationId, LOCKMODE lockmode)
Definition: indexam.c:133
char * BuildIndexValueDescription(Relation indexRelation, const Datum *values, const bool *isnull)
Definition: genam.c:177
struct SysScanDescData * SysScanDesc
Definition: genam.h:91
bool index_fetch_heap(IndexScanDesc scan, struct TupleTableSlot *slot)
Definition: indexam.c:635
bytea * index_opclass_options(Relation indrel, AttrNumber attnum, Datum attoptions, bool validate)
Definition: indexam.c:999
int64 index_getbitmap(IndexScanDesc scan, TIDBitmap *bitmap)
Definition: indexam.c:721
void index_parallelrescan(IndexScanDesc scan)
Definition: indexam.c:526
void index_rescan(IndexScanDesc scan, ScanKey keys, int nkeys, ScanKey orderbys, int norderbys)
Definition: indexam.c:353
struct ParallelIndexScanDescData * ParallelIndexScanDesc
Definition: genam.h:93
struct IndexScanDescData * IndexScanDesc
Definition: genam.h:90
void index_insert_cleanup(Relation indexRelation, struct IndexInfo *indexInfo)
Definition: indexam.c:241
SysScanDesc systable_beginscan(Relation heapRelation, Oid indexId, bool indexOK, Snapshot snapshot, int nkeys, ScanKey key)
Definition: genam.c:387
IndexScanDesc RelationGetIndexScan(Relation indexRelation, int nkeys, int norderbys)
Definition: genam.c:81
void index_store_float8_orderby_distances(IndexScanDesc scan, Oid *orderByTypes, IndexOrderByDistance *distances, bool recheckOrderBy)
Definition: indexam.c:931
#define nitems(x)
Definition: indent.h:31
int LOCKMODE
Definition: lockdefs.h:26
uint16 OffsetNumber
Definition: off.h:24
int16 attnum
Definition: pg_attribute.h:74
uintptr_t Datum
Definition: postgres.h:64
unsigned int Oid
Definition: postgres_ext.h:31
ScanDirection
Definition: sdir.h:25
Definition: fmgr.h:57
double heap_tuples
Definition: genam.h:32
double index_tuples
Definition: genam.h:33
bool estimated_count
Definition: genam.h:78
BlockNumber pages_deleted
Definition: genam.h:82
BlockNumber pages_newly_deleted
Definition: genam.h:81
BlockNumber pages_free
Definition: genam.h:83
BlockNumber num_pages
Definition: genam.h:77
double tuples_removed
Definition: genam.h:80
double num_index_tuples
Definition: genam.h:79
Relation index
Definition: genam.h:46
double num_heap_tuples
Definition: genam.h:52
bool analyze_only
Definition: genam.h:48
BufferAccessStrategy strategy
Definition: genam.h:53
Relation heaprel
Definition: genam.h:47
bool report_progress
Definition: genam.h:49
int message_level
Definition: genam.h:51
bool estimated_count
Definition: genam.h:50
Definition: regguts.h:323
Definition: c.h:676
static void callback(struct sockaddr *addr, struct sockaddr *mask, void *unused)
Definition: test_ifaddrs.c:46