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-2017, 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). 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 */
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 */
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 */
87 typedef struct SysScanDescData *SysScanDesc;
88 
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 */
118 
119 
120 /*
121  * generalized index_ interface routines (in indexam.c)
122  */
123 
124 /*
125  * IndexScanIsValid
126  * True iff the index scan is valid.
127  */
128 #define IndexScanIsValid(scan) PointerIsValid(scan)
129 
130 extern Relation index_open(Oid relationId, LOCKMODE lockmode);
131 extern void index_close(Relation relation, LOCKMODE lockmode);
132 
133 extern bool index_insert(Relation indexRelation,
134  Datum *values, bool *isnull,
135  ItemPointer heap_t_ctid,
136  Relation heapRelation,
137  IndexUniqueCheck checkUnique,
138  struct IndexInfo *indexInfo);
139 
140 extern IndexScanDesc index_beginscan(Relation heapRelation,
141  Relation indexRelation,
142  Snapshot snapshot,
143  int nkeys, int norderbys);
144 extern IndexScanDesc index_beginscan_bitmap(Relation indexRelation,
145  Snapshot snapshot,
146  int nkeys);
147 extern void index_rescan(IndexScanDesc scan,
148  ScanKey keys, int nkeys,
149  ScanKey orderbys, int norderbys);
150 extern void index_endscan(IndexScanDesc scan);
151 extern void index_markpos(IndexScanDesc scan);
152 extern void index_restrpos(IndexScanDesc scan);
153 extern Size index_parallelscan_estimate(Relation indexrel, Snapshot snapshot);
154 extern void index_parallelscan_initialize(Relation heaprel, Relation indexrel,
155  Snapshot snapshot, ParallelIndexScanDesc target);
156 extern void index_parallelrescan(IndexScanDesc scan);
157 extern IndexScanDesc index_beginscan_parallel(Relation heaprel,
158  Relation indexrel, int nkeys, int norderbys,
159  ParallelIndexScanDesc pscan);
160 extern ItemPointer index_getnext_tid(IndexScanDesc scan,
161  ScanDirection direction);
162 extern HeapTuple index_fetch_heap(IndexScanDesc scan);
163 extern HeapTuple index_getnext(IndexScanDesc scan, ScanDirection direction);
164 extern int64 index_getbitmap(IndexScanDesc scan, TIDBitmap *bitmap);
165 
167  IndexBulkDeleteResult *stats,
169  void *callback_state);
171  IndexBulkDeleteResult *stats);
172 extern bool index_can_return(Relation indexRelation, int attno);
173 extern RegProcedure index_getprocid(Relation irel, AttrNumber attnum,
174  uint16 procnum);
175 extern FmgrInfo *index_getprocinfo(Relation irel, AttrNumber attnum,
176  uint16 procnum);
177 
178 /*
179  * index access method support routines (in genam.c)
180  */
181 extern IndexScanDesc RelationGetIndexScan(Relation indexRelation,
182  int nkeys, int norderbys);
183 extern void IndexScanEnd(IndexScanDesc scan);
184 extern char *BuildIndexValueDescription(Relation indexRelation,
185  Datum *values, bool *isnull);
186 
187 /*
188  * heap-or-index access to system catalogs (in genam.c)
189  */
190 extern SysScanDesc systable_beginscan(Relation heapRelation,
191  Oid indexId,
192  bool indexOK,
193  Snapshot snapshot,
194  int nkeys, ScanKey key);
195 extern HeapTuple systable_getnext(SysScanDesc sysscan);
196 extern bool systable_recheck_tuple(SysScanDesc sysscan, HeapTuple tup);
197 extern void systable_endscan(SysScanDesc sysscan);
198 extern SysScanDesc systable_beginscan_ordered(Relation heapRelation,
199  Relation indexRelation,
200  Snapshot snapshot,
201  int nkeys, ScanKey key);
202 extern HeapTuple systable_getnext_ordered(SysScanDesc sysscan,
203  ScanDirection direction);
204 extern void systable_endscan_ordered(SysScanDesc sysscan);
205 
206 #endif /* GENAM_H */
IndexScanDesc index_beginscan_parallel(Relation heaprel, Relation indexrel, int nkeys, int norderbys, ParallelIndexScanDesc pscan)
Definition: indexam.c:496
struct IndexBuildResult IndexBuildResult
HeapTuple index_getnext(IndexScanDesc scan, ScanDirection direction)
Definition: indexam.c:659
FmgrInfo * index_getprocinfo(Relation irel, AttrNumber attnum, uint16 procnum)
Definition: indexam.c:855
ItemPointer index_getnext_tid(IndexScanDesc scan, ScanDirection direction)
Definition: indexam.c:526
Definition: fmgr.h:56
Relation index_open(Oid relationId, LOCKMODE lockmode)
Definition: indexam.c:151
struct SysScanDescData * SysScanDesc
Definition: genam.h:87
void systable_endscan_ordered(SysScanDesc sysscan)
Definition: genam.c:614
IndexBulkDeleteResult * index_vacuum_cleanup(IndexVacuumInfo *info, IndexBulkDeleteResult *stats)
Definition: indexam.c:764
void index_parallelscan_initialize(Relation heaprel, Relation indexrel, Snapshot snapshot, ParallelIndexScanDesc target)
Definition: indexam.c:450
double tuples_removed
Definition: genam.h:77
void index_close(Relation relation, LOCKMODE lockmode)
Definition: indexam.c:176
int LOCKMODE
Definition: lockdefs.h:26
bool analyze_only
Definition: genam.h:47
regproc RegProcedure
Definition: c.h:453
BufferAccessStrategy strategy
Definition: genam.h:51
Relation index
Definition: genam.h:46
uint32 BlockNumber
Definition: block.h:31
struct ParallelIndexScanDescData * ParallelIndexScanDesc
Definition: genam.h:89
unsigned int Oid
Definition: postgres_ext.h:31
char bool
Definition: c.h:257
HeapTuple systable_getnext(SysScanDesc sysscan)
Definition: genam.c:416
IndexUniqueCheck
Definition: genam.h:111
unsigned short uint16
Definition: c.h:305
BlockNumber num_pages
Definition: genam.h:73
BlockNumber pages_free
Definition: genam.h:79
static void callback(struct sockaddr *addr, struct sockaddr *mask, void *unused)
Definition: test_ifaddrs.c:48
IndexScanDesc index_beginscan(Relation heapRelation, Relation indexRelation, Snapshot snapshot, int nkeys, int norderbys)
Definition: indexam.c:221
IndexBulkDeleteResult * index_bulk_delete(IndexVacuumInfo *info, IndexBulkDeleteResult *stats, IndexBulkDeleteCallback callback, void *callback_state)
Definition: indexam.c:743
IndexScanDesc index_beginscan_bitmap(Relation indexRelation, Snapshot snapshot, int nkeys)
Definition: indexam.c:247
ScanDirection
Definition: sdir.h:22
BlockNumber pages_deleted
Definition: genam.h:78
BlockNumber pages_removed
Definition: genam.h:74
void index_endscan(IndexScanDesc scan)
Definition: indexam.c:340
struct IndexBulkDeleteResult IndexBulkDeleteResult
void index_markpos(IndexScanDesc scan)
Definition: indexam.c:370
void index_rescan(IndexScanDesc scan, ScanKey keys, int nkeys, ScanKey orderbys, int norderbys)
Definition: indexam.c:310
uintptr_t Datum
Definition: postgres.h:372
Size index_parallelscan_estimate(Relation indexrel, Snapshot snapshot)
Definition: indexam.c:417
char * BuildIndexValueDescription(Relation indexRelation, Datum *values, bool *isnull)
Definition: genam.c:177
HeapTuple systable_getnext_ordered(SysScanDesc sysscan, ScanDirection direction)
Definition: genam.c:597
int message_level
Definition: genam.h:49
double num_heap_tuples
Definition: genam.h:50
SysScanDesc systable_beginscan(Relation heapRelation, Oid indexId, bool indexOK, Snapshot snapshot, int nkeys, ScanKey key)
Definition: genam.c:328
struct IndexVacuumInfo IndexVacuumInfo
Definition: regguts.h:298
bool systable_recheck_tuple(SysScanDesc sysscan, HeapTuple tup)
Definition: genam.c:454
IndexScanDesc RelationGetIndexScan(Relation indexRelation, int nkeys, int norderbys)
Definition: genam.c:78
size_t Size
Definition: c.h:414
static Datum values[MAXATTR]
Definition: bootstrap.c:164
void systable_endscan(SysScanDesc sysscan)
Definition: genam.c:499
void index_parallelrescan(IndexScanDesc scan)
Definition: indexam.c:481
bool index_insert(Relation indexRelation, Datum *values, bool *isnull, ItemPointer heap_t_ctid, Relation heapRelation, IndexUniqueCheck checkUnique, struct IndexInfo *indexInfo)
Definition: indexam.c:194
int64 index_getbitmap(IndexScanDesc scan, TIDBitmap *bitmap)
Definition: indexam.c:713
SysScanDesc systable_beginscan_ordered(Relation heapRelation, Relation indexRelation, Snapshot snapshot, int nkeys, ScanKey key)
Definition: genam.c:533
bool index_can_return(Relation indexRelation, int attno)
Definition: indexam.c:783
RegProcedure index_getprocid(Relation irel, AttrNumber attnum, uint16 procnum)
Definition: indexam.c:821
void IndexScanEnd(IndexScanDesc scan)
Definition: genam.c:146
HeapTuple index_fetch_heap(IndexScanDesc scan)
Definition: indexam.c:583
double num_index_tuples
Definition: genam.h:76
struct IndexScanDescData * IndexScanDesc
Definition: genam.h:86
int16 AttrNumber
Definition: attnum.h:21
bool estimated_count
Definition: genam.h:75
void index_restrpos(IndexScanDesc scan)
Definition: indexam.c:395
double index_tuples
Definition: genam.h:33
bool(* IndexBulkDeleteCallback)(ItemPointer itemptr, void *state)
Definition: genam.h:83
double heap_tuples
Definition: genam.h:32
bool estimated_count
Definition: genam.h:48