Header And Logo

PostgreSQL
| The world's most advanced open source database.

rel.h

Go to the documentation of this file.
00001 /*-------------------------------------------------------------------------
00002  *
00003  * rel.h
00004  *    POSTGRES relation descriptor (a/k/a relcache entry) definitions.
00005  *
00006  *
00007  * Portions Copyright (c) 1996-2013, PostgreSQL Global Development Group
00008  * Portions Copyright (c) 1994, Regents of the University of California
00009  *
00010  * src/include/utils/rel.h
00011  *
00012  *-------------------------------------------------------------------------
00013  */
00014 #ifndef REL_H
00015 #define REL_H
00016 
00017 #include "access/tupdesc.h"
00018 #include "catalog/pg_am.h"
00019 #include "catalog/pg_class.h"
00020 #include "catalog/pg_index.h"
00021 #include "fmgr.h"
00022 #include "nodes/bitmapset.h"
00023 #include "rewrite/prs2lock.h"
00024 #include "storage/block.h"
00025 #include "storage/relfilenode.h"
00026 #include "utils/relcache.h"
00027 #include "utils/reltrigger.h"
00028 
00029 
00030 /*
00031  * LockRelId and LockInfo really belong to lmgr.h, but it's more convenient
00032  * to declare them here so we can have a LockInfoData field in a Relation.
00033  */
00034 
00035 typedef struct LockRelId
00036 {
00037     Oid         relId;          /* a relation identifier */
00038     Oid         dbId;           /* a database identifier */
00039 } LockRelId;
00040 
00041 typedef struct LockInfoData
00042 {
00043     LockRelId   lockRelId;
00044 } LockInfoData;
00045 
00046 typedef LockInfoData *LockInfo;
00047 
00048 
00049 /*
00050  * Cached lookup information for the frequently used index access method
00051  * functions, defined by the pg_am row associated with an index relation.
00052  */
00053 typedef struct RelationAmInfo
00054 {
00055     FmgrInfo    aminsert;
00056     FmgrInfo    ambeginscan;
00057     FmgrInfo    amgettuple;
00058     FmgrInfo    amgetbitmap;
00059     FmgrInfo    amrescan;
00060     FmgrInfo    amendscan;
00061     FmgrInfo    ammarkpos;
00062     FmgrInfo    amrestrpos;
00063     FmgrInfo    amcanreturn;
00064 } RelationAmInfo;
00065 
00066 
00067 /*
00068  * Here are the contents of a relation cache entry.
00069  */
00070 
00071 typedef struct RelationData
00072 {
00073     RelFileNode rd_node;        /* relation physical identifier */
00074     /* use "struct" here to avoid needing to include smgr.h: */
00075     struct SMgrRelationData *rd_smgr;   /* cached file handle, or NULL */
00076     int         rd_refcnt;      /* reference count */
00077     BackendId   rd_backend;     /* owning backend id, if temporary relation */
00078     bool        rd_islocaltemp; /* rel is a temp rel of this session */
00079     bool        rd_isnailed;    /* rel is nailed in cache */
00080     bool        rd_ispopulated; /* matview has query results */
00081     bool        rd_isvalid;     /* relcache entry is valid */
00082     char        rd_indexvalid;  /* state of rd_indexlist: 0 = not valid, 1 =
00083                                  * valid, 2 = temporarily forced */
00084 
00085     /*
00086      * rd_createSubid is the ID of the highest subtransaction the rel has
00087      * survived into; or zero if the rel was not created in the current top
00088      * transaction.  This can be now be relied on, whereas previously it
00089      * could be "forgotten" in earlier releases.
00090      * Likewise, rd_newRelfilenodeSubid is the ID of the highest
00091      * subtransaction the relfilenode change has survived into, or zero if not
00092      * changed in the current transaction (or we have forgotten changing it).
00093      * rd_newRelfilenodeSubid can be forgotten when a relation has multiple
00094      * new relfilenodes within a single transaction, with one of them occuring
00095      * in a subsequently aborted subtransaction, e.g.
00096      *      BEGIN;
00097      *      TRUNCATE t;
00098      *      SAVEPOINT save;
00099      *      TRUNCATE t;
00100      *      ROLLBACK TO save;
00101      *      -- rd_newRelfilenode is now forgotten
00102      */
00103     SubTransactionId rd_createSubid;    /* rel was created in current xact */
00104     SubTransactionId rd_newRelfilenodeSubid;    /* new relfilenode assigned in
00105                                                  * current xact */
00106 
00107     Form_pg_class rd_rel;       /* RELATION tuple */
00108     TupleDesc   rd_att;         /* tuple descriptor */
00109     Oid         rd_id;          /* relation's object id */
00110     List       *rd_indexlist;   /* list of OIDs of indexes on relation */
00111     Bitmapset  *rd_indexattr;   /* identifies columns used in indexes */
00112     Bitmapset  *rd_keyattr;     /* cols that can be ref'd by foreign keys */
00113     Oid         rd_oidindex;    /* OID of unique index on OID, if any */
00114     LockInfoData rd_lockInfo;   /* lock mgr's info for locking relation */
00115     RuleLock   *rd_rules;       /* rewrite rules */
00116     MemoryContext rd_rulescxt;  /* private memory cxt for rd_rules, if any */
00117     TriggerDesc *trigdesc;      /* Trigger info, or NULL if rel has none */
00118 
00119     /*
00120      * rd_options is set whenever rd_rel is loaded into the relcache entry.
00121      * Note that you can NOT look into rd_rel for this data.  NULL means "use
00122      * defaults".
00123      */
00124     bytea      *rd_options;     /* parsed pg_class.reloptions */
00125 
00126     /* These are non-NULL only for an index relation: */
00127     Form_pg_index rd_index;     /* pg_index tuple describing this index */
00128     /* use "struct" here to avoid needing to include htup.h: */
00129     struct HeapTupleData *rd_indextuple;        /* all of pg_index tuple */
00130     Form_pg_am  rd_am;          /* pg_am tuple for index's AM */
00131 
00132     /*
00133      * index access support info (used only for an index relation)
00134      *
00135      * Note: only default support procs for each opclass are cached, namely
00136      * those with lefttype and righttype equal to the opclass's opcintype. The
00137      * arrays are indexed by support function number, which is a sufficient
00138      * identifier given that restriction.
00139      *
00140      * Note: rd_amcache is available for index AMs to cache private data about
00141      * an index.  This must be just a cache since it may get reset at any time
00142      * (in particular, it will get reset by a relcache inval message for the
00143      * index).  If used, it must point to a single memory chunk palloc'd in
00144      * rd_indexcxt.  A relcache reset will include freeing that chunk and
00145      * setting rd_amcache = NULL.
00146      */
00147     MemoryContext rd_indexcxt;  /* private memory cxt for this stuff */
00148     RelationAmInfo *rd_aminfo;  /* lookup info for funcs found in pg_am */
00149     Oid        *rd_opfamily;    /* OIDs of op families for each index col */
00150     Oid        *rd_opcintype;   /* OIDs of opclass declared input data types */
00151     RegProcedure *rd_support;   /* OIDs of support procedures */
00152     FmgrInfo   *rd_supportinfo; /* lookup info for support procedures */
00153     int16      *rd_indoption;   /* per-column AM-specific flags */
00154     List       *rd_indexprs;    /* index expression trees, if any */
00155     List       *rd_indpred;     /* index predicate tree, if any */
00156     Oid        *rd_exclops;     /* OIDs of exclusion operators, if any */
00157     Oid        *rd_exclprocs;   /* OIDs of exclusion ops' procs, if any */
00158     uint16     *rd_exclstrats;  /* exclusion ops' strategy numbers, if any */
00159     void       *rd_amcache;     /* available for use by index AM */
00160     Oid        *rd_indcollation;    /* OIDs of index collations */
00161 
00162     /*
00163      * foreign-table support
00164      *
00165      * rd_fdwroutine must point to a single memory chunk palloc'd in
00166      * CacheMemoryContext.  It will be freed and reset to NULL on a relcache
00167      * reset.
00168      */
00169 
00170     /* use "struct" here to avoid needing to include fdwapi.h: */
00171     struct FdwRoutine *rd_fdwroutine;   /* cached function pointers, or NULL */
00172 
00173     /*
00174      * Hack for CLUSTER, rewriting ALTER TABLE, etc: when writing a new
00175      * version of a table, we need to make any toast pointers inserted into it
00176      * have the existing toast table's OID, not the OID of the transient toast
00177      * table.  If rd_toastoid isn't InvalidOid, it is the OID to place in
00178      * toast pointers inserted into this rel.  (Note it's set on the new
00179      * version of the main heap, not the toast table itself.)  This also
00180      * causes toast_save_datum() to try to preserve toast value OIDs.
00181      */
00182     Oid         rd_toastoid;    /* Real TOAST table's OID, or InvalidOid */
00183 
00184     /* use "struct" here to avoid needing to include pgstat.h: */
00185     struct PgStat_TableStatus *pgstat_info;     /* statistics collection area */
00186 } RelationData;
00187 
00188 /*
00189  * StdRdOptions
00190  *      Standard contents of rd_options for heaps and generic indexes.
00191  *
00192  * RelationGetFillFactor() and RelationGetTargetPageFreeSpace() can only
00193  * be applied to relations that use this format or a superset for
00194  * private options data.
00195  */
00196  /* autovacuum-related reloptions. */
00197 typedef struct AutoVacOpts
00198 {
00199     bool        enabled;
00200     int         vacuum_threshold;
00201     int         analyze_threshold;
00202     int         vacuum_cost_delay;
00203     int         vacuum_cost_limit;
00204     int         freeze_min_age;
00205     int         freeze_max_age;
00206     int         freeze_table_age;
00207     float8      vacuum_scale_factor;
00208     float8      analyze_scale_factor;
00209 } AutoVacOpts;
00210 
00211 typedef struct StdRdOptions
00212 {
00213     int32       vl_len_;        /* varlena header (do not touch directly!) */
00214     int         fillfactor;     /* page fill factor in percent (0..100) */
00215     AutoVacOpts autovacuum;     /* autovacuum-related options */
00216     bool        security_barrier;       /* for views */
00217 } StdRdOptions;
00218 
00219 #define HEAP_MIN_FILLFACTOR         10
00220 #define HEAP_DEFAULT_FILLFACTOR     100
00221 
00222 /*
00223  * RelationGetFillFactor
00224  *      Returns the relation's fillfactor.  Note multiple eval of argument!
00225  */
00226 #define RelationGetFillFactor(relation, defaultff) \
00227     ((relation)->rd_options ? \
00228      ((StdRdOptions *) (relation)->rd_options)->fillfactor : (defaultff))
00229 
00230 /*
00231  * RelationGetTargetPageUsage
00232  *      Returns the relation's desired space usage per page in bytes.
00233  */
00234 #define RelationGetTargetPageUsage(relation, defaultff) \
00235     (BLCKSZ * RelationGetFillFactor(relation, defaultff) / 100)
00236 
00237 /*
00238  * RelationGetTargetPageFreeSpace
00239  *      Returns the relation's desired freespace per page in bytes.
00240  */
00241 #define RelationGetTargetPageFreeSpace(relation, defaultff) \
00242     (BLCKSZ * (100 - RelationGetFillFactor(relation, defaultff)) / 100)
00243 
00244 /*
00245  * RelationIsSecurityView
00246  *      Returns whether the relation is security view, or not
00247  */
00248 #define RelationIsSecurityView(relation)    \
00249     ((relation)->rd_options ?               \
00250      ((StdRdOptions *) (relation)->rd_options)->security_barrier : false)
00251 
00252 /*
00253  * RelationIsValid
00254  *      True iff relation descriptor is valid.
00255  */
00256 #define RelationIsValid(relation) PointerIsValid(relation)
00257 
00258 #define InvalidRelation ((Relation) NULL)
00259 
00260 /*
00261  * RelationHasReferenceCountZero
00262  *      True iff relation reference count is zero.
00263  *
00264  * Note:
00265  *      Assumes relation descriptor is valid.
00266  */
00267 #define RelationHasReferenceCountZero(relation) \
00268         ((bool)((relation)->rd_refcnt == 0))
00269 
00270 /*
00271  * RelationGetForm
00272  *      Returns pg_class tuple for a relation.
00273  *
00274  * Note:
00275  *      Assumes relation descriptor is valid.
00276  */
00277 #define RelationGetForm(relation) ((relation)->rd_rel)
00278 
00279 /*
00280  * RelationGetRelid
00281  *      Returns the OID of the relation
00282  */
00283 #define RelationGetRelid(relation) ((relation)->rd_id)
00284 
00285 /*
00286  * RelationGetNumberOfAttributes
00287  *      Returns the number of attributes in a relation.
00288  */
00289 #define RelationGetNumberOfAttributes(relation) ((relation)->rd_rel->relnatts)
00290 
00291 /*
00292  * RelationGetDescr
00293  *      Returns tuple descriptor for a relation.
00294  */
00295 #define RelationGetDescr(relation) ((relation)->rd_att)
00296 
00297 /*
00298  * RelationGetRelationName
00299  *      Returns the rel's name.
00300  *
00301  * Note that the name is only unique within the containing namespace.
00302  */
00303 #define RelationGetRelationName(relation) \
00304     (NameStr((relation)->rd_rel->relname))
00305 
00306 /*
00307  * RelationGetNamespace
00308  *      Returns the rel's namespace OID.
00309  */
00310 #define RelationGetNamespace(relation) \
00311     ((relation)->rd_rel->relnamespace)
00312 
00313 /*
00314  * RelationIsMapped
00315  *      True if the relation uses the relfilenode map.
00316  *
00317  * NB: this is only meaningful for relkinds that have storage, else it
00318  * will misleadingly say "true".
00319  */
00320 #define RelationIsMapped(relation) \
00321     ((relation)->rd_rel->relfilenode == InvalidOid)
00322 
00323 /*
00324  * RelationOpenSmgr
00325  *      Open the relation at the smgr level, if not already done.
00326  */
00327 #define RelationOpenSmgr(relation) \
00328     do { \
00329         if ((relation)->rd_smgr == NULL) \
00330             smgrsetowner(&((relation)->rd_smgr), smgropen((relation)->rd_node, (relation)->rd_backend)); \
00331     } while (0)
00332 
00333 /*
00334  * RelationCloseSmgr
00335  *      Close the relation at the smgr level, if not already done.
00336  *
00337  * Note: smgrclose should unhook from owner pointer, hence the Assert.
00338  */
00339 #define RelationCloseSmgr(relation) \
00340     do { \
00341         if ((relation)->rd_smgr != NULL) \
00342         { \
00343             smgrclose((relation)->rd_smgr); \
00344             Assert((relation)->rd_smgr == NULL); \
00345         } \
00346     } while (0)
00347 
00348 /*
00349  * RelationGetTargetBlock
00350  *      Fetch relation's current insertion target block.
00351  *
00352  * Returns InvalidBlockNumber if there is no current target block.  Note
00353  * that the target block status is discarded on any smgr-level invalidation.
00354  */
00355 #define RelationGetTargetBlock(relation) \
00356     ( (relation)->rd_smgr != NULL ? (relation)->rd_smgr->smgr_targblock : InvalidBlockNumber )
00357 
00358 /*
00359  * RelationSetTargetBlock
00360  *      Set relation's current insertion target block.
00361  */
00362 #define RelationSetTargetBlock(relation, targblock) \
00363     do { \
00364         RelationOpenSmgr(relation); \
00365         (relation)->rd_smgr->smgr_targblock = (targblock); \
00366     } while (0)
00367 
00368 /*
00369  * RelationNeedsWAL
00370  *      True if relation needs WAL.
00371  */
00372 #define RelationNeedsWAL(relation) \
00373     ((relation)->rd_rel->relpersistence == RELPERSISTENCE_PERMANENT)
00374 
00375 /*
00376  * RelationUsesLocalBuffers
00377  *      True if relation's pages are stored in local buffers.
00378  */
00379 #define RelationUsesLocalBuffers(relation) \
00380     ((relation)->rd_rel->relpersistence == RELPERSISTENCE_TEMP)
00381 
00382 /*
00383  * RELATION_IS_LOCAL
00384  *      If a rel is either temp or newly created in the current transaction,
00385  *      it can be assumed to be accessible only to the current backend.
00386  *      This is typically used to decide that we can skip acquiring locks.
00387  *
00388  * Beware of multiple eval of argument
00389  */
00390 #define RELATION_IS_LOCAL(relation) \
00391     ((relation)->rd_islocaltemp || \
00392      (relation)->rd_createSubid != InvalidSubTransactionId)
00393 
00394 /*
00395  * RELATION_IS_OTHER_TEMP
00396  *      Test for a temporary relation that belongs to some other session.
00397  *
00398  * Beware of multiple eval of argument
00399  */
00400 #define RELATION_IS_OTHER_TEMP(relation) \
00401     ((relation)->rd_rel->relpersistence == RELPERSISTENCE_TEMP && \
00402      !(relation)->rd_islocaltemp)
00403 
00404 
00405 /*
00406  * RelationIsScannable
00407  *      Currently can only be false for a materialized view which has not been
00408  *      populated by its query.  This is likely to get more complicated later,
00409  *      so use a macro which looks like a function.
00410  */
00411 #define RelationIsScannable(relation) ((relation)->rd_ispopulated)
00412 
00413 
00414 /* routines in utils/cache/relcache.c */
00415 extern void RelationIncrementReferenceCount(Relation rel);
00416 extern void RelationDecrementReferenceCount(Relation rel);
00417 
00418 #endif   /* REL_H */