rdelaage/postgresql
1
0
Fork 0
mirror of https://git.postgresql.org/git/postgresql.git synced 2024-09-06 14:09:21 +02:00
Code Issues Packages Projects Releases Wiki Activity
3e23b68dac
postgresql/src/include/postgres.h
Tom Lane 3e23b68dac Support varlena fields with single-byte headers and unaligned storage. 
This commit breaks any code that assumes that the mere act of forming a tuple
(without writing it to disk) does not "toast" any fields.  While all available
regression tests pass, I'm not totally sure that we've fixed every nook and
cranny, especially in contrib.

Greg Stark with some help from Tom Lane
2007-04-06 04:21:44 +00:00

718 lines
21 KiB
C
Raw Blame History

/*-------------------------------------------------------------------------
*
* postgres.h
* Primary include file for PostgreSQL server .c files
*
* This should be the first file included by PostgreSQL backend modules.
* Client-side code should include postgres_fe.h instead.
*
*
* Portions Copyright (c) 1996-2007, PostgreSQL Global Development Group
* Portions Copyright (c) 1995, Regents of the University of California
*
* $PostgreSQL: pgsql/src/include/postgres.h,v 1.79 2007/04/06 04:21:44 tgl Exp $
*
*-------------------------------------------------------------------------
*/
/*
*----------------------------------------------------------------
* TABLE OF CONTENTS
*
* When adding stuff to this file, please try to put stuff
* into the relevant section, or add new sections as appropriate.
*
* section description
* ------- ------------------------------------------------
* 1) variable-length datatypes (TOAST support)
* 2) datum type + support macros
* 3) exception handling definitions
* 4) genbki macros used by catalog/pg_xxx.h files
*
* NOTES
*
* In general, this file should contain declarations that are widely needed
* in the backend environment, but are of no interest outside the backend.
*
* Simple type definitions live in c.h, where they are shared with
* postgres_fe.h. We do that since those type definitions are needed by
* frontend modules that want to deal with binary data transmission to or
* from the backend. Type definitions in this file should be for
* representations that never escape the backend, such as Datum or
* TOASTed varlena objects.
*
*----------------------------------------------------------------
*/
#ifndef POSTGRES_H
#define POSTGRES_H
#include "c.h"
#include "utils/elog.h"
#include "utils/palloc.h"
/* ----------------------------------------------------------------
* Section 1: variable-length datatypes (TOAST support)
* ----------------------------------------------------------------
*/
/*
* struct varatt_external is a "TOAST pointer", that is, the information
* needed to fetch a stored-out-of-line Datum. The data is compressed
* if and only if va_extsize < va_rawsize - VARHDRSZ. This struct must not
* contain any padding, because we sometimes compare pointers using memcmp.
*
* Note that this information is stored unaligned within actual tuples, so
* you need to memcpy from the tuple into a local struct variable before
* you can look at these fields! (The reason we use memcmp is to avoid
* having to do that just to detect equality of two TOAST pointers...)
*/
struct varatt_external
{
int32 va_rawsize; /* Original data size (includes header) */
int32 va_extsize; /* External saved size (doesn't) */
Oid va_valueid; /* Unique ID of value within TOAST table */
Oid va_toastrelid; /* RelID of TOAST table containing it */
};
/*
* These structs describe the header of a varlena object that may have been
* TOASTed. Generally, don't reference these structs directly, but use the
* macros below.
*
* We use separate structs for the aligned and unaligned cases because the
* compiler might otherwise think it could generate code that assumes
* alignment while touching fields of a 1-byte-header varlena.
*/
typedef union
{
struct /* Normal varlena (4-byte length) */
{
uint32 va_header;
char va_data[1];
} va_4byte;
struct /* Compressed-in-line format */
{
uint32 va_header;
uint32 va_rawsize; /* Original data size (excludes header) */
char va_data[1]; /* Compressed data */
} va_compressed;
} varattrib_4b;
typedef struct
{
uint8 va_header;
char va_data[1]; /* Data or TOAST pointer */
} varattrib_1b;
typedef struct
{
uint8 va_header;
char va_data[sizeof(struct varatt_external)];
} varattrib_pointer;
/*
* Bit layouts for varlena headers on big-endian machines:
*
* 00xxxxxx 4-byte length word, aligned, uncompressed data (up to 1G)
* 01xxxxxx 4-byte length word, aligned, *compressed* data (up to 1G)
* 10000000 1-byte length word, unaligned, TOAST pointer
* 1xxxxxxx 1-byte length word, unaligned, uncompressed data (up to 126b)
*
* Bit layouts for varlena headers on little-endian machines:
*
* xxxxxx00 4-byte length word, aligned, uncompressed data (up to 1G)
* xxxxxx10 4-byte length word, aligned, *compressed* data (up to 1G)
* 00000001 1-byte length word, unaligned, TOAST pointer
* xxxxxxx1 1-byte length word, unaligned, uncompressed data (up to 126b)
*
* The "xxx" bits are the length field (which includes itself in all cases).
* In the big-endian case we mask to extract the length, in the little-endian
* case we shift. Note that in both cases the flag bits are in the physically
* first byte. Also, it is not possible for a 1-byte length word to be zero;
* this lets us disambiguate alignment padding bytes from the start of an
* unaligned datum. (We now *require* pad bytes to be filled with zero!)
*/
/*
* Endian-dependent macros. These are considered internal --- use the
* external macros below instead of using these directly.
*
* Note: IS_1B is true for external toast records but VARSIZE_1B will return 0
* for such records. Hence you should usually check for IS_EXTERNAL before
* checking for IS_1B.
*/
#ifdef WORDS_BIGENDIAN
#define VARATT_IS_4B(PTR) \
((((varattrib_1b *) (PTR))->va_header & 0x80) == 0x00)
#define VARATT_IS_4B_U(PTR) \
((((varattrib_1b *) (PTR))->va_header & 0xC0) == 0x00)
#define VARATT_IS_4B_C(PTR) \
((((varattrib_1b *) (PTR))->va_header & 0xC0) == 0x40)
#define VARATT_IS_1B(PTR) \
((((varattrib_1b *) (PTR))->va_header & 0x80) == 0x80)
#define VARATT_IS_1B_E(PTR) \
((((varattrib_1b *) (PTR))->va_header) == 0x80)
#define VARATT_NOT_PAD_BYTE(PTR) \
(*((uint8 *) (PTR)) != 0)
/* VARSIZE_4B() should only be used on known-aligned data */
#define VARSIZE_4B(PTR) \
(((varattrib_4b *) (PTR))->va_4byte.va_header & 0x3FFFFFFF)
#define VARSIZE_1B(PTR) \
(((varattrib_1b *) (PTR))->va_header & 0x7F)
/* Currently there is only one size of toast pointer, but someday maybe not */
#define VARSIZE_1B_E(PTR) \
(sizeof(varattrib_pointer))
#define SET_VARSIZE_4B(PTR,len) \
(((varattrib_4b *) (PTR))->va_4byte.va_header = (len) & 0x3FFFFFFF)
#define SET_VARSIZE_4B_C(PTR,len) \
(((varattrib_4b *) (PTR))->va_4byte.va_header = ((len) & 0x3FFFFFFF) | 0x40000000)
#define SET_VARSIZE_1B(PTR,len) \
(((varattrib_1b *) (PTR))->va_header = (len) | 0x80)
#define SET_VARSIZE_1B_E(PTR) \
(((varattrib_1b *) (PTR))->va_header = 0x80)
#else /* !WORDS_BIGENDIAN */
#define VARATT_IS_4B(PTR) \
((((varattrib_1b *) (PTR))->va_header & 0x01) == 0x00)
#define VARATT_IS_4B_U(PTR) \
((((varattrib_1b *) (PTR))->va_header & 0x03) == 0x00)
#define VARATT_IS_4B_C(PTR) \
((((varattrib_1b *) (PTR))->va_header & 0x03) == 0x02)
#define VARATT_IS_1B(PTR) \
((((varattrib_1b *) (PTR))->va_header & 0x01) == 0x01)
#define VARATT_IS_1B_E(PTR) \
((((varattrib_1b *) (PTR))->va_header) == 0x01)
#define VARATT_NOT_PAD_BYTE(PTR) \
(*((uint8 *) (PTR)) != 0)
/* VARSIZE_4B() should only be used on known-aligned data */
#define VARSIZE_4B(PTR) \
((((varattrib_4b *) (PTR))->va_4byte.va_header >> 2) & 0x3FFFFFFF)
#define VARSIZE_1B(PTR) \
((((varattrib_1b *) (PTR))->va_header >> 1) & 0x7F)
/* Currently there is only one size of toast pointer, but someday maybe not */
#define VARSIZE_1B_E(PTR) \
(sizeof(varattrib_pointer))
#define SET_VARSIZE_4B(PTR,len) \
(((varattrib_4b *) (PTR))->va_4byte.va_header = (((uint32) (len)) << 2))
#define SET_VARSIZE_4B_C(PTR,len) \
(((varattrib_4b *) (PTR))->va_4byte.va_header = (((uint32) (len)) << 2) | 0x02)
#define SET_VARSIZE_1B(PTR,len) \
(((varattrib_1b *) (PTR))->va_header = (((uint8) (len)) << 1) | 0x01)
#define SET_VARSIZE_1B_E(PTR) \
(((varattrib_1b *) (PTR))->va_header = 0x01)
#endif /* WORDS_BIGENDIAN */
#define VARHDRSZ_SHORT 1
#define VARATT_SHORT_MAX 0x7F
#define VARATT_CAN_MAKE_SHORT(PTR) \
(VARATT_IS_4B_U(PTR) && \
(VARSIZE(PTR) - VARHDRSZ + VARHDRSZ_SHORT) <= VARATT_SHORT_MAX)
#define VARATT_CONVERTED_SHORT_SIZE(PTR) \
(VARSIZE(PTR) - VARHDRSZ + VARHDRSZ_SHORT)
#define VARDATA_4B(PTR) (((varattrib_4b *) (PTR))->va_4byte.va_data)
#define VARDATA_4B_C(PTR) (((varattrib_4b *) (PTR))->va_compressed.va_data)
#define VARDATA_1B(PTR) (((varattrib_1b *) (PTR))->va_data)
#define VARRAWSIZE_4B_C(PTR) \
(((varattrib_4b *) (PTR))->va_compressed.va_rawsize)
/* Externally visible macros */
/*
* VARDATA, VARSIZE, and SET_VARSIZE are the recommended API for most code
* for varlena datatypes. Note that they only work on untoasted,
* 4-byte-header Datums!
*
* Code that wants to use 1-byte-header values without detoasting should
* use VARSIZE_ANY/VARSIZE_ANY_EXHDR/VARDATA_ANY. The other macros here
* should usually be used only by tuple assembly/disassembly code and
* code that specifically wants to work with still-toasted Datums.
*/
#define VARDATA(PTR) VARDATA_4B(PTR)
#define VARSIZE(PTR) VARSIZE_4B(PTR)
#define VARSIZE_SHORT(PTR) VARSIZE_1B(PTR)
#define VARDATA_SHORT(PTR) VARDATA_1B(PTR)
#define VARSIZE_EXTERNAL(PTR) VARSIZE_1B_E(PTR)
#define VARATT_IS_COMPRESSED(PTR) VARATT_IS_4B_C(PTR)
#define VARATT_IS_EXTERNAL(PTR) VARATT_IS_1B_E(PTR)
#define VARATT_IS_SHORT(PTR) VARATT_IS_1B(PTR)
#define VARATT_IS_EXTENDED(PTR) (!VARATT_IS_4B_U(PTR))
#define SET_VARSIZE(PTR, len) SET_VARSIZE_4B(PTR, len)
#define SET_VARSIZE_SHORT(PTR, len) SET_VARSIZE_1B(PTR, len)
#define SET_VARSIZE_COMPRESSED(PTR, len) SET_VARSIZE_4B_C(PTR, len)
#define SET_VARSIZE_EXTERNAL(PTR) SET_VARSIZE_1B_E(PTR)
#define VARSIZE_ANY(PTR) \
(VARATT_IS_1B_E(PTR) ? VARSIZE_1B_E(PTR) : \
(VARATT_IS_1B(PTR) ? VARSIZE_1B(PTR) : \
VARSIZE_4B(PTR)))
#define VARSIZE_ANY_EXHDR(PTR) \
(VARATT_IS_1B_E(PTR) ? VARSIZE_1B_E(PTR)-1 : \
(VARATT_IS_1B(PTR) ? VARSIZE_1B(PTR)-1 : \
VARSIZE_4B(PTR)-4))
/* caution: this will not work on an external or compressed-in-line Datum */
#define VARDATA_ANY(PTR) \
(VARATT_IS_1B(PTR) ? VARDATA_1B(PTR) : VARDATA_4B(PTR))
/* ----------------------------------------------------------------
* Section 2: datum type + support macros
* ----------------------------------------------------------------
*/
/*
* Port Notes:
* Postgres makes the following assumption about machines:
*
* sizeof(Datum) == sizeof(long) >= sizeof(void *) >= 4
*
* Postgres also assumes that
*
* sizeof(char) == 1
*
* and that
*
* sizeof(short) == 2
*
* When a type narrower than Datum is stored in a Datum, we place it in the
* low-order bits and are careful that the DatumGetXXX macro for it discards
* the unused high-order bits (as opposed to, say, assuming they are zero).
* This is needed to support old-style user-defined functions, since depending
* on architecture and compiler, the return value of a function returning char
* or short may contain garbage when called as if it returned Datum.
*/
typedef unsigned long Datum; /* XXX sizeof(long) >= sizeof(void *) */
#define SIZEOF_DATUM SIZEOF_UNSIGNED_LONG
typedef Datum *DatumPtr;
#define GET_1_BYTE(datum) (((Datum) (datum)) & 0x000000ff)
#define GET_2_BYTES(datum) (((Datum) (datum)) & 0x0000ffff)
#define GET_4_BYTES(datum) (((Datum) (datum)) & 0xffffffff)
#define SET_1_BYTE(value) (((Datum) (value)) & 0x000000ff)
#define SET_2_BYTES(value) (((Datum) (value)) & 0x0000ffff)
#define SET_4_BYTES(value) (((Datum) (value)) & 0xffffffff)
/*
* DatumGetBool
* Returns boolean value of a datum.
*
* Note: any nonzero value will be considered TRUE, but we ignore bits to
* the left of the width of bool, per comment above.
*/
#define DatumGetBool(X) ((bool) (((bool) (X)) != 0))
/*
* BoolGetDatum
* Returns datum representation for a boolean.
*
* Note: any nonzero value will be considered TRUE.
*/
#define BoolGetDatum(X) ((Datum) ((X) ? 1 : 0))
/*
* DatumGetChar
* Returns character value of a datum.
*/
#define DatumGetChar(X) ((char) GET_1_BYTE(X))
/*
* CharGetDatum
* Returns datum representation for a character.
*/
#define CharGetDatum(X) ((Datum) SET_1_BYTE(X))
/*
* Int8GetDatum
* Returns datum representation for an 8-bit integer.
*/
#define Int8GetDatum(X) ((Datum) SET_1_BYTE(X))
/*
* DatumGetUInt8
* Returns 8-bit unsigned integer value of a datum.
*/
#define DatumGetUInt8(X) ((uint8) GET_1_BYTE(X))
/*
* UInt8GetDatum
* Returns datum representation for an 8-bit unsigned integer.
*/
#define UInt8GetDatum(X) ((Datum) SET_1_BYTE(X))
/*
* DatumGetInt16
* Returns 16-bit integer value of a datum.
*/
#define DatumGetInt16(X) ((int16) GET_2_BYTES(X))
/*
* Int16GetDatum
* Returns datum representation for a 16-bit integer.
*/
#define Int16GetDatum(X) ((Datum) SET_2_BYTES(X))
/*
* DatumGetUInt16
* Returns 16-bit unsigned integer value of a datum.
*/
#define DatumGetUInt16(X) ((uint16) GET_2_BYTES(X))
/*
* UInt16GetDatum
* Returns datum representation for a 16-bit unsigned integer.
*/
#define UInt16GetDatum(X) ((Datum) SET_2_BYTES(X))
/*
* DatumGetInt32
* Returns 32-bit integer value of a datum.
*/
#define DatumGetInt32(X) ((int32) GET_4_BYTES(X))
/*
* Int32GetDatum
* Returns datum representation for a 32-bit integer.
*/
#define Int32GetDatum(X) ((Datum) SET_4_BYTES(X))
/*
* DatumGetUInt32
* Returns 32-bit unsigned integer value of a datum.
*/
#define DatumGetUInt32(X) ((uint32) GET_4_BYTES(X))
/*
* UInt32GetDatum
* Returns datum representation for a 32-bit unsigned integer.
*/
#define UInt32GetDatum(X) ((Datum) SET_4_BYTES(X))
/*
* DatumGetObjectId
* Returns object identifier value of a datum.
*/
#define DatumGetObjectId(X) ((Oid) GET_4_BYTES(X))
/*
* ObjectIdGetDatum
* Returns datum representation for an object identifier.
*/
#define ObjectIdGetDatum(X) ((Datum) SET_4_BYTES(X))
/*
* DatumGetTransactionId
* Returns transaction identifier value of a datum.
*/
#define DatumGetTransactionId(X) ((TransactionId) GET_4_BYTES(X))
/*
* TransactionIdGetDatum
* Returns datum representation for a transaction identifier.
*/
#define TransactionIdGetDatum(X) ((Datum) SET_4_BYTES((X)))
/*
* DatumGetCommandId
* Returns command identifier value of a datum.
*/
#define DatumGetCommandId(X) ((CommandId) GET_4_BYTES(X))
/*
* CommandIdGetDatum
* Returns datum representation for a command identifier.
*/
#define CommandIdGetDatum(X) ((Datum) SET_4_BYTES(X))
/*
* DatumGetPointer
* Returns pointer value of a datum.
*/
#define DatumGetPointer(X) ((Pointer) (X))
/*
* PointerGetDatum
* Returns datum representation for a pointer.
*/
#define PointerGetDatum(X) ((Datum) (X))
/*
* DatumGetCString
* Returns C string (null-terminated string) value of a datum.
*
* Note: C string is not a full-fledged Postgres type at present,
* but type input functions use this conversion for their inputs.
*/
#define DatumGetCString(X) ((char *) DatumGetPointer(X))
/*
* CStringGetDatum
* Returns datum representation for a C string (null-terminated string).
*
* Note: C string is not a full-fledged Postgres type at present,
* but type output functions use this conversion for their outputs.
* Note: CString is pass-by-reference; caller must ensure the pointed-to
* value has adequate lifetime.
*/
#define CStringGetDatum(X) PointerGetDatum(X)
/*
* DatumGetName
* Returns name value of a datum.
*/
#define DatumGetName(X) ((Name) DatumGetPointer(X))
/*
* NameGetDatum
* Returns datum representation for a name.
*
* Note: Name is pass-by-reference; caller must ensure the pointed-to
* value has adequate lifetime.
*/
#define NameGetDatum(X) PointerGetDatum(X)
/*
* DatumGetInt64
* Returns 64-bit integer value of a datum.
*
* Note: this macro hides the fact that int64 is currently a
* pass-by-reference type. Someday it may be pass-by-value,
* at least on some platforms.
*/
#define DatumGetInt64(X) (* ((int64 *) DatumGetPointer(X)))
/*
* Int64GetDatum
* Returns datum representation for a 64-bit integer.
*
* Note: this routine returns a reference to palloc'd space.
*/
extern Datum Int64GetDatum(int64 X);
/*
* DatumGetFloat4
* Returns 4-byte floating point value of a datum.
*
* Note: this macro hides the fact that float4 is currently a
* pass-by-reference type. Someday it may be pass-by-value.
*/
#define DatumGetFloat4(X) (* ((float4 *) DatumGetPointer(X)))
/*
* Float4GetDatum
* Returns datum representation for a 4-byte floating point number.
*
* Note: this routine returns a reference to palloc'd space.
*/
extern Datum Float4GetDatum(float4 X);
/*
* DatumGetFloat8
* Returns 8-byte floating point value of a datum.
*
* Note: this macro hides the fact that float8 is currently a
* pass-by-reference type. Someday it may be pass-by-value,
* at least on some platforms.
*/
#define DatumGetFloat8(X) (* ((float8 *) DatumGetPointer(X)))
/*
* Float8GetDatum
* Returns datum representation for an 8-byte floating point number.
*
* Note: this routine returns a reference to palloc'd space.
*/
extern Datum Float8GetDatum(float8 X);
/*
* DatumGetFloat32
* Returns 32-bit floating point value of a datum.
* This is really a pointer, of course.
*
* XXX: this macro is now deprecated in favor of DatumGetFloat4.
* It will eventually go away.
*/
#define DatumGetFloat32(X) ((float32) DatumGetPointer(X))
/*
* Float32GetDatum
* Returns datum representation for a 32-bit floating point number.
* This is really a pointer, of course.
*
* XXX: this macro is now deprecated in favor of Float4GetDatum.
* It will eventually go away.
*/
#define Float32GetDatum(X) PointerGetDatum(X)
/*
* DatumGetFloat64
* Returns 64-bit floating point value of a datum.
* This is really a pointer, of course.
*
* XXX: this macro is now deprecated in favor of DatumGetFloat8.
* It will eventually go away.
*/
#define DatumGetFloat64(X) ((float64) DatumGetPointer(X))
/*
* Float64GetDatum
* Returns datum representation for a 64-bit floating point number.
* This is really a pointer, of course.
*
* XXX: this macro is now deprecated in favor of Float8GetDatum.
* It will eventually go away.
*/
#define Float64GetDatum(X) PointerGetDatum(X)
/*
* Int64GetDatumFast
* Float4GetDatumFast
* Float8GetDatumFast
*
* These macros are intended to allow writing code that does not depend on
* whether int64, float4, float8 are pass-by-reference types, while not
* sacrificing performance when they are. The argument must be a variable
* that will exist and have the same value for as long as the Datum is needed.
* In the pass-by-ref case, the address of the variable is taken to use as
* the Datum. In the pass-by-val case, these will be the same as the non-Fast
* macros.
*/
#define Int64GetDatumFast(X) PointerGetDatum(&(X))
#define Float4GetDatumFast(X) PointerGetDatum(&(X))
#define Float8GetDatumFast(X) PointerGetDatum(&(X))
/* ----------------------------------------------------------------
* Section 3: exception handling definitions
* Assert, Trap, etc macros
* ----------------------------------------------------------------
*/
extern DLLIMPORT bool assert_enabled;
/*
* USE_ASSERT_CHECKING, if defined, turns on all the assertions.
* - plai 9/5/90
*
* It should _NOT_ be defined in releases or in benchmark copies
*/
/*
* Trap
* Generates an exception if the given condition is true.
*/
#define Trap(condition, errorType) \
do { \
if ((assert_enabled) && (condition)) \
ExceptionalCondition(CppAsString(condition), (errorType), \
__FILE__, __LINE__); \
} while (0)
/*
* TrapMacro is the same as Trap but it's intended for use in macros:
*
* #define foo(x) (AssertMacro(x != 0) && bar(x))
*
* Isn't CPP fun?
*/
#define TrapMacro(condition, errorType) \
((bool) ((! assert_enabled) || ! (condition) || \
(ExceptionalCondition(CppAsString(condition), (errorType), \
__FILE__, __LINE__))))
#ifndef USE_ASSERT_CHECKING
#define Assert(condition)
#define AssertMacro(condition) ((void)true)
#define AssertArg(condition)
#define AssertState(condition)
#else
#define Assert(condition) \
Trap(!(condition), "FailedAssertion")
#define AssertMacro(condition) \
((void) TrapMacro(!(condition), "FailedAssertion"))
#define AssertArg(condition) \
Trap(!(condition), "BadArgument")
#define AssertState(condition) \
Trap(!(condition), "BadState")
#endif /* USE_ASSERT_CHECKING */
extern int ExceptionalCondition(char *conditionName, char *errorType,
char *fileName, int lineNumber);
/* ----------------------------------------------------------------
* Section 4: genbki macros used by catalog/pg_xxx.h files
* ----------------------------------------------------------------
*/
#define CATALOG(name,oid) typedef struct CppConcat(FormData_,name)
#define BKI_BOOTSTRAP
#define BKI_SHARED_RELATION
#define BKI_WITHOUT_OIDS
/* these need to expand into some harmless, repeatable declaration */
#define DATA(x) extern int no_such_variable
#define DESCR(x) extern int no_such_variable
#define SHDESCR(x) extern int no_such_variable
typedef int4 aclitem; /* PHONY definition for catalog use only */
#endif /* POSTGRES_H */
Reference in New Issue View Git Blame Copy Permalink