codekingpro/portable-devtools

1/*-------------------------------------------------------------------------2 *3 * expandeddatum.h4 *	  Declarations for access to "expanded" value representations.5 *6 * Complex data types, particularly container types such as arrays and7 * records, usually have on-disk representations that are compact but not8 * especially convenient to modify.  What's more, when we do modify them,9 * having to recopy all the rest of the value can be extremely inefficient.10 * Therefore, we provide a notion of an "expanded" representation that is used11 * only in memory and is optimized more for computation than storage.12 * The format appearing on disk is called the data type's "flattened"13 * representation, since it is required to be a contiguous blob of bytes --14 * but the type can have an expanded representation that is not.  Data types15 * must provide means to translate an expanded representation back to16 * flattened form.17 *18 * An expanded object is meant to survive across multiple operations, but19 * not to be enormously long-lived; for example it might be a local variable20 * in a PL/pgSQL procedure.  So its extra bulk compared to the on-disk format21 * is a worthwhile trade-off.22 *23 * References to expanded objects are a type of TOAST pointer.24 * Because of longstanding conventions in Postgres, this means that the25 * flattened form of such an object must always be a varlena object.26 * Fortunately that's no restriction in practice.27 *28 * There are actually two kinds of TOAST pointers for expanded objects:29 * read-only and read-write pointers.  Possession of one of the latter30 * authorizes a function to modify the value in-place rather than copying it31 * as would normally be required.  Functions should always return a read-write32 * pointer to any new expanded object they create.  Functions that modify an33 * argument value in-place must take care that they do not corrupt the old34 * value if they fail partway through.35 *36 *37 * Portions Copyright (c) 1996-2023, PostgreSQL Global Development Group38 * Portions Copyright (c) 1994, Regents of the University of California39 *40 * src/include/utils/expandeddatum.h41 *42 *-------------------------------------------------------------------------43 */44#ifndef EXPANDEDDATUM_H45#define EXPANDEDDATUM_H46 47#include "varatt.h"48 49/* Size of an EXTERNAL datum that contains a pointer to an expanded object */50#define EXPANDED_POINTER_SIZE (VARHDRSZ_EXTERNAL + sizeof(varatt_expanded))51 52/*53 * "Methods" that must be provided for any expanded object.54 *55 * get_flat_size: compute space needed for flattened representation (total,56 * including header).57 *58 * flatten_into: construct flattened representation in the caller-allocated59 * space at *result, of size allocated_size (which will always be the result60 * of a preceding get_flat_size call; it's passed for cross-checking).61 *62 * The flattened representation must be a valid in-line, non-compressed,63 * 4-byte-header varlena object.64 *65 * Note: construction of a heap tuple from an expanded datum calls66 * get_flat_size twice, so it's worthwhile to make sure that that doesn't67 * incur too much overhead.68 */69typedef Size (*EOM_get_flat_size_method) (ExpandedObjectHeader *eohptr);70typedef void (*EOM_flatten_into_method) (ExpandedObjectHeader *eohptr,71										 void *result, Size allocated_size);72 73/* Struct of function pointers for an expanded object's methods */74typedef struct ExpandedObjectMethods75{76	EOM_get_flat_size_method get_flat_size;77	EOM_flatten_into_method flatten_into;78} ExpandedObjectMethods;79 80/*81 * Every expanded object must contain this header; typically the header82 * is embedded in some larger struct that adds type-specific fields.83 *84 * It is presumed that the header object and all subsidiary data are stored85 * in eoh_context, so that the object can be freed by deleting that context,86 * or its storage lifespan can be altered by reparenting the context.87 * (In principle the object could own additional resources, such as malloc'd88 * storage, and use a memory context reset callback to free them upon reset or89 * deletion of eoh_context.)90 *91 * We set up two TOAST pointers within the standard header, one read-write92 * and one read-only.  This allows functions to return either kind of pointer93 * without making an additional allocation, and in particular without worrying94 * whether a separately palloc'd object would have sufficient lifespan.95 * But note that these pointers are just a convenience; a pointer object96 * appearing somewhere else would still be legal.97 *98 * The typedef declaration for this appears in postgres.h.99 */100struct ExpandedObjectHeader101{102	/* Phony varlena header */103	int32		vl_len_;		/* always EOH_HEADER_MAGIC, see below */104 105	/* Pointer to methods required for object type */106	const ExpandedObjectMethods *eoh_methods;107 108	/* Memory context containing this header and subsidiary data */109	MemoryContext eoh_context;110 111	/* Standard R/W TOAST pointer for this object is kept here */112	char		eoh_rw_ptr[EXPANDED_POINTER_SIZE];113 114	/* Standard R/O TOAST pointer for this object is kept here */115	char		eoh_ro_ptr[EXPANDED_POINTER_SIZE];116};117 118/*119 * Particularly for read-only functions, it is handy to be able to work with120 * either regular "flat" varlena inputs or expanded inputs of the same data121 * type.  To allow determining which case an argument-fetching function has122 * returned, the first int32 of an ExpandedObjectHeader always contains -1123 * (EOH_HEADER_MAGIC to the code).  This works since no 4-byte-header varlena124 * could have that as its first 4 bytes.  Caution: we could not reliably tell125 * the difference between an ExpandedObjectHeader and a short-header object126 * with this trick.  However, it works fine if the argument fetching code127 * always returns either a 4-byte-header flat object or an expanded object.128 */129#define EOH_HEADER_MAGIC (-1)130#define VARATT_IS_EXPANDED_HEADER(PTR) \131	(((varattrib_4b *) (PTR))->va_4byte.va_header == (uint32) EOH_HEADER_MAGIC)132 133/*134 * Generic support functions for expanded objects.135 * (More of these might be worth inlining later.)136 */137 138static inline Datum139EOHPGetRWDatum(const struct ExpandedObjectHeader *eohptr)140{141	return PointerGetDatum(eohptr->eoh_rw_ptr);142}143 144static inline Datum145EOHPGetRODatum(const struct ExpandedObjectHeader *eohptr)146{147	return PointerGetDatum(eohptr->eoh_ro_ptr);148}149 150/* Does the Datum represent a writable expanded object? */151#define DatumIsReadWriteExpandedObject(d, isnull, typlen) \152	(((isnull) || (typlen) != -1) ? false : \153	 VARATT_IS_EXTERNAL_EXPANDED_RW(DatumGetPointer(d)))154 155#define MakeExpandedObjectReadOnly(d, isnull, typlen) \156	(((isnull) || (typlen) != -1) ? (d) : \157	 MakeExpandedObjectReadOnlyInternal(d))158 159extern ExpandedObjectHeader *DatumGetEOHP(Datum d);160extern void EOH_init_header(ExpandedObjectHeader *eohptr,161							const ExpandedObjectMethods *methods,162							MemoryContext obj_context);163extern Size EOH_get_flat_size(ExpandedObjectHeader *eohptr);164extern void EOH_flatten_into(ExpandedObjectHeader *eohptr,165							 void *result, Size allocated_size);166extern Datum MakeExpandedObjectReadOnlyInternal(Datum d);167extern Datum TransferExpandedObject(Datum d, MemoryContext new_parent);168extern void DeleteExpandedObject(Datum d);169 170#endif							/* EXPANDEDDATUM_H */171