codekingpro/portable-devtools

1/*-------------------------------------------------------------------------2 *3 * tuptable.h4 *	  tuple table support stuff5 *6 *7 * Portions Copyright (c) 1996-2023, PostgreSQL Global Development Group8 * Portions Copyright (c) 1994, Regents of the University of California9 *10 * src/include/executor/tuptable.h11 *12 *-------------------------------------------------------------------------13 */14#ifndef TUPTABLE_H15#define TUPTABLE_H16 17#include "access/htup.h"18#include "access/htup_details.h"19#include "access/sysattr.h"20#include "access/tupdesc.h"21#include "storage/buf.h"22 23/*----------24 * The executor stores tuples in a "tuple table" which is a List of25 * independent TupleTableSlots.26 *27 * There's various different types of tuple table slots, each being able to28 * store different types of tuples. Additional types of slots can be added29 * without modifying core code. The type of a slot is determined by the30 * TupleTableSlotOps* passed to the slot creation routine. The builtin types31 * of slots are32 *33 * 1. physical tuple in a disk buffer page (TTSOpsBufferHeapTuple)34 * 2. physical tuple constructed in palloc'ed memory (TTSOpsHeapTuple)35 * 3. "minimal" physical tuple constructed in palloc'ed memory36 *    (TTSOpsMinimalTuple)37 * 4. "virtual" tuple consisting of Datum/isnull arrays (TTSOpsVirtual)38 *39 *40 * The first two cases are similar in that they both deal with "materialized"41 * tuples, but resource management is different.  For a tuple in a disk page42 * we need to hold a pin on the buffer until the TupleTableSlot's reference43 * to the tuple is dropped; while for a palloc'd tuple we usually want the44 * tuple pfree'd when the TupleTableSlot's reference is dropped.45 *46 * A "minimal" tuple is handled similarly to a palloc'd regular tuple.47 * At present, minimal tuples never are stored in buffers, so there is no48 * parallel to case 1.  Note that a minimal tuple has no "system columns".49 *50 * A "virtual" tuple is an optimization used to minimize physical data copying51 * in a nest of plan nodes.  Until materialized pass-by-reference Datums in52 * the slot point to storage that is not directly associated with the53 * TupleTableSlot; generally they will point to part of a tuple stored in a54 * lower plan node's output TupleTableSlot, or to a function result55 * constructed in a plan node's per-tuple econtext.  It is the responsibility56 * of the generating plan node to be sure these resources are not released for57 * as long as the virtual tuple needs to be valid or is materialized.  Note58 * also that a virtual tuple does not have any "system columns".59 *60 * The Datum/isnull arrays of a TupleTableSlot serve double duty.  For virtual61 * slots they are the authoritative data.  For the other builtin slots,62 * the arrays contain data extracted from the tuple.  (In this state, any63 * pass-by-reference Datums point into the physical tuple.)  The extracted64 * information is built "lazily", ie, only as needed.  This serves to avoid65 * repeated extraction of data from the physical tuple.66 *67 * A TupleTableSlot can also be "empty", indicated by flag TTS_FLAG_EMPTY set68 * in tts_flags, holding no valid data.  This is the only valid state for a69 * freshly-created slot that has not yet had a tuple descriptor assigned to70 * it.  In this state, TTS_FLAG_SHOULDFREE should not be set in tts_flags and71 * tts_nvalid should be set to zero.72 *73 * The tupleDescriptor is simply referenced, not copied, by the TupleTableSlot74 * code.  The caller of ExecSetSlotDescriptor() is responsible for providing75 * a descriptor that will live as long as the slot does.  (Typically, both76 * slots and descriptors are in per-query memory and are freed by memory77 * context deallocation at query end; so it's not worth providing any extra78 * mechanism to do more.  However, the slot will increment the tupdesc79 * reference count if a reference-counted tupdesc is supplied.)80 *81 * When TTS_FLAG_SHOULDFREE is set in tts_flags, the physical tuple is "owned"82 * by the slot and should be freed when the slot's reference to the tuple is83 * dropped.84 *85 * tts_values/tts_isnull are allocated either when the slot is created (when86 * the descriptor is provided), or when a descriptor is assigned to the slot;87 * they are of length equal to the descriptor's natts.88 *89 * The TTS_FLAG_SLOW flag is saved state for90 * slot_deform_heap_tuple, and should not be touched by any other code.91 *----------92 */93 94/* true = slot is empty */95#define			TTS_FLAG_EMPTY			(1 << 1)96#define TTS_EMPTY(slot)	(((slot)->tts_flags & TTS_FLAG_EMPTY) != 0)97 98/* should pfree tuple "owned" by the slot? */99#define			TTS_FLAG_SHOULDFREE		(1 << 2)100#define TTS_SHOULDFREE(slot) (((slot)->tts_flags & TTS_FLAG_SHOULDFREE) != 0)101 102/* saved state for slot_deform_heap_tuple */103#define			TTS_FLAG_SLOW		(1 << 3)104#define TTS_SLOW(slot) (((slot)->tts_flags & TTS_FLAG_SLOW) != 0)105 106/* fixed tuple descriptor */107#define			TTS_FLAG_FIXED		(1 << 4)108#define TTS_FIXED(slot) (((slot)->tts_flags & TTS_FLAG_FIXED) != 0)109 110struct TupleTableSlotOps;111typedef struct TupleTableSlotOps TupleTableSlotOps;112 113/* base tuple table slot type */114typedef struct TupleTableSlot115{116	NodeTag		type;117#define FIELDNO_TUPLETABLESLOT_FLAGS 1118	uint16		tts_flags;		/* Boolean states */119#define FIELDNO_TUPLETABLESLOT_NVALID 2120	AttrNumber	tts_nvalid;		/* # of valid values in tts_values */121	const TupleTableSlotOps *const tts_ops; /* implementation of slot */122#define FIELDNO_TUPLETABLESLOT_TUPLEDESCRIPTOR 4123	TupleDesc	tts_tupleDescriptor;	/* slot's tuple descriptor */124#define FIELDNO_TUPLETABLESLOT_VALUES 5125	Datum	   *tts_values;		/* current per-attribute values */126#define FIELDNO_TUPLETABLESLOT_ISNULL 6127	bool	   *tts_isnull;		/* current per-attribute isnull flags */128	MemoryContext tts_mcxt;		/* slot itself is in this context */129	ItemPointerData tts_tid;	/* stored tuple's tid */130	Oid			tts_tableOid;	/* table oid of tuple */131} TupleTableSlot;132 133/* routines for a TupleTableSlot implementation */134struct TupleTableSlotOps135{136	/* Minimum size of the slot */137	size_t		base_slot_size;138 139	/* Initialization. */140	void		(*init) (TupleTableSlot *slot);141 142	/* Destruction. */143	void		(*release) (TupleTableSlot *slot);144 145	/*146	 * Clear the contents of the slot. Only the contents are expected to be147	 * cleared and not the tuple descriptor. Typically an implementation of148	 * this callback should free the memory allocated for the tuple contained149	 * in the slot.150	 */151	void		(*clear) (TupleTableSlot *slot);152 153	/*154	 * Fill up first natts entries of tts_values and tts_isnull arrays with155	 * values from the tuple contained in the slot. The function may be called156	 * with natts more than the number of attributes available in the tuple,157	 * in which case it should set tts_nvalid to the number of returned158	 * columns.159	 */160	void		(*getsomeattrs) (TupleTableSlot *slot, int natts);161 162	/*163	 * Returns value of the given system attribute as a datum and sets isnull164	 * to false, if it's not NULL. Throws an error if the slot type does not165	 * support system attributes.166	 */167	Datum		(*getsysattr) (TupleTableSlot *slot, int attnum, bool *isnull);168 169	/*170	 * Make the contents of the slot solely depend on the slot, and not on171	 * underlying resources (like another memory context, buffers, etc).172	 */173	void		(*materialize) (TupleTableSlot *slot);174 175	/*176	 * Copy the contents of the source slot into the destination slot's own177	 * context. Invoked using callback of the destination slot.178	 */179	void		(*copyslot) (TupleTableSlot *dstslot, TupleTableSlot *srcslot);180 181	/*182	 * Return a heap tuple "owned" by the slot. It is slot's responsibility to183	 * free the memory consumed by the heap tuple. If the slot can not "own" a184	 * heap tuple, it should not implement this callback and should set it as185	 * NULL.186	 */187	HeapTuple	(*get_heap_tuple) (TupleTableSlot *slot);188 189	/*190	 * Return a minimal tuple "owned" by the slot. It is slot's responsibility191	 * to free the memory consumed by the minimal tuple. If the slot can not192	 * "own" a minimal tuple, it should not implement this callback and should193	 * set it as NULL.194	 */195	MinimalTuple (*get_minimal_tuple) (TupleTableSlot *slot);196 197	/*198	 * Return a copy of heap tuple representing the contents of the slot. The199	 * copy needs to be palloc'd in the current memory context. The slot200	 * itself is expected to remain unaffected. It is *not* expected to have201	 * meaningful "system columns" in the copy. The copy is not be "owned" by202	 * the slot i.e. the caller has to take responsibility to free memory203	 * consumed by the slot.204	 */205	HeapTuple	(*copy_heap_tuple) (TupleTableSlot *slot);206 207	/*208	 * Return a copy of minimal tuple representing the contents of the slot.209	 * The copy needs to be palloc'd in the current memory context. The slot210	 * itself is expected to remain unaffected. It is *not* expected to have211	 * meaningful "system columns" in the copy. The copy is not be "owned" by212	 * the slot i.e. the caller has to take responsibility to free memory213	 * consumed by the slot.214	 */215	MinimalTuple (*copy_minimal_tuple) (TupleTableSlot *slot);216};217 218/*219 * Predefined TupleTableSlotOps for various types of TupleTableSlotOps. The220 * same are used to identify the type of a given slot.221 */222extern PGDLLIMPORT const TupleTableSlotOps TTSOpsVirtual;223extern PGDLLIMPORT const TupleTableSlotOps TTSOpsHeapTuple;224extern PGDLLIMPORT const TupleTableSlotOps TTSOpsMinimalTuple;225extern PGDLLIMPORT const TupleTableSlotOps TTSOpsBufferHeapTuple;226 227#define TTS_IS_VIRTUAL(slot) ((slot)->tts_ops == &TTSOpsVirtual)228#define TTS_IS_HEAPTUPLE(slot) ((slot)->tts_ops == &TTSOpsHeapTuple)229#define TTS_IS_MINIMALTUPLE(slot) ((slot)->tts_ops == &TTSOpsMinimalTuple)230#define TTS_IS_BUFFERTUPLE(slot) ((slot)->tts_ops == &TTSOpsBufferHeapTuple)231 232 233/*234 * Tuple table slot implementations.235 */236 237typedef struct VirtualTupleTableSlot238{239	pg_node_attr(abstract)240 241	TupleTableSlot base;242 243	char	   *data;			/* data for materialized slots */244} VirtualTupleTableSlot;245 246typedef struct HeapTupleTableSlot247{248	pg_node_attr(abstract)249 250	TupleTableSlot base;251 252#define FIELDNO_HEAPTUPLETABLESLOT_TUPLE 1253	HeapTuple	tuple;			/* physical tuple */254#define FIELDNO_HEAPTUPLETABLESLOT_OFF 2255	uint32		off;			/* saved state for slot_deform_heap_tuple */256	HeapTupleData tupdata;		/* optional workspace for storing tuple */257} HeapTupleTableSlot;258 259/* heap tuple residing in a buffer */260typedef struct BufferHeapTupleTableSlot261{262	pg_node_attr(abstract)263 264	HeapTupleTableSlot base;265 266	/*267	 * If buffer is not InvalidBuffer, then the slot is holding a pin on the268	 * indicated buffer page; drop the pin when we release the slot's269	 * reference to that buffer.  (TTS_FLAG_SHOULDFREE should not be set in270	 * such a case, since presumably base.tuple is pointing into the buffer.)271	 */272	Buffer		buffer;			/* tuple's buffer, or InvalidBuffer */273} BufferHeapTupleTableSlot;274 275typedef struct MinimalTupleTableSlot276{277	pg_node_attr(abstract)278 279	TupleTableSlot base;280 281	/*282	 * In a minimal slot tuple points at minhdr and the fields of that struct283	 * are set correctly for access to the minimal tuple; in particular,284	 * minhdr.t_data points MINIMAL_TUPLE_OFFSET bytes before mintuple.  This285	 * allows column extraction to treat the case identically to regular286	 * physical tuples.287	 */288#define FIELDNO_MINIMALTUPLETABLESLOT_TUPLE 1289	HeapTuple	tuple;			/* tuple wrapper */290	MinimalTuple mintuple;		/* minimal tuple, or NULL if none */291	HeapTupleData minhdr;		/* workspace for minimal-tuple-only case */292#define FIELDNO_MINIMALTUPLETABLESLOT_OFF 4293	uint32		off;			/* saved state for slot_deform_heap_tuple */294} MinimalTupleTableSlot;295 296/*297 * TupIsNull -- is a TupleTableSlot empty?298 */299#define TupIsNull(slot) \300	((slot) == NULL || TTS_EMPTY(slot))301 302/* in executor/execTuples.c */303extern TupleTableSlot *MakeTupleTableSlot(TupleDesc tupleDesc,304										  const TupleTableSlotOps *tts_ops);305extern TupleTableSlot *ExecAllocTableSlot(List **tupleTable, TupleDesc desc,306										  const TupleTableSlotOps *tts_ops);307extern void ExecResetTupleTable(List *tupleTable, bool shouldFree);308extern TupleTableSlot *MakeSingleTupleTableSlot(TupleDesc tupdesc,309												const TupleTableSlotOps *tts_ops);310extern void ExecDropSingleTupleTableSlot(TupleTableSlot *slot);311extern void ExecSetSlotDescriptor(TupleTableSlot *slot, TupleDesc tupdesc);312extern TupleTableSlot *ExecStoreHeapTuple(HeapTuple tuple,313										  TupleTableSlot *slot,314										  bool shouldFree);315extern void ExecForceStoreHeapTuple(HeapTuple tuple,316									TupleTableSlot *slot,317									bool shouldFree);318extern TupleTableSlot *ExecStoreBufferHeapTuple(HeapTuple tuple,319												TupleTableSlot *slot,320												Buffer buffer);321extern TupleTableSlot *ExecStorePinnedBufferHeapTuple(HeapTuple tuple,322													  TupleTableSlot *slot,323													  Buffer buffer);324extern TupleTableSlot *ExecStoreMinimalTuple(MinimalTuple mtup,325											 TupleTableSlot *slot,326											 bool shouldFree);327extern void ExecForceStoreMinimalTuple(MinimalTuple mtup, TupleTableSlot *slot,328									   bool shouldFree);329extern TupleTableSlot *ExecStoreVirtualTuple(TupleTableSlot *slot);330extern TupleTableSlot *ExecStoreAllNullTuple(TupleTableSlot *slot);331extern void ExecStoreHeapTupleDatum(Datum data, TupleTableSlot *slot);332extern HeapTuple ExecFetchSlotHeapTuple(TupleTableSlot *slot, bool materialize, bool *shouldFree);333extern MinimalTuple ExecFetchSlotMinimalTuple(TupleTableSlot *slot,334											  bool *shouldFree);335extern Datum ExecFetchSlotHeapTupleDatum(TupleTableSlot *slot);336extern void slot_getmissingattrs(TupleTableSlot *slot, int startAttNum,337								 int lastAttNum);338extern void slot_getsomeattrs_int(TupleTableSlot *slot, int attnum);339 340 341#ifndef FRONTEND342 343/*344 * This function forces the entries of the slot's Datum/isnull arrays to be345 * valid at least up through the attnum'th entry.346 */347static inline void348slot_getsomeattrs(TupleTableSlot *slot, int attnum)349{350	if (slot->tts_nvalid < attnum)351		slot_getsomeattrs_int(slot, attnum);352}353 354/*355 * slot_getallattrs356 *		This function forces all the entries of the slot's Datum/isnull357 *		arrays to be valid.  The caller may then extract data directly358 *		from those arrays instead of using slot_getattr.359 */360static inline void361slot_getallattrs(TupleTableSlot *slot)362{363	slot_getsomeattrs(slot, slot->tts_tupleDescriptor->natts);364}365 366 367/*368 * slot_attisnull369 *370 * Detect whether an attribute of the slot is null, without actually fetching371 * it.372 */373static inline bool374slot_attisnull(TupleTableSlot *slot, int attnum)375{376	Assert(attnum > 0);377 378	if (attnum > slot->tts_nvalid)379		slot_getsomeattrs(slot, attnum);380 381	return slot->tts_isnull[attnum - 1];382}383 384/*385 * slot_getattr - fetch one attribute of the slot's contents.386 */387static inline Datum388slot_getattr(TupleTableSlot *slot, int attnum,389			 bool *isnull)390{391	Assert(attnum > 0);392 393	if (attnum > slot->tts_nvalid)394		slot_getsomeattrs(slot, attnum);395 396	*isnull = slot->tts_isnull[attnum - 1];397 398	return slot->tts_values[attnum - 1];399}400 401/*402 * slot_getsysattr - fetch a system attribute of the slot's current tuple.403 *404 *  If the slot type does not contain system attributes, this will throw an405 *  error.  Hence before calling this function, callers should make sure that406 *  the slot type is the one that supports system attributes.407 */408static inline Datum409slot_getsysattr(TupleTableSlot *slot, int attnum, bool *isnull)410{411	Assert(attnum < 0);			/* caller error */412 413	if (attnum == TableOidAttributeNumber)414	{415		*isnull = false;416		return ObjectIdGetDatum(slot->tts_tableOid);417	}418	else if (attnum == SelfItemPointerAttributeNumber)419	{420		*isnull = false;421		return PointerGetDatum(&slot->tts_tid);422	}423 424	/* Fetch the system attribute from the underlying tuple. */425	return slot->tts_ops->getsysattr(slot, attnum, isnull);426}427 428/*429 * ExecClearTuple - clear the slot's contents430 */431static inline TupleTableSlot *432ExecClearTuple(TupleTableSlot *slot)433{434	slot->tts_ops->clear(slot);435 436	return slot;437}438 439/* ExecMaterializeSlot - force a slot into the "materialized" state.440 *441 * This causes the slot's tuple to be a local copy not dependent on any442 * external storage (i.e. pointing into a Buffer, or having allocations in443 * another memory context).444 *445 * A typical use for this operation is to prepare a computed tuple for being446 * stored on disk.  The original data may or may not be virtual, but in any447 * case we need a private copy for heap_insert to scribble on.448 */449static inline void450ExecMaterializeSlot(TupleTableSlot *slot)451{452	slot->tts_ops->materialize(slot);453}454 455/*456 * ExecCopySlotHeapTuple - return HeapTuple allocated in caller's context457 */458static inline HeapTuple459ExecCopySlotHeapTuple(TupleTableSlot *slot)460{461	Assert(!TTS_EMPTY(slot));462 463	return slot->tts_ops->copy_heap_tuple(slot);464}465 466/*467 * ExecCopySlotMinimalTuple - return MinimalTuple allocated in caller's context468 */469static inline MinimalTuple470ExecCopySlotMinimalTuple(TupleTableSlot *slot)471{472	return slot->tts_ops->copy_minimal_tuple(slot);473}474 475/*476 * ExecCopySlot - copy one slot's contents into another.477 *478 * If a source's system attributes are supposed to be accessed in the target479 * slot, the target slot and source slot types need to match.480 */481static inline TupleTableSlot *482ExecCopySlot(TupleTableSlot *dstslot, TupleTableSlot *srcslot)483{484	Assert(!TTS_EMPTY(srcslot));485	Assert(srcslot != dstslot);486 487	dstslot->tts_ops->copyslot(dstslot, srcslot);488 489	return dstslot;490}491 492#endif							/* FRONTEND */493 494#endif							/* TUPTABLE_H */495