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-2018, 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  bool phs_snapshot_any; /* SnapshotAny, not phs_snapshot_data? */
43  char phs_snapshot_data[FLEXIBLE_ARRAY_MEMBER];
45 
46 typedef struct HeapScanDescData
47 {
48  /* scan parameters */
49  Relation rs_rd; /* heap relation descriptor */
50  Snapshot rs_snapshot; /* snapshot to see */
51  int rs_nkeys; /* number of scan keys */
52  ScanKey rs_key; /* array of scan key descriptors */
53  bool rs_bitmapscan; /* true if this is really a bitmap scan */
54  bool rs_samplescan; /* true if this is really a sample scan */
55  bool rs_pageatatime; /* verify visibility page-at-a-time? */
56  bool rs_allow_strat; /* allow or disallow use of access strategy */
57  bool rs_allow_sync; /* allow or disallow use of syncscan */
58  bool rs_temp_snap; /* unregister snapshot at scan end? */
59 
60  /* state set up at initscan time */
61  BlockNumber rs_nblocks; /* total number of blocks in rel */
62  BlockNumber rs_startblock; /* block # to start at */
63  BlockNumber rs_numblocks; /* max number of blocks to scan */
64  /* rs_numblocks is usually InvalidBlockNumber, meaning "scan whole rel" */
65  BufferAccessStrategy rs_strategy; /* access strategy for reads */
66  bool rs_syncscan; /* report location to syncscan logic? */
67 
68  /* scan current state */
69  bool rs_inited; /* false = scan not init'd yet */
70  HeapTupleData rs_ctup; /* current tuple in scan, if any */
71  BlockNumber rs_cblock; /* current block # in scan, if any */
72  Buffer rs_cbuf; /* current buffer in scan, if any */
73  /* NB: if rs_cbuf is not InvalidBuffer, we hold a pin on that buffer */
74  ParallelHeapScanDesc rs_parallel; /* parallel scan information */
75 
76  /* these fields only used in page-at-a-time mode and for bitmap scans */
77  int rs_cindex; /* current tuple's index in vistuples */
78  int rs_ntuples; /* number of visible tuples on page */
79  OffsetNumber rs_vistuples[MaxHeapTuplesPerPage]; /* their offsets */
81 
82 /*
83  * We use the same IndexScanDescData structure for both amgettuple-based
84  * and amgetbitmap-based index scans. Some fields are only relevant in
85  * amgettuple-based scans.
86  */
87 typedef struct IndexScanDescData
88 {
89  /* scan parameters */
90  Relation heapRelation; /* heap relation descriptor, or NULL */
91  Relation indexRelation; /* index relation descriptor */
92  Snapshot xs_snapshot; /* snapshot to see */
93  int numberOfKeys; /* number of index qualifier conditions */
94  int numberOfOrderBys; /* number of ordering operators */
95  ScanKey keyData; /* array of index qualifier descriptors */
96  ScanKey orderByData; /* array of ordering op descriptors */
97  bool xs_want_itup; /* caller requests index tuples */
98  bool xs_temp_snap; /* unregister snapshot at scan end? */
99 
100  /* signaling to index AM about killing index tuples */
101  bool kill_prior_tuple; /* last-returned tuple is dead */
102  bool ignore_killed_tuples; /* do not return killed entries */
103  bool xactStartedInRecovery; /* prevents killing/seeing killed
104  * tuples */
105 
106  /* index access method's private state */
107  void *opaque; /* access-method-specific info */
108 
109  /*
110  * In an index-only scan, a successful amgettuple call must fill either
111  * xs_itup (and xs_itupdesc) or xs_hitup (and xs_hitupdesc) to provide the
112  * data returned by the scan. It can fill both, in which case the heap
113  * format will be used.
114  */
115  IndexTuple xs_itup; /* index tuple returned by AM */
116  TupleDesc xs_itupdesc; /* rowtype descriptor of xs_itup */
117  HeapTuple xs_hitup; /* index data returned by AM, as HeapTuple */
118  TupleDesc xs_hitupdesc; /* rowtype descriptor of xs_hitup */
119 
120  /* xs_ctup/xs_cbuf/xs_recheck are valid after a successful index_getnext */
121  HeapTupleData xs_ctup; /* current heap tuple, if any */
122  Buffer xs_cbuf; /* current heap buffer in scan, if any */
123  /* NB: if xs_cbuf is not InvalidBuffer, we hold a pin on that buffer */
124  bool xs_recheck; /* T means scan keys must be rechecked */
125 
126  /*
127  * When fetching with an ordering operator, the values of the ORDER BY
128  * expressions of the last returned tuple, according to the index. If
129  * xs_recheckorderby is true, these need to be rechecked just like the
130  * scan keys, and the values returned here are a lower-bound on the actual
131  * values.
132  */
136 
137  /* state data for traversing HOT chains in index_getnext */
138  bool xs_continue_hot; /* T if must keep walking HOT chain */
139 
140  /* parallel index scan information, in shared memory */
143 
144 /* Generic structure for parallel scans */
146 {
149  Size ps_offset; /* Offset in bytes of am specific structure */
150  char ps_snapshot_data[FLEXIBLE_ARRAY_MEMBER];
152 
153 /* Struct for heap-or-index scans of system tables */
154 typedef struct SysScanDescData
155 {
156  Relation heap_rel; /* catalog being scanned */
157  Relation irel; /* NULL if doing heap scan */
158  HeapScanDesc scan; /* only valid in heap-scan case */
159  IndexScanDesc iscan; /* only valid in index-scan case */
160  Snapshot snapshot; /* snapshot to unregister at end of scan */
162 
163 #endif /* RELSCAN_H */
ParallelIndexScanDesc parallel_scan
Definition: relscan.h:141
int slock_t
Definition: s_lock.h:912
Relation irel
Definition: relscan.h:157
Snapshot snapshot
Definition: relscan.h:160
BlockNumber rs_cblock
Definition: relscan.h:71
char phs_snapshot_data[FLEXIBLE_ARRAY_MEMBER]
Definition: relscan.h:43
Relation heap_rel
Definition: relscan.h:156
IndexTuple xs_itup
Definition: relscan.h:115
struct HeapScanDescData HeapScanDescData
bool rs_allow_sync
Definition: relscan.h:57
struct ParallelHeapScanDescData ParallelHeapScanDescData
#define MaxHeapTuplesPerPage
Definition: htup_details.h:592
Snapshot xs_snapshot
Definition: relscan.h:92
Datum * xs_orderbyvals
Definition: relscan.h:133
bool xs_recheckorderby
Definition: relscan.h:135
uint32 BlockNumber
Definition: block.h:31
TupleDesc xs_itupdesc
Definition: relscan.h:116
unsigned int Oid
Definition: postgres_ext.h:31
IndexScanDesc iscan
Definition: relscan.h:159
TupleDesc xs_hitupdesc
Definition: relscan.h:118
bool ignore_killed_tuples
Definition: relscan.h:102
Relation indexRelation
Definition: relscan.h:91
HeapTupleData rs_ctup
Definition: relscan.h:70
uint16 OffsetNumber
Definition: off.h:24
Relation heapRelation
Definition: relscan.h:90
bool rs_bitmapscan
Definition: relscan.h:53
bool * xs_orderbynulls
Definition: relscan.h:134
pg_atomic_uint64 phs_nallocated
Definition: relscan.h:40
Buffer xs_cbuf
Definition: relscan.h:122
bool rs_pageatatime
Definition: relscan.h:55
BlockNumber rs_numblocks
Definition: relscan.h:63
bool xs_temp_snap
Definition: relscan.h:98
ParallelHeapScanDesc rs_parallel
Definition: relscan.h:74
bool xactStartedInRecovery
Definition: relscan.h:103
bool xs_continue_hot
Definition: relscan.h:138
Snapshot rs_snapshot
Definition: relscan.h:50
bool rs_inited
Definition: relscan.h:69
BlockNumber rs_startblock
Definition: relscan.h:62
struct IndexScanDescData IndexScanDescData
bool rs_temp_snap
Definition: relscan.h:58
ScanKey orderByData
Definition: relscan.h:96
uintptr_t Datum
Definition: postgres.h:365
BlockNumber rs_nblocks
Definition: relscan.h:61
BufferAccessStrategy rs_strategy
Definition: relscan.h:65
BlockNumber phs_startblock
Definition: relscan.h:39
Relation rs_rd
Definition: relscan.h:49
bool xs_want_itup
Definition: relscan.h:97
Buffer rs_cbuf
Definition: relscan.h:72
struct SysScanDescData SysScanDescData
HeapTupleData xs_ctup
Definition: relscan.h:121
size_t Size
Definition: c.h:433
ScanKey keyData
Definition: relscan.h:95
HeapScanDesc scan
Definition: relscan.h:158
BlockNumber phs_nblocks
Definition: relscan.h:37
HeapTuple xs_hitup
Definition: relscan.h:117
bool rs_allow_strat
Definition: relscan.h:56
bool kill_prior_tuple
Definition: relscan.h:101
bool rs_syncscan
Definition: relscan.h:66
int numberOfOrderBys
Definition: relscan.h:94
int Buffer
Definition: buf.h:23
bool rs_samplescan
Definition: relscan.h:54
struct ParallelIndexScanDescData ParallelIndexScanDescData
ScanKey rs_key
Definition: relscan.h:52