src/include/access/relscan.h

   1 /*-------------------------------------------------------------------------
   2  *
   3  * relscan.h
   4  *        POSTGRES relation scan descriptor 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/relscan.h
  11  *
  12  *-------------------------------------------------------------------------
  13  */
  14 #ifndef RELSCAN_H
  15 #define RELSCAN_H
  16
  17 #include "access/htup_details.h"
  18 #include "access/itup.h"
  19 #include "port/atomics.h"
  20 #include "storage/buf.h"
  21 #include "storage/relfilelocator.h"
  22 #include "storage/spin.h"
  23 #include "utils/relcache.h"
  24
  25
  26 struct ParallelTableScanDescData;
  27
  28 struct TBMIterator;
  29 struct TBMSharedIterator;
  30
  31 /*
  32  * Generic descriptor for table scans. This is the base-class for table scans,
  33  * which needs to be embedded in the scans of individual AMs.
  34  */
  35 typedef struct TableScanDescData
  36 {
  37         /* scan parameters */
  38         Relation        rs_rd;                  /* heap relation descriptor */
  39         struct SnapshotData *rs_snapshot;       /* snapshot to see */
  40         int                     rs_nkeys;               /* number of scan keys */
  41         struct ScanKeyData *rs_key; /* array of scan key descriptors */
  42
  43         /*
  44          * Scan type-specific members
  45          */
  46         union
  47         {
  48                 /* Iterators for Bitmap Table Scans */
  49                 struct
  50                 {
  51                         struct TBMIterator *rs_iterator;
  52                         struct TBMSharedIterator *rs_shared_iterator;
  53                 }                       bitmap;
  54
  55                 /*
  56                  * Range of ItemPointers for table_scan_getnextslot_tidrange() to
  57                  * scan.
  58                  */
  59                 struct
  60                 {
  61                         ItemPointerData rs_mintid;
  62                         ItemPointerData rs_maxtid;
  63                 }                       tidrange;
  64         }                       st;
  65
  66         /*
  67          * Information about type and behaviour of the scan, a bitmask of members
  68          * of the ScanOptions enum (see tableam.h).
  69          */
  70         uint32          rs_flags;
  71
  72         struct ParallelTableScanDescData *rs_parallel;  /* parallel scan
  73                                                                                                          * information */
  74 } TableScanDescData;
  75 typedef struct TableScanDescData *TableScanDesc;
  76
  77 /*
  78  * Shared state for parallel table scan.
  79  *
  80  * Each backend participating in a parallel table scan has its own
  81  * TableScanDesc in backend-private memory, and those objects all contain a
  82  * pointer to this structure.  The information here must be sufficient to
  83  * properly initialize each new TableScanDesc as workers join the scan, and it
  84  * must act as a information what to scan for those workers.
  85  */
  86 typedef struct ParallelTableScanDescData
  87 {
  88         RelFileLocator phs_locator; /* physical relation to scan */
  89         bool            phs_syncscan;   /* report location to syncscan logic? */
  90         bool            phs_snapshot_any;       /* SnapshotAny, not phs_snapshot_data? */
  91         Size            phs_snapshot_off;       /* data for snapshot */
  92 } ParallelTableScanDescData;
  93 typedef struct ParallelTableScanDescData *ParallelTableScanDesc;
  94
  95 /*
  96  * Shared state for parallel table scans, for block oriented storage.
  97  */
  98 typedef struct ParallelBlockTableScanDescData
  99 {
 100         ParallelTableScanDescData base;
 101
 102         BlockNumber phs_nblocks;        /* # blocks in relation at start of scan */
 103         slock_t         phs_mutex;              /* mutual exclusion for setting startblock */
 104         BlockNumber phs_startblock; /* starting block number */
 105         pg_atomic_uint64 phs_nallocated;        /* number of blocks allocated to
 106                                                                                  * workers so far. */
 107 }                       ParallelBlockTableScanDescData;
 108 typedef struct ParallelBlockTableScanDescData *ParallelBlockTableScanDesc;
 109
 110 /*
 111  * Per backend state for parallel table scan, for block-oriented storage.
 112  */
 113 typedef struct ParallelBlockTableScanWorkerData
 114 {
 115         uint64          phsw_nallocated;        /* Current # of blocks into the scan */
 116         uint32          phsw_chunk_remaining;   /* # blocks left in this chunk */
 117         uint32          phsw_chunk_size;        /* The number of blocks to allocate in
 118                                                                          * each I/O chunk for the scan */
 119 } ParallelBlockTableScanWorkerData;
 120 typedef struct ParallelBlockTableScanWorkerData *ParallelBlockTableScanWorker;
 121
 122 /*
 123  * Base class for fetches from a table via an index. This is the base-class
 124  * for such scans, which needs to be embedded in the respective struct for
 125  * individual AMs.
 126  */
 127 typedef struct IndexFetchTableData
 128 {
 129         Relation        rel;
 130 } IndexFetchTableData;
 131
 132 /*
 133  * We use the same IndexScanDescData structure for both amgettuple-based
 134  * and amgetbitmap-based index scans.  Some fields are only relevant in
 135  * amgettuple-based scans.
 136  */
 137 typedef struct IndexScanDescData
 138 {
 139         /* scan parameters */
 140         Relation        heapRelation;   /* heap relation descriptor, or NULL */
 141         Relation        indexRelation;  /* index relation descriptor */
 142         struct SnapshotData *xs_snapshot;       /* snapshot to see */
 143         int                     numberOfKeys;   /* number of index qualifier conditions */
 144         int                     numberOfOrderBys;       /* number of ordering operators */
 145         struct ScanKeyData *keyData;    /* array of index qualifier descriptors */
 146         struct ScanKeyData *orderByData;        /* array of ordering op descriptors */
 147         bool            xs_want_itup;   /* caller requests index tuples */
 148         bool            xs_temp_snap;   /* unregister snapshot at scan end? */
 149
 150         /* signaling to index AM about killing index tuples */
 151         bool            kill_prior_tuple;       /* last-returned tuple is dead */
 152         bool            ignore_killed_tuples;   /* do not return killed entries */
 153         bool            xactStartedInRecovery;  /* prevents killing/seeing killed
 154                                                                                  * tuples */
 155
 156         /* index access method's private state */
 157         void       *opaque;                     /* access-method-specific info */
 158
 159         /*
 160          * In an index-only scan, a successful amgettuple call must fill either
 161          * xs_itup (and xs_itupdesc) or xs_hitup (and xs_hitupdesc) to provide the
 162          * data returned by the scan.  It can fill both, in which case the heap
 163          * format will be used.
 164          */
 165         IndexTuple      xs_itup;                /* index tuple returned by AM */
 166         struct TupleDescData *xs_itupdesc;      /* rowtype descriptor of xs_itup */
 167         HeapTuple       xs_hitup;               /* index data returned by AM, as HeapTuple */
 168         struct TupleDescData *xs_hitupdesc; /* rowtype descriptor of xs_hitup */
 169
 170         ItemPointerData xs_heaptid; /* result */
 171         bool            xs_heap_continue;       /* T if must keep walking, potential
 172                                                                          * further results */
 173         IndexFetchTableData *xs_heapfetch;
 174
 175         bool            xs_recheck;             /* T means scan keys must be rechecked */
 176
 177         /*
 178          * When fetching with an ordering operator, the values of the ORDER BY
 179          * expressions of the last returned tuple, according to the index.  If
 180          * xs_recheckorderby is true, these need to be rechecked just like the
 181          * scan keys, and the values returned here are a lower-bound on the actual
 182          * values.
 183          */
 184         Datum      *xs_orderbyvals;
 185         bool       *xs_orderbynulls;
 186         bool            xs_recheckorderby;
 187
 188         /* parallel index scan information, in shared memory */
 189         struct ParallelIndexScanDescData *parallel_scan;
 190 }                       IndexScanDescData;
 191
 192 /* Generic structure for parallel scans */
 193 typedef struct ParallelIndexScanDescData
 194 {
 195         RelFileLocator ps_locator;      /* physical table relation to scan */
 196         RelFileLocator ps_indexlocator; /* physical index relation to scan */
 197         Size            ps_offset;              /* Offset in bytes of am specific structure */
 198         char            ps_snapshot_data[FLEXIBLE_ARRAY_MEMBER];
 199 }                       ParallelIndexScanDescData;
 200
 201 struct TupleTableSlot;
 202
 203 /* Struct for storage-or-index scans of system tables */
 204 typedef struct SysScanDescData
 205 {
 206         Relation        heap_rel;               /* catalog being scanned */
 207         Relation        irel;                   /* NULL if doing heap scan */
 208         struct TableScanDescData *scan; /* only valid in storage-scan case */
 209         struct IndexScanDescData *iscan;        /* only valid in index-scan case */
 210         struct SnapshotData *snapshot;  /* snapshot to unregister at end of scan */
 211         struct TupleTableSlot *slot;
 212 }                       SysScanDescData;
 213
 214 #endif                                                  /* RELSCAN_H */