Redesign query-snapshot timing so that volatile functions in READ COMMITTED

mode see a fresh snapshot for each command in the function, rather than
using the latest interactive command's snapshot.  Also, suppress fresh
snapshots as well as CommandCounterIncrement inside STABLE and IMMUTABLE
functions, instead using the snapshot taken for the most closely nested
regular query.  (This behavior is only sane for read-only functions, so
the patch also enforces that such functions contain only SELECT commands.)
As per my proposal of 6-Sep-2004; I note that I floated essentially the
same proposal on 19-Jun-2002, but that discussion tailed off without any
action.  Since 8.0 seems like the right place to be taking possibly
nontrivial backwards compatibility hits, let's get it done now.

Author: tglsfdc

contrib/tablefunc/tablefunc.c

@@ -386,7 +386,7 @@ crosstab(PG_FUNCTION_ARGS)
 			elog(ERROR, "crosstab: SPI_connect returned %d", ret);
 
 		/* Retrieve the desired rows */
-		ret = SPI_exec(sql, 0);
+		ret = SPI_execute(sql, true, 0);
 		proc = SPI_processed;
 
 		/* Check for qualifying tuples */
@@ -777,7 +777,7 @@ load_categories_hash(char *cats_sql, MemoryContext per_query_ctx)
 		elog(ERROR, "load_categories_hash: SPI_connect returned %d", ret);
 
 	/* Retrieve the category name rows */
-	ret = SPI_exec(cats_sql, 0);
+	ret = SPI_execute(cats_sql, true, 0);
 	num_categories = proc = SPI_processed;
 
 	/* Check for qualifying tuples */
@@ -855,7 +855,7 @@ get_crosstab_tuplestore(char *sql,
 		elog(ERROR, "get_crosstab_tuplestore: SPI_connect returned %d", ret);
 
 	/* Now retrieve the crosstab source rows */
-	ret = SPI_exec(sql, 0);
+	ret = SPI_execute(sql, true, 0);
 	proc = SPI_processed;
 
 	/* Check for qualifying tuples */
@@ -1376,7 +1376,7 @@ build_tuplestore_recursively(char *key_fld,
 	}
 
 	/* Retrieve the desired rows */
-	ret = SPI_exec(sql->data, 0);
+	ret = SPI_execute(sql->data, true, 0);
 	proc = SPI_processed;
 
 	/* Check for qualifying tuples */

contrib/tsearch2/ts_stat.c

@@ -446,7 +446,7 @@ ts_stat_sql(text *txt, text *ws)
 		/* internal error */
 		elog(ERROR, "SPI_prepare('%s') returns NULL", query);
 
-	if ((portal = SPI_cursor_open(NULL, plan, NULL, NULL)) == NULL)
+	if ((portal = SPI_cursor_open(NULL, plan, NULL, NULL, false)) == NULL)
 		/* internal error */
 		elog(ERROR, "SPI_cursor_open('%s') returns NULL", query);
 

doc/src/sgml/plpython.sgml

@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/plpython.sgml,v 1.23 2004/05/16 23:22:07 neilc Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/plpython.sgml,v 1.24 2004/09/13 20:05:18 tgl Exp $ -->
 
 <chapter id="plpython">
  <title>PL/Python - Python Procedural Language</title>
@@ -175,7 +175,7 @@ def __plpython_procedure_myfunc_23456():
    row number and column name.  It has these additional methods:
    <function>nrows</function> which returns the number of rows
    returned by the query, and <function>status</function> which is the
-   <function>SPI_exec()</function> return value.  The result object
+   <function>SPI_execute()</function> return value.  The result object
    can be modified.
   </para>
 

doc/src/sgml/ref/create_function.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/create_function.sgml,v 1.58 2004/07/11 23:23:43 momjian Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/create_function.sgml,v 1.59 2004/09/13 20:05:38 tgl Exp $
 -->
 
 <refentry id="SQL-CREATEFUNCTION">
@@ -172,7 +172,7 @@ CREATE [ OR REPLACE ] FUNCTION <replaceable class="parameter">name</replaceable>
        These attributes inform the system whether it is safe to
        replace multiple evaluations of the function with a single
        evaluation, for run-time optimization.  At most one choice
-       should be specified.  If none of these appear,
+       may be specified.  If none of these appear,
        <literal>VOLATILE</literal> is the default assumption.
       </para>
 
@@ -206,6 +206,10 @@ CREATE [ OR REPLACE ] FUNCTION <replaceable class="parameter">name</replaceable>
        to prevent calls from being optimized away; an example is
        <literal>setval()</>.
       </para>
+
+      <para>
+       For additional details see <xref linkend="xfunc-volatility">.
+      </para>
      </listitem>
     </varlistentry>
 

doc/src/sgml/release.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/release.sgml,v 1.295 2004/09/10 18:39:54 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/release.sgml,v 1.296 2004/09/13 20:05:18 tgl Exp $
 -->
 
 <appendix id="release">
@@ -337,6 +337,26 @@ $PostgreSQL: pgsql/doc/src/sgml/release.sgml,v 1.295 2004/09/10 18:39:54 tgl Exp
       </para>
      </listitem>
 
+     <listitem>
+      <para>
+       In <literal>READ COMMITTED</> serialization mode, volatile functions
+       now see the results of concurrent transactions committed up to the
+       beginning of each statement within the function, rather than up to the
+       beginning of the interactive command that called the function.
+      </para>
+     </listitem>
+
+     <listitem>
+      <para>
+       Functions declared <literal>STABLE</> or <literal>IMMUTABLE</> always
+       use the snapshot of the calling query, and therefore do not see the
+       effects of actions taken after the calling query starts, whether in
+       their own transaction or other transactions.  Such a function must be
+       read-only, too, meaning that it cannot use any SQL commands other than
+       <command>SELECT</>.
+      </para>
+     </listitem>
+
      <listitem>
       <para>
        Non-deferred AFTER triggers are now fired immediately after completion
@@ -1434,6 +1454,26 @@ $PostgreSQL: pgsql/doc/src/sgml/release.sgml,v 1.295 2004/09/10 18:39:54 tgl Exp
    <title>Server-Side Language Changes</title>
    <itemizedlist>
 
+    <listitem>
+     <para>
+      In <literal>READ COMMITTED</> serialization mode, volatile functions
+      now see the results of concurrent transactions committed up to the
+      beginning of each statement within the function, rather than up to the
+      beginning of the interactive command that called the function.
+     </para>
+    </listitem>
+
+    <listitem>
+     <para>
+      Functions declared <literal>STABLE</> or <literal>IMMUTABLE</> always
+      use the snapshot of the calling query, and therefore do not see the
+      effects of actions taken after the calling query starts, whether in
+      their own transaction or other transactions.  Such a function must be
+      read-only, too, meaning that it cannot use any SQL commands other than
+      <command>SELECT</>.
+     </para>
+    </listitem>
+
     <listitem>
      <para>
       Non-deferred AFTER triggers are now fired immediately after completion