From fec0778c8098cebec2d5cb3674ac7151d8d95638 Mon Sep 17 00:00:00 2001
From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Wed, 17 Jul 2019 14:55:13 -0400
Subject: [PATCH] Clarify the distinction between public and private
SPITupleTable fields.
The fields that we consider public are "tupdesc" and "vals", which
historically are in the middle of the struct. Move them to the front
(this should be perfectly safe to do in HEAD) and add comments to make
it quite clear which fields are public or not.
Also adjust spi.sgml's documentation of the struct to match.
That doc had bit-rotted somewhat, as it was missing some fields.
(Arguably we should just remove all the private fields from the docs,
but for now I refrained.)
Daniel Gustafsson, reviewed by Fabien Coelho
Discussion: https://postgr.es/m/0D19F836-B743-4340-B6A2-F148CA3DD1F0@yesql.se
---
doc/src/sgml/spi.sgml | 21 +++++++++++++--------
src/include/executor/spi.h | 7 +++++--
2 files changed, 18 insertions(+), 10 deletions(-)
diff --git a/doc/src/sgml/spi.sgml b/doc/src/sgml/spi.sgml
index 66eced6c949..e39f99fbb32 100644
--- a/doc/src/sgml/spi.sgml
+++ b/doc/src/sgml/spi.sgml
@@ -318,21 +318,26 @@ SPI_execute("INSERT INTO foo SELECT * FROM bar RETURNING *", false, 5);
The structure <structname>SPITupleTable</structname> is defined
thus:
<programlisting>
-typedef struct
+typedef struct SPITupleTable
{
+ /* Public members */
+ TupleDesc tupdesc; /* tuple descriptor */
+ HeapTuple *vals; /* array of tuples */
+
+ /* Private members, not intended for external callers */
MemoryContext tuptabcxt; /* memory context of result table */
- uint64 alloced; /* number of alloced vals */
- uint64 free; /* number of free vals */
- TupleDesc tupdesc; /* row descriptor */
- HeapTuple *vals; /* rows */
+ uint64 alloced; /* # of alloced vals */
+ uint64 free; /* # of free vals */
+ slist_node next; /* link for internal bookkeeping */
+ SubTransactionId subid; /* subxact in which tuptable was created */
} SPITupleTable;
</programlisting>
+ <structfield>vals</structfield> and <structfield>tupdesc</structfield> can
+ be used by SPI callers, the remaining fields are internal.
<structfield>vals</structfield> is an array of pointers to rows. (The number
of valid entries is given by <varname>SPI_processed</varname>.)
<structfield>tupdesc</structfield> is a row descriptor which you can pass to
- SPI functions dealing with rows. <structfield>tuptabcxt</structfield>,
- <structfield>alloced</structfield>, and <structfield>free</structfield> are internal
- fields not intended for use by SPI callers.
+ SPI functions dealing with rows.
</para>
<para>
diff --git a/src/include/executor/spi.h b/src/include/executor/spi.h
index 7bf361874d2..af4f8c875c7 100644
--- a/src/include/executor/spi.h
+++ b/src/include/executor/spi.h
@@ -21,11 +21,14 @@
typedef struct SPITupleTable
{
+ /* Public members */
+ TupleDesc tupdesc; /* tuple descriptor */
+ HeapTuple *vals; /* array of tuples */
+
+ /* Private members, not intended for external callers */
MemoryContext tuptabcxt; /* memory context of result table */
uint64 alloced; /* # of alloced vals */
uint64 free; /* # of free vals */
- TupleDesc tupdesc; /* tuple descriptor */
- HeapTuple *vals; /* tuples */
slist_node next; /* link for internal bookkeeping */
SubTransactionId subid; /* subxact in which tuptable was created */
} SPITupleTable;