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

diff --git a/doc/src/sgml/spi.sgml b/doc/src/sgml/spi.sgml
index 66eced6c949087b4ebf68ddad66060f1ae292592..e39f99fbb325f969ca2ce49ace348d4869571726 100644 (file)
--- 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 7bf361874d2069c848c4e8e5e5a66410c65f8f66..af4f8c875c759079690f41dd7ef983d29a523da6 100644 (file)
--- 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;