PostgreSQL Source Code  git master
relscan.h
Go to the documentation of this file.
1 /*-------------------------------------------------------------------------
2  *
3  * relscan.h
4  * POSTGRES relation scan descriptor 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/relscan.h
11  *
12  *-------------------------------------------------------------------------
13  */
14 #ifndef RELSCAN_H
15 #define RELSCAN_H
16 
17 #include "access/genam.h"
18 #include "access/heapam.h"
19 #include "access/htup_details.h"
20 #include "access/itup.h"
21 #include "access/tupdesc.h"
22 #include "storage/spin.h"
23 
24 /*
25  * Shared state for parallel heap scan.
26  *
27  * Each backend participating in a parallel heap scan has its own
28  * HeapScanDesc in backend-private memory, and those objects all contain
29  * a pointer to this structure. The information here must be sufficient
30  * to properly initialize each new HeapScanDesc as workers join the scan,
31  * and it must act as a font of block numbers for those workers.
32  */
34 {
35  Oid phs_relid; /* OID of relation to scan */
36  bool phs_syncscan; /* report location to syncscan logic? */
37  BlockNumber phs_nblocks; /* # blocks in relation at start of scan */
38  slock_t phs_mutex; /* mutual exclusion for setting startblock */
39  BlockNumber phs_startblock; /* starting block number */
40  pg_atomic_uint64 phs_nallocated; /* number of blocks allocated to
41  * workers so far. */
42  char phs_snapshot_data[FLEXIBLE_ARRAY_MEMBER];
44 
45 typedef struct HeapScanDescData
46 {
47  /* scan parameters */
48  Relation rs_rd; /* heap relation descriptor */
49  Snapshot rs_snapshot; /* snapshot to see */
50  int rs_nkeys; /* number of scan keys */
51  ScanKey rs_key; /* array of scan key descriptors */
52  bool rs_bitmapscan; /* true if this is really a bitmap scan */
53  bool rs_samplescan; /* true if this is really a sample scan */
54  bool rs_pageatatime; /* verify visibility page-at-a-time? */
55  bool rs_allow_strat; /* allow or disallow use of access strategy */
56  bool rs_allow_sync; /* allow or disallow use of syncscan */
57  bool rs_temp_snap; /* unregister snapshot at scan end? */
58 
59  /* state set up at initscan time */
60  BlockNumber rs_nblocks; /* total number of blocks in rel */
61  BlockNumber rs_startblock; /* block # to start at */
62  BlockNumber rs_numblocks; /* max number of blocks to scan */
63  /* rs_numblocks is usually InvalidBlockNumber, meaning "scan whole rel" */
64  BufferAccessStrategy rs_strategy; /* access strategy for reads */
65  bool rs_syncscan; /* report location to syncscan logic? */
66 
67  /* scan current state */
68  bool rs_inited; /* false = scan not init'd yet */
69  HeapTupleData rs_ctup; /* current tuple in scan, if any */
70  BlockNumber rs_cblock; /* current block # in scan, if any */
71  Buffer rs_cbuf; /* current buffer in scan, if any */
72  /* NB: if rs_cbuf is not InvalidBuffer, we hold a pin on that buffer */
73  ParallelHeapScanDesc rs_parallel; /* parallel scan information */
74 
75  /* these fields only used in page-at-a-time mode and for bitmap scans */
76  int rs_cindex; /* current tuple's index in vistuples */
77  int rs_ntuples; /* number of visible tuples on page */
78  OffsetNumber rs_vistuples[MaxHeapTuplesPerPage]; /* their offsets */
80 
81 /*
82  * We use the same IndexScanDescData structure for both amgettuple-based
83  * and amgetbitmap-based index scans. Some fields are only relevant in
84  * amgettuple-based scans.
85  */
86 typedef struct IndexScanDescData
87 {
88  /* scan parameters */
89  Relation heapRelation; /* heap relation descriptor, or NULL */
90  Relation indexRelation; /* index relation descriptor */
91  Snapshot xs_snapshot; /* snapshot to see */
92  int numberOfKeys; /* number of index qualifier conditions */
93  int numberOfOrderBys; /* number of ordering operators */
94  ScanKey keyData; /* array of index qualifier descriptors */
95  ScanKey orderByData; /* array of ordering op descriptors */
96  bool xs_want_itup; /* caller requests index tuples */
97  bool xs_temp_snap; /* unregister snapshot at scan end? */
98 
99  /* signaling to index AM about killing index tuples */
100  bool kill_prior_tuple; /* last-returned tuple is dead */
101  bool ignore_killed_tuples; /* do not return killed entries */
102  bool xactStartedInRecovery; /* prevents killing/seeing killed
103  * tuples */
104 
105  /* index access method's private state */
106  void *opaque; /* access-method-specific info */
107 
108  /*
109  * In an index-only scan, a successful amgettuple call must fill either
110  * xs_itup (and xs_itupdesc) or xs_hitup (and xs_hitupdesc) to provide the
111  * data returned by the scan. It can fill both, in which case the heap
112  * format will be used.
113  */
114  IndexTuple xs_itup; /* index tuple returned by AM */
115  TupleDesc xs_itupdesc; /* rowtype descriptor of xs_itup */
116  HeapTuple xs_hitup; /* index data returned by AM, as HeapTuple */
117  TupleDesc xs_hitupdesc; /* rowtype descriptor of xs_hitup */
118 
119  /* xs_ctup/xs_cbuf/xs_recheck are valid after a successful index_getnext */
120  HeapTupleData xs_ctup; /* current heap tuple, if any */
121  Buffer xs_cbuf; /* current heap buffer in scan, if any */
122  /* NB: if xs_cbuf is not InvalidBuffer, we hold a pin on that buffer */
123  bool xs_recheck; /* T means scan keys must be rechecked */
124 
125  /*
126  * When fetching with an ordering operator, the values of the ORDER BY
127  * expressions of the last returned tuple, according to the index. If
128  * xs_recheckorderby is true, these need to be rechecked just like the
129  * scan keys, and the values returned here are a lower-bound on the actual
130  * values.
131  */
135 
136  /* state data for traversing HOT chains in index_getnext */
137  bool xs_continue_hot; /* T if must keep walking HOT chain */
138 
139  /* parallel index scan information, in shared memory */
142 
143 /* Generic structure for parallel scans */
145 {
148  Size ps_offset; /* Offset in bytes of am specific structure */
149  char ps_snapshot_data[FLEXIBLE_ARRAY_MEMBER];
151 
152 /* Struct for heap-or-index scans of system tables */
153 typedef struct SysScanDescData
154 {
155  Relation heap_rel; /* catalog being scanned */
156  Relation irel; /* NULL if doing heap scan */
157  HeapScanDesc scan; /* only valid in heap-scan case */
158  IndexScanDesc iscan; /* only valid in index-scan case */
159  Snapshot snapshot; /* snapshot to unregister at end of scan */
161 
162 #endif /* RELSCAN_H */
ParallelIndexScanDesc parallel_scan
Definition: relscan.h:140
int slock_t
Definition: s_lock.h:888
Relation irel
Definition: relscan.h:156
Snapshot snapshot
Definition: relscan.h:159
BlockNumber rs_cblock
Definition: relscan.h:70
char phs_snapshot_data[FLEXIBLE_ARRAY_MEMBER]
Definition: relscan.h:42
Relation heap_rel
Definition: relscan.h:155
IndexTuple xs_itup
Definition: relscan.h:114
struct HeapScanDescData HeapScanDescData
bool rs_allow_sync
Definition: relscan.h:56
#define MaxHeapTuplesPerPage
Definition: htup_details.h:580
Snapshot xs_snapshot
Definition: relscan.h:91
Datum * xs_orderbyvals
Definition: relscan.h:132
bool xs_recheckorderby
Definition: relscan.h:134
uint32 BlockNumber
Definition: block.h:31
TupleDesc xs_itupdesc
Definition: relscan.h:115
unsigned int Oid
Definition: postgres_ext.h:31
IndexScanDesc iscan
Definition: relscan.h:158
TupleDesc xs_hitupdesc
Definition: relscan.h:117
bool ignore_killed_tuples
Definition: relscan.h:101
Relation indexRelation
Definition: relscan.h:90
HeapTupleData rs_ctup
Definition: relscan.h:69
uint16 OffsetNumber
Definition: off.h:24
Relation heapRelation
Definition: relscan.h:89
bool rs_bitmapscan
Definition: relscan.h:52
bool * xs_orderbynulls
Definition: relscan.h:133
pg_atomic_uint64 phs_nallocated
Definition: relscan.h:40
struct ParallelHeapScanDescData ParallelHeapScanDescData
Buffer xs_cbuf
Definition: relscan.h:121
bool rs_pageatatime
Definition: relscan.h:54
BlockNumber rs_numblocks
Definition: relscan.h:62
bool xs_temp_snap
Definition: relscan.h:97
ParallelHeapScanDesc rs_parallel
Definition: relscan.h:73
bool xactStartedInRecovery
Definition: relscan.h:102
bool xs_continue_hot
Definition: relscan.h:137
Snapshot rs_snapshot
Definition: relscan.h:49
bool rs_inited
Definition: relscan.h:68
BlockNumber rs_startblock
Definition: relscan.h:61
struct IndexScanDescData IndexScanDescData
bool rs_temp_snap
Definition: relscan.h:57
ScanKey orderByData
Definition: relscan.h:95
uintptr_t Datum
Definition: postgres.h:372
BlockNumber rs_nblocks
Definition: relscan.h:60
BufferAccessStrategy rs_strategy
Definition: relscan.h:64
BlockNumber phs_startblock
Definition: relscan.h:39
Relation rs_rd
Definition: relscan.h:48
bool xs_want_itup
Definition: relscan.h:96
Buffer rs_cbuf
Definition: relscan.h:71
struct SysScanDescData SysScanDescData
HeapTupleData xs_ctup
Definition: relscan.h:120
size_t Size
Definition: c.h:404
ScanKey keyData
Definition: relscan.h:94
HeapScanDesc scan
Definition: relscan.h:157
BlockNumber phs_nblocks
Definition: relscan.h:37
HeapTuple xs_hitup
Definition: relscan.h:116
bool rs_allow_strat
Definition: relscan.h:55
bool kill_prior_tuple
Definition: relscan.h:100
bool rs_syncscan
Definition: relscan.h:65
int numberOfOrderBys
Definition: relscan.h:93
int Buffer
Definition: buf.h:23
bool rs_samplescan
Definition: relscan.h:53
struct ParallelIndexScanDescData ParallelIndexScanDescData
ScanKey rs_key
Definition: relscan.h:51