From 178214d2ae46b1b1a67b168b510a224881f60efd Mon Sep 17 00:00:00 2001 From: Bruce Momjian Date: Tue, 15 May 2007 17:39:54 +0000 Subject: [PATCH] Update comments for PG_DETOAST_PACKED and VARDATA_ANY on a structures that require alignment. Add a paragraph to the "User-Defined Types" chapter on using these macros since it seems like they're a hit. Gregory Stark --- doc/src/sgml/xtypes.sgml | 44 ++++++++++++++++++++++++++++------------ src/include/fmgr.h | 9 +++++++- src/include/postgres.h | 9 +++++++- 3 files changed, 47 insertions(+), 15 deletions(-) diff --git a/doc/src/sgml/xtypes.sgml b/doc/src/sgml/xtypes.sgml index e1ec4ea189b..bc84ccd1c4b 100644 --- a/doc/src/sgml/xtypes.sgml +++ b/doc/src/sgml/xtypes.sgml @@ -1,4 +1,4 @@ - + User-Defined Types @@ -237,20 +237,38 @@ CREATE TYPE complex ( TOAST and user-defined types - If the values of your data type might exceed a few hundred bytes in - size (in internal form), you should make the data type - TOAST-able (see ). - To do this, the internal - representation must follow the standard layout for variable-length - data: the first four bytes must be an int32 containing - the total length in bytes of the datum (including itself). The C - functions operating on the data type must be careful to unpack any + If the values of your data type vary in size (in internal form), you should + make the data type TOAST-able (see ). You should do this even if the data are always + too small to be compressed or stored externally because + Postgres can save space on small data using + TOAST as well. + + + + To do this, the internal representation must follow the standard layout for + variable-length data: the first four bytes must be an int32 + which is never accessed directly (customarily named vl_len_). You + must use SET_VARSIZE() to store the size of the datum + in this field and VARSIZE() to retrieve it. The C + functions operating on the data type must always be careful to unpack any toasted values they are handed, by using PG_DETOAST_DATUM. (This detail is customarily hidden by defining type-specific - GETARG macros.) Then, - when running the CREATE TYPE command, specify the - internal length as variable and select the appropriate - storage option. + GETARG_DATATYPE_P macros.) Then, when running the + CREATE TYPE command, specify the internal length as + variable and select the appropriate storage option. + + + + If the alignment is unimportant (either just for a specific function or + because the data type specifies byte alignment anyways) then it's possible + to avoid some of the overhead of PG_DETOAST_DATUM. You can use + PG_DETOAST_DATUM_PACKED instead (customarily hidden by + defining a GETARG_DATATYPE_PP macro) and using the macros + VARSIZE_ANY_EXHDR and VARDATA_ANY macros. + Again, the data returned by these macros is not aligned even if the data + type definition specifies an alignment. If the alignment is important you + must go through the regular PG_DETOAST_DATUM interface. diff --git a/src/include/fmgr.h b/src/include/fmgr.h index 298cd12c775..32cadeb6b54 100644 --- a/src/include/fmgr.h +++ b/src/include/fmgr.h @@ -11,7 +11,7 @@ * Portions Copyright (c) 1996-2007, PostgreSQL Global Development Group * Portions Copyright (c) 1994, Regents of the University of California * - * $PostgreSQL: pgsql/src/include/fmgr.h,v 1.50 2007/04/06 04:21:44 tgl Exp $ + * $PostgreSQL: pgsql/src/include/fmgr.h,v 1.51 2007/05/15 17:39:54 momjian Exp $ * *------------------------------------------------------------------------- */ @@ -158,6 +158,12 @@ extern void fmgr_info_copy(FmgrInfo *dstinfo, FmgrInfo *srcinfo, * The resulting datum can be accessed using VARSIZE_ANY() and VARDATA_ANY() * (beware of multiple evaluations in those macros!) * + * WARNING: It is only safe to use PG_DETOAST_DATUM_UNPACKED() and + * VARDATA_ANY() if you really don't care about the alignment. Either because + * you're working with something like text where the alignment doesn't matter + * or because you're not going to access its constituent parts and just use + * things like memcpy on it anyways. + * * Note: it'd be nice if these could be macros, but I see no way to do that * without evaluating the arguments multiple times, which is NOT acceptable. */ @@ -174,6 +180,7 @@ extern struct varlena *pg_detoast_datum_packed(struct varlena * datum); #define PG_DETOAST_DATUM_SLICE(datum,f,c) \ pg_detoast_datum_slice((struct varlena *) DatumGetPointer(datum), \ (int32) f, (int32) c) +/* WARNING -- unaligned pointer */ #define PG_DETOAST_DATUM_PACKED(datum) \ pg_detoast_datum_packed((struct varlena *) DatumGetPointer(datum)) diff --git a/src/include/postgres.h b/src/include/postgres.h index 27c21e2bcc8..3f65d646312 100644 --- a/src/include/postgres.h +++ b/src/include/postgres.h @@ -10,7 +10,7 @@ * 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.80 2007/05/04 02:01:02 tgl Exp $ + * $PostgreSQL: pgsql/src/include/postgres.h,v 1.81 2007/05/15 17:39:54 momjian Exp $ * *------------------------------------------------------------------------- */ @@ -235,6 +235,12 @@ typedef struct * 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. + * + * WARNING: It is only safe to use VARDATA_ANY() -- typically with + * PG_DETOAST_DATUM_UNPACKED() -- if you really don't care about the alignment. + * Either because you're working with something like text where the alignment + * doesn't matter or because you're not going to access its constituent parts + * and just use things like memcpy on it anyways. */ #define VARDATA(PTR) VARDATA_4B(PTR) #define VARSIZE(PTR) VARSIZE_4B(PTR) @@ -265,6 +271,7 @@ typedef struct VARSIZE_4B(PTR)-4)) /* caution: this will not work on an external or compressed-in-line Datum */ +/* caution: this will return a possibly unaligned pointer */ #define VARDATA_ANY(PTR) \ (VARATT_IS_1B(PTR) ? VARDATA_1B(PTR) : VARDATA_4B(PTR)) -- 2.30.2