Approaching the current documentation from a position of ignorance, I

find it ambiguous.  I propose something along the lines of the
following patch to clarify it.  Thanks.

(Alternatively, perhaps the code could maintain a count of nested
calls to SPI_connect/SPI_finish.  But I didn't try to write that
patch.)

Ian Lance Taylor

diff --git a/doc/src/sgml/spi.sgml b/doc/src/sgml/spi.sgml
index c16033033a128f84d17c01fe156a8e072fc882fc..e70e44479ffedf0f0ac3bdc00fd041e7c95d2135 100644 (file)
--- a/doc/src/sgml/spi.sgml
+++ b/doc/src/sgml/spi.sgml
@@ -34,10 +34,11 @@ using SPI.
 
 
 
-SPI procedures are always called by some (upper) 
-Executor and the SPI
-manager uses the Executor to run your queries. Other procedures may be
-called by the Executor running queries from your procedure.
+Procedures which use SPI are called by the
+Executor.  The SPI calls recursively invoke the
+Executor in turn to run queries.  When the Executor is invoked
+recursively, it may itself call procedures which may make
+SPI calls.
 
 
 
@@ -146,12 +147,17 @@ Return status
    utility SPI functions may be called from un-connected procedures.
 
 
-   You may get SPI_ERROR_CONNECT error if SPI_connect is
-   called from an already connected procedure - e.g. if you directly call one
-   procedure from another connected one.  Actually, while the child procedure
-   will be able to use SPI, your parent procedure will not be able to continue
-   to use SPI after the child returns (if SPI_finish is called by the child).
-   It's bad practice.
+   If your procedure is already connected,
+   SPI_connect will return an
+   SPI_ERROR_CONNECT error.  Note that this
+   may happen if a procedure which has called
+   SPI_connect directly calls another procedure
+   which itself calls SPI_connect.  While
+   recursive calls to the SPI manager are permitted
+   when an SPI query invokes another function which
+   uses SPI, directly nested calls to
+   SPI_connect and
+   SPI_finish are forbidden.