src/backend/access/index/genam.c

   1 /*-------------------------------------------------------------------------
   2  *
   3  * genam.c
   4  *        general index access method routines
   5  *
   6  * Portions Copyright (c) 1996-2009, PostgreSQL Global Development Group
   7  * Portions Copyright (c) 1994, Regents of the University of California
   8  *
   9  *
  10  * IDENTIFICATION
  11  *        $PostgreSQL$
  12  *
  13  * NOTES
  14  *        many of the old access method routines have been turned into
  15  *        macros and moved to genam.h -cim 4/30/91
  16  *
  17  *-------------------------------------------------------------------------
  18  */
  19
  20 #include "postgres.h"
  21
  22 #include "access/relscan.h"
  23 #include "access/transam.h"
  24 #include "miscadmin.h"
  25 #include "pgstat.h"
  26 #include "storage/bufmgr.h"
  27 #include "utils/rel.h"
  28 #include "utils/tqual.h"
  29
  30
  31 /* ----------------------------------------------------------------
  32  *              general access method routines
  33  *
  34  *              All indexed access methods use an identical scan structure.
  35  *              We don't know how the various AMs do locking, however, so we don't
  36  *              do anything about that here.
  37  *
  38  *              The intent is that an AM implementor will define a beginscan routine
  39  *              that calls RelationGetIndexScan, to fill in the scan, and then does
  40  *              whatever kind of locking he wants.
  41  *
  42  *              At the end of a scan, the AM's endscan routine undoes the locking,
  43  *              but does *not* call IndexScanEnd --- the higher-level index_endscan
  44  *              routine does that.      (We can't do it in the AM because index_endscan
  45  *              still needs to touch the IndexScanDesc after calling the AM.)
  46  *
  47  *              Because of this, the AM does not have a choice whether to call
  48  *              RelationGetIndexScan or not; its beginscan routine must return an
  49  *              object made by RelationGetIndexScan.  This is kinda ugly but not
  50  *              worth cleaning up now.
  51  * ----------------------------------------------------------------
  52  */
  53
  54 /* ----------------
  55  *      RelationGetIndexScan -- Create and fill an IndexScanDesc.
  56  *
  57  *              This routine creates an index scan structure and sets its contents
  58  *              up correctly. This routine calls AMrescan to set up the scan with
  59  *              the passed key.
  60  *
  61  *              Parameters:
  62  *                              indexRelation -- index relation for scan.
  63  *                              nkeys -- count of scan keys.
  64  *                              key -- array of scan keys to restrict the index scan.
  65  *
  66  *              Returns:
  67  *                              An initialized IndexScanDesc.
  68  * ----------------
  69  */
  70 IndexScanDesc
  71 RelationGetIndexScan(Relation indexRelation,
  72                                          int nkeys, ScanKey key)
  73 {
  74         IndexScanDesc scan;
  75
  76         scan = (IndexScanDesc) palloc(sizeof(IndexScanDescData));
  77
  78         scan->heapRelation = NULL;      /* may be set later */
  79         scan->indexRelation = indexRelation;
  80         scan->xs_snapshot = SnapshotNow;        /* may be set later */
  81         scan->numberOfKeys = nkeys;
  82
  83         /*
  84          * We allocate the key space here, but the AM is responsible for actually
  85          * filling it from the passed key array.
  86          */
  87         if (nkeys > 0)
  88                 scan->keyData = (ScanKey) palloc(sizeof(ScanKeyData) * nkeys);
  89         else
  90                 scan->keyData = NULL;
  91
  92         scan->kill_prior_tuple = false;
  93         scan->ignore_killed_tuples = true;      /* default setting */
  94
  95         scan->opaque = NULL;
  96
  97         ItemPointerSetInvalid(&scan->xs_ctup.t_self);
  98         scan->xs_ctup.t_data = NULL;
  99         scan->xs_cbuf = InvalidBuffer;
 100         scan->xs_hot_dead = false;
 101         scan->xs_next_hot = InvalidOffsetNumber;
 102         scan->xs_prev_xmax = InvalidTransactionId;
 103
 104         /*
 105          * Let the AM fill in the key and any opaque data it wants.
 106          */
 107         index_rescan(scan, key);
 108
 109         return scan;
 110 }
 111
 112 /* ----------------
 113  *      IndexScanEnd -- End an index scan.
 114  *
 115  *              This routine just releases the storage acquired by
 116  *              RelationGetIndexScan().  Any AM-level resources are
 117  *              assumed to already have been released by the AM's
 118  *              endscan routine.
 119  *
 120  *      Returns:
 121  *              None.
 122  * ----------------
 123  */
 124 void
 125 IndexScanEnd(IndexScanDesc scan)
 126 {
 127         if (scan->keyData != NULL)
 128                 pfree(scan->keyData);
 129
 130         pfree(scan);
 131 }
 132
 133
 134 /* ----------------------------------------------------------------
 135  *              heap-or-index-scan access to system catalogs
 136  *
 137  *              These functions support system catalog accesses that normally use
 138  *              an index but need to be capable of being switched to heap scans
 139  *              if the system indexes are unavailable.
 140  *
 141  *              The specified scan keys must be compatible with the named index.
 142  *              Generally this means that they must constrain either all columns
 143  *              of the index, or the first K columns of an N-column index.
 144  *
 145  *              These routines could work with non-system tables, actually,
 146  *              but they're only useful when there is a known index to use with
 147  *              the given scan keys; so in practice they're only good for
 148  *              predetermined types of scans of system catalogs.
 149  * ----------------------------------------------------------------
 150  */
 151
 152 /*
 153  * systable_beginscan --- set up for heap-or-index scan
 154  *
 155  *      rel: catalog to scan, already opened and suitably locked
 156  *      indexId: OID of index to conditionally use
 157  *      indexOK: if false, forces a heap scan (see notes below)
 158  *      snapshot: time qual to use (usually should be SnapshotNow)
 159  *      nkeys, key: scan keys
 160  *
 161  * The attribute numbers in the scan key should be set for the heap case.
 162  * If we choose to index, we reset them to 1..n to reference the index
 163  * columns.  Note this means there must be one scankey qualification per
 164  * index column!  This is checked by the Asserts in the normal, index-using
 165  * case, but won't be checked if the heapscan path is taken.
 166  *
 167  * The routine checks the normal cases for whether an indexscan is safe,
 168  * but caller can make additional checks and pass indexOK=false if needed.
 169  * In standard case indexOK can simply be constant TRUE.
 170  */
 171 SysScanDesc
 172 systable_beginscan(Relation heapRelation,
 173                                    Oid indexId,
 174                                    bool indexOK,
 175                                    Snapshot snapshot,
 176                                    int nkeys, ScanKey key)
 177 {
 178         SysScanDesc sysscan;
 179         Relation        irel;
 180
 181         if (indexOK &&
 182                 !IgnoreSystemIndexes &&
 183                 !ReindexIsProcessingIndex(indexId))
 184                 irel = index_open(indexId, AccessShareLock);
 185         else
 186                 irel = NULL;
 187
 188         sysscan = (SysScanDesc) palloc(sizeof(SysScanDescData));
 189
 190         sysscan->heap_rel = heapRelation;
 191         sysscan->irel = irel;
 192
 193         if (irel)
 194         {
 195                 int                     i;
 196
 197                 /* Change attribute numbers to be index column numbers. */
 198                 for (i = 0; i < nkeys; i++)
 199                 {
 200                         int                     j;
 201
 202                         for (j = 0; j < irel->rd_index->indnatts; j++)
 203                         {
 204                                 if (key[i].sk_attno == irel->rd_index->indkey.values[j])
 205                                 {
 206                                         key[i].sk_attno = j + 1;
 207                                         break;
 208                                 }
 209                         }
 210                         if (j == irel->rd_index->indnatts)
 211                                 elog(ERROR, "column is not in index");
 212                 }
 213
 214                 sysscan->iscan = index_beginscan(heapRelation, irel,
 215                                                                                  snapshot, nkeys, key);
 216                 sysscan->scan = NULL;
 217         }
 218         else
 219         {
 220                 sysscan->scan = heap_beginscan(heapRelation, snapshot, nkeys, key);
 221                 sysscan->iscan = NULL;
 222         }
 223
 224         return sysscan;
 225 }
 226
 227 /*
 228  * systable_getnext --- get next tuple in a heap-or-index scan
 229  *
 230  * Returns NULL if no more tuples available.
 231  *
 232  * Note that returned tuple is a reference to data in a disk buffer;
 233  * it must not be modified, and should be presumed inaccessible after
 234  * next getnext() or endscan() call.
 235  */
 236 HeapTuple
 237 systable_getnext(SysScanDesc sysscan)
 238 {
 239         HeapTuple       htup;
 240
 241         if (sysscan->irel)
 242         {
 243                 htup = index_getnext(sysscan->iscan, ForwardScanDirection);
 244
 245                 /*
 246                  * We currently don't need to support lossy index operators for any
 247                  * system catalog scan.  It could be done here, using the scan keys to
 248                  * drive the operator calls, if we arranged to save the heap attnums
 249                  * during systable_beginscan(); this is practical because we still
 250                  * wouldn't need to support indexes on expressions.
 251                  */
 252                 if (htup && sysscan->iscan->xs_recheck)
 253                         elog(ERROR, "system catalog scans with lossy index conditions are not implemented");
 254         }
 255         else
 256                 htup = heap_getnext(sysscan->scan, ForwardScanDirection);
 257
 258         return htup;
 259 }
 260
 261 /*
 262  * systable_recheck_tuple --- recheck visibility of most-recently-fetched tuple
 263  *
 264  * This is useful to test whether an object was deleted while we waited to
 265  * acquire lock on it.
 266  *
 267  * Note: we don't actually *need* the tuple to be passed in, but it's a
 268  * good crosscheck that the caller is interested in the right tuple.
 269  */
 270 bool
 271 systable_recheck_tuple(SysScanDesc sysscan, HeapTuple tup)
 272 {
 273         bool            result;
 274
 275         if (sysscan->irel)
 276         {
 277                 IndexScanDesc scan = sysscan->iscan;
 278
 279                 Assert(tup == &scan->xs_ctup);
 280                 Assert(BufferIsValid(scan->xs_cbuf));
 281                 /* must hold a buffer lock to call HeapTupleSatisfiesVisibility */
 282                 LockBuffer(scan->xs_cbuf, BUFFER_LOCK_SHARE);
 283                 result = HeapTupleSatisfiesVisibility(tup, scan->xs_snapshot,
 284                                                                                           scan->xs_cbuf);
 285                 LockBuffer(scan->xs_cbuf, BUFFER_LOCK_UNLOCK);
 286         }
 287         else
 288         {
 289                 HeapScanDesc scan = sysscan->scan;
 290
 291                 Assert(tup == &scan->rs_ctup);
 292                 Assert(BufferIsValid(scan->rs_cbuf));
 293                 /* must hold a buffer lock to call HeapTupleSatisfiesVisibility */
 294                 LockBuffer(scan->rs_cbuf, BUFFER_LOCK_SHARE);
 295                 result = HeapTupleSatisfiesVisibility(tup, scan->rs_snapshot,
 296                                                                                           scan->rs_cbuf);
 297                 LockBuffer(scan->rs_cbuf, BUFFER_LOCK_UNLOCK);
 298         }
 299         return result;
 300 }
 301
 302 /*
 303  * systable_endscan --- close scan, release resources
 304  *
 305  * Note that it's still up to the caller to close the heap relation.
 306  */
 307 void
 308 systable_endscan(SysScanDesc sysscan)
 309 {
 310         if (sysscan->irel)
 311         {
 312                 index_endscan(sysscan->iscan);
 313                 index_close(sysscan->irel, AccessShareLock);
 314         }
 315         else
 316                 heap_endscan(sysscan->scan);
 317
 318         pfree(sysscan);
 319 }
 320
 321
 322 /*
 323  * systable_beginscan_ordered --- set up for ordered catalog scan
 324  *
 325  * These routines have essentially the same API as systable_beginscan etc,
 326  * except that they guarantee to return multiple matching tuples in
 327  * index order.  Also, for largely historical reasons, the index to use
 328  * is opened and locked by the caller, not here.
 329  *
 330  * Currently we do not support non-index-based scans here.      (In principle
 331  * we could do a heapscan and sort, but the uses are in places that
 332  * probably don't need to still work with corrupted catalog indexes.)
 333  * For the moment, therefore, these functions are merely the thinnest of
 334  * wrappers around index_beginscan/index_getnext.  The main reason for their
 335  * existence is to centralize possible future support of lossy operators
 336  * in catalog scans.
 337  */
 338 SysScanDesc
 339 systable_beginscan_ordered(Relation heapRelation,
 340                                                    Relation indexRelation,
 341                                                    Snapshot snapshot,
 342                                                    int nkeys, ScanKey key)
 343 {
 344         SysScanDesc sysscan;
 345         int                     i;
 346
 347         /* REINDEX can probably be a hard error here ... */
 348         if (ReindexIsProcessingIndex(RelationGetRelid(indexRelation)))
 349                 elog(ERROR, "cannot do ordered scan on index \"%s\", because it is the current REINDEX target",
 350                          RelationGetRelationName(indexRelation));
 351         /* ... but we only throw a warning about violating IgnoreSystemIndexes */
 352         if (IgnoreSystemIndexes)
 353                 elog(WARNING, "using index \"%s\" despite IgnoreSystemIndexes",
 354                          RelationGetRelationName(indexRelation));
 355
 356         sysscan = (SysScanDesc) palloc(sizeof(SysScanDescData));
 357
 358         sysscan->heap_rel = heapRelation;
 359         sysscan->irel = indexRelation;
 360
 361         /* Change attribute numbers to be index column numbers. */
 362         for (i = 0; i < nkeys; i++)
 363         {
 364                 int                     j;
 365
 366                 for (j = 0; j < indexRelation->rd_index->indnatts; j++)
 367                 {
 368                         if (key[i].sk_attno == indexRelation->rd_index->indkey.values[j])
 369                         {
 370                                 key[i].sk_attno = j + 1;
 371                                 break;
 372                         }
 373                 }
 374                 if (j == indexRelation->rd_index->indnatts)
 375                         elog(ERROR, "column is not in index");
 376         }
 377
 378         sysscan->iscan = index_beginscan(heapRelation, indexRelation,
 379                                                                          snapshot, nkeys, key);
 380         sysscan->scan = NULL;
 381
 382         return sysscan;
 383 }
 384
 385 /*
 386  * systable_getnext_ordered --- get next tuple in an ordered catalog scan
 387  */
 388 HeapTuple
 389 systable_getnext_ordered(SysScanDesc sysscan, ScanDirection direction)
 390 {
 391         HeapTuple       htup;
 392
 393         Assert(sysscan->irel);
 394         htup = index_getnext(sysscan->iscan, direction);
 395         /* See notes in systable_getnext */
 396         if (htup && sysscan->iscan->xs_recheck)
 397                 elog(ERROR, "system catalog scans with lossy index conditions are not implemented");
 398
 399         return htup;
 400 }
 401
 402 /*
 403  * systable_endscan_ordered --- close scan, release resources
 404  */
 405 void
 406 systable_endscan_ordered(SysScanDesc sysscan)
 407 {
 408         Assert(sysscan->irel);
 409         index_endscan(sysscan->iscan);
 410         pfree(sysscan);
 411 }