LCOV - code coverage report
Current view: top level - src/include/access - tupdesc.h (source / functions) Hit Total Coverage
Test: PostgreSQL 18devel Lines: 6 6 100.0 %
Date: 2025-04-01 15:15:16 Functions: 2 2 100.0 %
Legend: Lines: hit not hit

          Line data    Source code
       1             : /*-------------------------------------------------------------------------
       2             :  *
       3             :  * tupdesc.h
       4             :  *    POSTGRES tuple descriptor definitions.
       5             :  *
       6             :  *
       7             :  * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
       8             :  * Portions Copyright (c) 1994, Regents of the University of California
       9             :  *
      10             :  * src/include/access/tupdesc.h
      11             :  *
      12             :  *-------------------------------------------------------------------------
      13             :  */
      14             : #ifndef TUPDESC_H
      15             : #define TUPDESC_H
      16             : 
      17             : #include "access/attnum.h"
      18             : #include "catalog/pg_attribute.h"
      19             : #include "nodes/pg_list.h"
      20             : 
      21             : 
      22             : typedef struct AttrDefault
      23             : {
      24             :     AttrNumber  adnum;
      25             :     char       *adbin;          /* nodeToString representation of expr */
      26             : } AttrDefault;
      27             : 
      28             : typedef struct ConstrCheck
      29             : {
      30             :     char       *ccname;
      31             :     char       *ccbin;          /* nodeToString representation of expr */
      32             :     bool        ccenforced;
      33             :     bool        ccvalid;
      34             :     bool        ccnoinherit;    /* this is a non-inheritable constraint */
      35             : } ConstrCheck;
      36             : 
      37             : /* This structure contains constraints of a tuple */
      38             : typedef struct TupleConstr
      39             : {
      40             :     AttrDefault *defval;        /* array */
      41             :     ConstrCheck *check;         /* array */
      42             :     struct AttrMissing *missing;    /* missing attributes values, NULL if none */
      43             :     uint16      num_defval;
      44             :     uint16      num_check;
      45             :     bool        has_not_null;
      46             :     bool        has_generated_stored;
      47             :     bool        has_generated_virtual;
      48             : } TupleConstr;
      49             : 
      50             : /*
      51             :  * CompactAttribute
      52             :  *      Cut-down version of FormData_pg_attribute for faster access for tasks
      53             :  *      such as tuple deformation.  The fields of this struct are populated
      54             :  *      using the populate_compact_attribute() function, which must be called
      55             :  *      directly after the FormData_pg_attribute struct is populated or
      56             :  *      altered in any way.
      57             :  *
      58             :  * Currently, this struct is 16 bytes.  Any code changes which enlarge this
      59             :  * struct should be considered very carefully.
      60             :  *
      61             :  * Code which must access a TupleDesc's attribute data should always make use
      62             :  * the fields of this struct when required fields are available here.  It's
      63             :  * more efficient to access the memory in CompactAttribute due to it being a
      64             :  * more compact representation of FormData_pg_attribute and also because
      65             :  * accessing the FormData_pg_attribute requires an additional calculations to
      66             :  * obtain the base address of the array within the TupleDesc.
      67             :  */
      68             : typedef struct CompactAttribute
      69             : {
      70             :     int32       attcacheoff;    /* fixed offset into tuple, if known, or -1 */
      71             :     int16       attlen;         /* attr len in bytes or -1 = varlen, -2 =
      72             :                                  * cstring */
      73             :     bool        attbyval;       /* as FormData_pg_attribute.attbyval */
      74             :     bool        attispackable;  /* FormData_pg_attribute.attstorage !=
      75             :                                  * TYPSTORAGE_PLAIN */
      76             :     bool        atthasmissing;  /* as FormData_pg_attribute.atthasmissing */
      77             :     bool        attisdropped;   /* as FormData_pg_attribute.attisdropped */
      78             :     bool        attgenerated;   /* FormData_pg_attribute.attgenerated != '\0' */
      79             :     bool        attnotnull;     /* as FormData_pg_attribute.attnotnull */
      80             :     uint8       attalignby;     /* alignment requirement in bytes */
      81             : } CompactAttribute;
      82             : 
      83             : /*
      84             :  * This struct is passed around within the backend to describe the structure
      85             :  * of tuples.  For tuples coming from on-disk relations, the information is
      86             :  * collected from the pg_attribute, pg_attrdef, and pg_constraint catalogs.
      87             :  * Transient row types (such as the result of a join query) have anonymous
      88             :  * TupleDesc structs that generally omit any constraint info; therefore the
      89             :  * structure is designed to let the constraints be omitted efficiently.
      90             :  *
      91             :  * Note that only user attributes, not system attributes, are mentioned in
      92             :  * TupleDesc.
      93             :  *
      94             :  * If the tupdesc is known to correspond to a named rowtype (such as a table's
      95             :  * rowtype) then tdtypeid identifies that type and tdtypmod is -1.  Otherwise
      96             :  * tdtypeid is RECORDOID, and tdtypmod can be either -1 for a fully anonymous
      97             :  * row type, or a value >= 0 to allow the rowtype to be looked up in the
      98             :  * typcache.c type cache.
      99             :  *
     100             :  * Note that tdtypeid is never the OID of a domain over composite, even if
     101             :  * we are dealing with values that are known (at some higher level) to be of
     102             :  * a domain-over-composite type.  This is because tdtypeid/tdtypmod need to
     103             :  * match up with the type labeling of composite Datums, and those are never
     104             :  * explicitly marked as being of a domain type, either.
     105             :  *
     106             :  * Tuple descriptors that live in caches (relcache or typcache, at present)
     107             :  * are reference-counted: they can be deleted when their reference count goes
     108             :  * to zero.  Tuple descriptors created by the executor need no reference
     109             :  * counting, however: they are simply created in the appropriate memory
     110             :  * context and go away when the context is freed.  We set the tdrefcount
     111             :  * field of such a descriptor to -1, while reference-counted descriptors
     112             :  * always have tdrefcount >= 0.
     113             :  *
     114             :  * Beyond the compact_attrs variable length array, the TupleDesc stores an
     115             :  * array of FormData_pg_attribute.  The TupleDescAttr() function, as defined
     116             :  * below, takes care of calculating the address of the elements of the
     117             :  * FormData_pg_attribute array.
     118             :  *
     119             :  * The array of CompactAttribute is effectively an abbreviated version of the
     120             :  * array of FormData_pg_attribute.  Because CompactAttribute is significantly
     121             :  * smaller than FormData_pg_attribute, code, especially performance-critical
     122             :  * code, should prioritize using the fields from the CompactAttribute over the
     123             :  * equivalent fields in FormData_pg_attribute.
     124             :  *
     125             :  * Any code making changes manually to and fields in the FormData_pg_attribute
     126             :  * array must subsequently call populate_compact_attribute() to flush the
     127             :  * changes out to the corresponding 'compact_attrs' element.
     128             :  */
     129             : typedef struct TupleDescData
     130             : {
     131             :     int         natts;          /* number of attributes in the tuple */
     132             :     Oid         tdtypeid;       /* composite type ID for tuple type */
     133             :     int32       tdtypmod;       /* typmod for tuple type */
     134             :     int         tdrefcount;     /* reference count, or -1 if not counting */
     135             :     TupleConstr *constr;        /* constraints, or NULL if none */
     136             :     /* compact_attrs[N] is the compact metadata of Attribute Number N+1 */
     137             :     CompactAttribute compact_attrs[FLEXIBLE_ARRAY_MEMBER];
     138             : }           TupleDescData;
     139             : typedef struct TupleDescData *TupleDesc;
     140             : 
     141             : extern void populate_compact_attribute(TupleDesc tupdesc, int attnum);
     142             : 
     143             : /*
     144             :  * Calculates the base address of the Form_pg_attribute at the end of the
     145             :  * TupleDescData struct.
     146             :  */
     147             : #define TupleDescAttrAddress(desc) \
     148             :     (Form_pg_attribute) ((char *) (desc) + \
     149             :      (offsetof(struct TupleDescData, compact_attrs) + \
     150             :      (desc)->natts * sizeof(CompactAttribute)))
     151             : 
     152             : /* Accessor for the i'th FormData_pg_attribute element of tupdesc. */
     153             : static inline FormData_pg_attribute *
     154   305009388 : TupleDescAttr(TupleDesc tupdesc, int i)
     155             : {
     156   305009388 :     FormData_pg_attribute *attrs = TupleDescAttrAddress(tupdesc);
     157             : 
     158   305009388 :     return &attrs[i];
     159             : }
     160             : 
     161             : #undef TupleDescAttrAddress
     162             : 
     163             : extern void verify_compact_attribute(TupleDesc, int attnum);
     164             : 
     165             : /*
     166             :  * Accessor for the i'th CompactAttribute element of tupdesc.
     167             :  */
     168             : static inline CompactAttribute *
     169  2695444536 : TupleDescCompactAttr(TupleDesc tupdesc, int i)
     170             : {
     171  2695444536 :     CompactAttribute *cattr = &tupdesc->compact_attrs[i];
     172             : 
     173             : #ifdef USE_ASSERT_CHECKING
     174             : 
     175             :     /* Check that the CompactAttribute is correctly populated */
     176             :     verify_compact_attribute(tupdesc, i);
     177             : #endif
     178             : 
     179  2695444536 :     return cattr;
     180             : }
     181             : 
     182             : extern TupleDesc CreateTemplateTupleDesc(int natts);
     183             : 
     184             : extern TupleDesc CreateTupleDesc(int natts, Form_pg_attribute *attrs);
     185             : 
     186             : extern TupleDesc CreateTupleDescCopy(TupleDesc tupdesc);
     187             : 
     188             : extern TupleDesc CreateTupleDescTruncatedCopy(TupleDesc tupdesc, int natts);
     189             : 
     190             : extern TupleDesc CreateTupleDescCopyConstr(TupleDesc tupdesc);
     191             : 
     192             : #define TupleDescSize(src) \
     193             :     (offsetof(struct TupleDescData, compact_attrs) + \
     194             :      (src)->natts * sizeof(CompactAttribute) + \
     195             :      (src)->natts * sizeof(FormData_pg_attribute))
     196             : 
     197             : extern void TupleDescCopy(TupleDesc dst, TupleDesc src);
     198             : 
     199             : extern void TupleDescCopyEntry(TupleDesc dst, AttrNumber dstAttno,
     200             :                                TupleDesc src, AttrNumber srcAttno);
     201             : 
     202             : extern void FreeTupleDesc(TupleDesc tupdesc);
     203             : 
     204             : extern void IncrTupleDescRefCount(TupleDesc tupdesc);
     205             : extern void DecrTupleDescRefCount(TupleDesc tupdesc);
     206             : 
     207             : #define PinTupleDesc(tupdesc) \
     208             :     do { \
     209             :         if ((tupdesc)->tdrefcount >= 0) \
     210             :             IncrTupleDescRefCount(tupdesc); \
     211             :     } while (0)
     212             : 
     213             : #define ReleaseTupleDesc(tupdesc) \
     214             :     do { \
     215             :         if ((tupdesc)->tdrefcount >= 0) \
     216             :             DecrTupleDescRefCount(tupdesc); \
     217             :     } while (0)
     218             : 
     219             : extern bool equalTupleDescs(TupleDesc tupdesc1, TupleDesc tupdesc2);
     220             : extern bool equalRowTypes(TupleDesc tupdesc1, TupleDesc tupdesc2);
     221             : extern uint32 hashRowType(TupleDesc desc);
     222             : 
     223             : extern void TupleDescInitEntry(TupleDesc desc,
     224             :                                AttrNumber attributeNumber,
     225             :                                const char *attributeName,
     226             :                                Oid oidtypeid,
     227             :                                int32 typmod,
     228             :                                int attdim);
     229             : 
     230             : extern void TupleDescInitBuiltinEntry(TupleDesc desc,
     231             :                                       AttrNumber attributeNumber,
     232             :                                       const char *attributeName,
     233             :                                       Oid oidtypeid,
     234             :                                       int32 typmod,
     235             :                                       int attdim);
     236             : 
     237             : extern void TupleDescInitEntryCollation(TupleDesc desc,
     238             :                                         AttrNumber attributeNumber,
     239             :                                         Oid collationid);
     240             : 
     241             : extern TupleDesc BuildDescFromLists(const List *names, const List *types, const List *typmods, const List *collations);
     242             : 
     243             : extern Node *TupleDescGetDefault(TupleDesc tupdesc, AttrNumber attnum);
     244             : 
     245             : #endif                          /* TUPDESC_H */

Generated by: LCOV version 1.14