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; /* any not-null, including not valid ones */
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 : char attnullability; /* status of not-null constraint, see below */
80 : uint8 attalignby; /* alignment requirement in bytes */
81 : } CompactAttribute;
82 :
83 : /* Valid values for CompactAttribute->attnullability */
84 : #define ATTNULLABLE_UNRESTRICTED 'f' /* No constraint exists */
85 : #define ATTNULLABLE_UNKNOWN 'u' /* constraint exists, validity unknown */
86 : #define ATTNULLABLE_VALID 'v' /* valid constraint exists */
87 : #define ATTNULLABLE_INVALID 'i' /* constraint exists, marked invalid */
88 :
89 : /*
90 : * This struct is passed around within the backend to describe the structure
91 : * of tuples. For tuples coming from on-disk relations, the information is
92 : * collected from the pg_attribute, pg_attrdef, and pg_constraint catalogs.
93 : * Transient row types (such as the result of a join query) have anonymous
94 : * TupleDesc structs that generally omit any constraint info; therefore the
95 : * structure is designed to let the constraints be omitted efficiently.
96 : *
97 : * Note that only user attributes, not system attributes, are mentioned in
98 : * TupleDesc.
99 : *
100 : * If the tupdesc is known to correspond to a named rowtype (such as a table's
101 : * rowtype) then tdtypeid identifies that type and tdtypmod is -1. Otherwise
102 : * tdtypeid is RECORDOID, and tdtypmod can be either -1 for a fully anonymous
103 : * row type, or a value >= 0 to allow the rowtype to be looked up in the
104 : * typcache.c type cache.
105 : *
106 : * Note that tdtypeid is never the OID of a domain over composite, even if
107 : * we are dealing with values that are known (at some higher level) to be of
108 : * a domain-over-composite type. This is because tdtypeid/tdtypmod need to
109 : * match up with the type labeling of composite Datums, and those are never
110 : * explicitly marked as being of a domain type, either.
111 : *
112 : * Tuple descriptors that live in caches (relcache or typcache, at present)
113 : * are reference-counted: they can be deleted when their reference count goes
114 : * to zero. Tuple descriptors created by the executor need no reference
115 : * counting, however: they are simply created in the appropriate memory
116 : * context and go away when the context is freed. We set the tdrefcount
117 : * field of such a descriptor to -1, while reference-counted descriptors
118 : * always have tdrefcount >= 0.
119 : *
120 : * Beyond the compact_attrs variable length array, the TupleDesc stores an
121 : * array of FormData_pg_attribute. The TupleDescAttr() function, as defined
122 : * below, takes care of calculating the address of the elements of the
123 : * FormData_pg_attribute array.
124 : *
125 : * The array of CompactAttribute is effectively an abbreviated version of the
126 : * array of FormData_pg_attribute. Because CompactAttribute is significantly
127 : * smaller than FormData_pg_attribute, code, especially performance-critical
128 : * code, should prioritize using the fields from the CompactAttribute over the
129 : * equivalent fields in FormData_pg_attribute.
130 : *
131 : * Any code making changes manually to and fields in the FormData_pg_attribute
132 : * array must subsequently call populate_compact_attribute() to flush the
133 : * changes out to the corresponding 'compact_attrs' element.
134 : */
135 : typedef struct TupleDescData
136 : {
137 : int natts; /* number of attributes in the tuple */
138 : Oid tdtypeid; /* composite type ID for tuple type */
139 : int32 tdtypmod; /* typmod for tuple type */
140 : int tdrefcount; /* reference count, or -1 if not counting */
141 : TupleConstr *constr; /* constraints, or NULL if none */
142 : /* compact_attrs[N] is the compact metadata of Attribute Number N+1 */
143 : CompactAttribute compact_attrs[FLEXIBLE_ARRAY_MEMBER];
144 : } TupleDescData;
145 : typedef struct TupleDescData *TupleDesc;
146 :
147 : extern void populate_compact_attribute(TupleDesc tupdesc, int attnum);
148 :
149 : /*
150 : * Calculates the base address of the Form_pg_attribute at the end of the
151 : * TupleDescData struct.
152 : */
153 : #define TupleDescAttrAddress(desc) \
154 : (Form_pg_attribute) ((char *) (desc) + \
155 : (offsetof(struct TupleDescData, compact_attrs) + \
156 : (desc)->natts * sizeof(CompactAttribute)))
157 :
158 : /* Accessor for the i'th FormData_pg_attribute element of tupdesc. */
159 : static inline FormData_pg_attribute *
160 327049310 : TupleDescAttr(TupleDesc tupdesc, int i)
161 : {
162 327049310 : FormData_pg_attribute *attrs = TupleDescAttrAddress(tupdesc);
163 :
164 327049310 : return &attrs[i];
165 : }
166 :
167 : #undef TupleDescAttrAddress
168 :
169 : extern void verify_compact_attribute(TupleDesc, int attnum);
170 :
171 : /*
172 : * Accessor for the i'th CompactAttribute element of tupdesc.
173 : */
174 : static inline CompactAttribute *
175 2990894834 : TupleDescCompactAttr(TupleDesc tupdesc, int i)
176 : {
177 2990894834 : CompactAttribute *cattr = &tupdesc->compact_attrs[i];
178 :
179 : #ifdef USE_ASSERT_CHECKING
180 :
181 : /* Check that the CompactAttribute is correctly populated */
182 : verify_compact_attribute(tupdesc, i);
183 : #endif
184 :
185 2990894834 : return cattr;
186 : }
187 :
188 : extern TupleDesc CreateTemplateTupleDesc(int natts);
189 :
190 : extern TupleDesc CreateTupleDesc(int natts, Form_pg_attribute *attrs);
191 :
192 : extern TupleDesc CreateTupleDescCopy(TupleDesc tupdesc);
193 :
194 : extern TupleDesc CreateTupleDescTruncatedCopy(TupleDesc tupdesc, int natts);
195 :
196 : extern TupleDesc CreateTupleDescCopyConstr(TupleDesc tupdesc);
197 :
198 : #define TupleDescSize(src) \
199 : (offsetof(struct TupleDescData, compact_attrs) + \
200 : (src)->natts * sizeof(CompactAttribute) + \
201 : (src)->natts * sizeof(FormData_pg_attribute))
202 :
203 : extern void TupleDescCopy(TupleDesc dst, TupleDesc src);
204 :
205 : extern void TupleDescCopyEntry(TupleDesc dst, AttrNumber dstAttno,
206 : TupleDesc src, AttrNumber srcAttno);
207 :
208 : extern void FreeTupleDesc(TupleDesc tupdesc);
209 :
210 : extern void IncrTupleDescRefCount(TupleDesc tupdesc);
211 : extern void DecrTupleDescRefCount(TupleDesc tupdesc);
212 :
213 : #define PinTupleDesc(tupdesc) \
214 : do { \
215 : if ((tupdesc)->tdrefcount >= 0) \
216 : IncrTupleDescRefCount(tupdesc); \
217 : } while (0)
218 :
219 : #define ReleaseTupleDesc(tupdesc) \
220 : do { \
221 : if ((tupdesc)->tdrefcount >= 0) \
222 : DecrTupleDescRefCount(tupdesc); \
223 : } while (0)
224 :
225 : extern bool equalTupleDescs(TupleDesc tupdesc1, TupleDesc tupdesc2);
226 : extern bool equalRowTypes(TupleDesc tupdesc1, TupleDesc tupdesc2);
227 : extern uint32 hashRowType(TupleDesc desc);
228 :
229 : extern void TupleDescInitEntry(TupleDesc desc,
230 : AttrNumber attributeNumber,
231 : const char *attributeName,
232 : Oid oidtypeid,
233 : int32 typmod,
234 : int attdim);
235 :
236 : extern void TupleDescInitBuiltinEntry(TupleDesc desc,
237 : AttrNumber attributeNumber,
238 : const char *attributeName,
239 : Oid oidtypeid,
240 : int32 typmod,
241 : int attdim);
242 :
243 : extern void TupleDescInitEntryCollation(TupleDesc desc,
244 : AttrNumber attributeNumber,
245 : Oid collationid);
246 :
247 : extern TupleDesc BuildDescFromLists(const List *names, const List *types, const List *typmods, const List *collations);
248 :
249 : extern Node *TupleDescGetDefault(TupleDesc tupdesc, AttrNumber attnum);
250 :
251 : #endif /* TUPDESC_H */
|
