diff options
Diffstat (limited to 'doc/src')
| -rw-r--r-- | doc/src/sgml/spi.sgml | 165 |
1 files changed, 111 insertions, 54 deletions
diff --git a/doc/src/sgml/spi.sgml b/doc/src/sgml/spi.sgml index f5e0a35da06..d8c121f5f35 100644 --- a/doc/src/sgml/spi.sgml +++ b/doc/src/sgml/spi.sgml @@ -1722,25 +1722,23 @@ int SPI_execute_plan(SPIPlanPtr <parameter>plan</parameter>, Datum * <parameter> <!-- *********************************************** --> -<refentry id="spi-spi-execute-plan-with-paramlist"> - <indexterm><primary>SPI_execute_plan_with_paramlist</primary></indexterm> +<refentry id="spi-spi-execute-plan-extended"> + <indexterm><primary>SPI_execute_plan_extended</primary></indexterm> <refmeta> - <refentrytitle>SPI_execute_plan_with_paramlist</refentrytitle> + <refentrytitle>SPI_execute_plan_extended</refentrytitle> <manvolnum>3</manvolnum> </refmeta> <refnamediv> - <refname>SPI_execute_plan_with_paramlist</refname> + <refname>SPI_execute_plan_extended</refname> <refpurpose>execute a statement prepared by <function>SPI_prepare</function></refpurpose> </refnamediv> <refsynopsisdiv> <synopsis> -int SPI_execute_plan_with_paramlist(SPIPlanPtr <parameter>plan</parameter>, - ParamListInfo <parameter>params</parameter>, - bool <parameter>read_only</parameter>, - long <parameter>count</parameter>) +int SPI_execute_plan_extended(SPIPlanPtr <parameter>plan</parameter>, + const SPIExecuteOptions * <parameter>options</parameter>) </synopsis> </refsynopsisdiv> @@ -1748,14 +1746,29 @@ int SPI_execute_plan_with_paramlist(SPIPlanPtr <parameter>plan</parameter>, <title>Description</title> <para> - <function>SPI_execute_plan_with_paramlist</function> executes a statement - prepared by <function>SPI_prepare</function>. - This function is equivalent to <function>SPI_execute_plan</function> + <function>SPI_execute_plan_extended</function> executes a statement + prepared by <function>SPI_prepare</function> or one of its siblings. + This function is equivalent to <function>SPI_execute_plan</function>, except that information about the parameter values to be passed to the - query is presented differently. The <literal>ParamListInfo</literal> - representation can be convenient for passing down values that are - already available in that format. It also supports use of dynamic - parameter sets via hook functions specified in <literal>ParamListInfo</literal>. + query is presented differently, and additional execution-controlling + options can be passed. + </para> + + <para> + Query parameter values are represented by + a <literal>ParamListInfo</literal> struct, which is convenient for passing + down values that are already available in that format. Dynamic parameter + sets can also be used, via hook functions specified + in <literal>ParamListInfo</literal>. + </para> + + <para> + Also, instead of always accumulating the result tuples into a + <varname>SPI_tuptable</varname> structure, tuples can be passed to a + caller-supplied <literal>DestReceiver</literal> object as they are + generated by the executor. This is particularly helpful for queries + that might generate many tuples, since the data can be processed + on-the-fly instead of being accumulated in memory. </para> </refsect1> @@ -1773,10 +1786,29 @@ int SPI_execute_plan_with_paramlist(SPIPlanPtr <parameter>plan</parameter>, </varlistentry> <varlistentry> + <term><literal>const SPIExecuteOptions * <parameter>options</parameter></literal></term> + <listitem> + <para> + struct containing optional arguments + </para> + </listitem> + </varlistentry> + </variablelist> + + <para> + Callers should always zero out the entire <parameter>options</parameter> + struct, then fill whichever fields they want to set. This ensures forward + compatibility of code, since any fields that are added to the struct in + future will be defined to behave backwards-compatibly if they are zero. + The currently available <parameter>options</parameter> fields are: + </para> + + <variablelist> + <varlistentry> <term><literal>ParamListInfo <parameter>params</parameter></literal></term> <listitem> <para> - data structure containing parameter types and values; NULL if none + data structure containing query parameter types and values; NULL if none </para> </listitem> </varlistentry> @@ -1789,7 +1821,17 @@ int SPI_execute_plan_with_paramlist(SPIPlanPtr <parameter>plan</parameter>, </varlistentry> <varlistentry> - <term><literal>long <parameter>count</parameter></literal></term> + <term><literal>bool <parameter>no_snapshots</parameter></literal></term> + <listitem> + <para> + <literal>true</literal> prevents SPI from managing snapshots for + execution of the query; use with extreme caution + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>uint64 <parameter>tcount</parameter></literal></term> <listitem> <para> maximum number of rows to return, @@ -1797,6 +1839,29 @@ int SPI_execute_plan_with_paramlist(SPIPlanPtr <parameter>plan</parameter>, </para> </listitem> </varlistentry> + + <varlistentry> + <term><literal>DestReceiver * <parameter>dest</parameter></literal></term> + <listitem> + <para> + <literal>DestReceiver</literal> object that will receive any tuples + emitted by the query; if NULL, result tuples are accumulated into + a <varname>SPI_tuptable</varname> structure, as + in <function>SPI_execute_plan</function> + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>ResourceOwner <parameter>owner</parameter></literal></term> + <listitem> + <para> + The resource owner that will hold a reference count on the plan while + it is executed. If NULL, CurrentResourceOwner is used. Ignored for + non-saved plans, as SPI does not acquire reference counts on those. + </para> + </listitem> + </varlistentry> </variablelist> </refsect1> @@ -1808,35 +1873,40 @@ int SPI_execute_plan_with_paramlist(SPIPlanPtr <parameter>plan</parameter>, </para> <para> + When <parameter>dest</parameter> is NULL, <varname>SPI_processed</varname> and <varname>SPI_tuptable</varname> are set as in - <function>SPI_execute_plan</function> if successful. + <function>SPI_execute_plan</function>. + When <parameter>dest</parameter> is not NULL, + <varname>SPI_processed</varname> is set to zero and + <varname>SPI_tuptable</varname> is set to NULL. If a tuple count + is required, the caller's <literal>DestReceiver</literal> object must + calculate it. </para> </refsect1> </refentry> <!-- *********************************************** --> -<refentry id="spi-spi-execute-plan-with-receiver"> - <indexterm><primary>SPI_execute_plan_with_receiver</primary></indexterm> +<refentry id="spi-spi-execute-plan-with-paramlist"> + <indexterm><primary>SPI_execute_plan_with_paramlist</primary></indexterm> <refmeta> - <refentrytitle>SPI_execute_plan_with_receiver</refentrytitle> + <refentrytitle>SPI_execute_plan_with_paramlist</refentrytitle> <manvolnum>3</manvolnum> </refmeta> <refnamediv> - <refname>SPI_execute_plan_with_receiver</refname> + <refname>SPI_execute_plan_with_paramlist</refname> <refpurpose>execute a statement prepared by <function>SPI_prepare</function></refpurpose> </refnamediv> <refsynopsisdiv> <synopsis> -int SPI_execute_plan_with_receiver(SPIPlanPtr <parameter>plan</parameter>, - ParamListInfo <parameter>params</parameter>, - bool <parameter>read_only</parameter>, - long <parameter>count</parameter>, - DestReceiver *<parameter>dest</parameter>) +int SPI_execute_plan_with_paramlist(SPIPlanPtr <parameter>plan</parameter>, + ParamListInfo <parameter>params</parameter>, + bool <parameter>read_only</parameter>, + long <parameter>count</parameter>) </synopsis> </refsynopsisdiv> @@ -1844,15 +1914,19 @@ int SPI_execute_plan_with_receiver(SPIPlanPtr <parameter>plan</parameter>, <title>Description</title> <para> - <function>SPI_execute_plan_with_receiver</function> executes a statement - prepared by <function>SPI_prepare</function>. This function is - equivalent to <function>SPI_execute_plan_with_paramlist</function> - except that, instead of always accumulating the result tuples into a - <varname>SPI_tuptable</varname> structure, tuples can be passed to a - caller-supplied <literal>DestReceiver</literal> object as they are - generated by the executor. This is particularly helpful for queries - that might generate many tuples, since the data can be processed - on-the-fly instead of being accumulated in memory. + <function>SPI_execute_plan_with_paramlist</function> executes a statement + prepared by <function>SPI_prepare</function>. + This function is equivalent to <function>SPI_execute_plan</function> + except that information about the parameter values to be passed to the + query is presented differently. The <literal>ParamListInfo</literal> + representation can be convenient for passing down values that are + already available in that format. It also supports use of dynamic + parameter sets via hook functions specified in <literal>ParamListInfo</literal>. + </para> + + <para> + This function is now deprecated in favor + of <function>SPI_execute_plan_extended</function>. </para> </refsect1> @@ -1894,17 +1968,6 @@ int SPI_execute_plan_with_receiver(SPIPlanPtr <parameter>plan</parameter>, </para> </listitem> </varlistentry> - - <varlistentry> - <term><literal>DestReceiver * <parameter>dest</parameter></literal></term> - <listitem> - <para> - <literal>DestReceiver</literal> object that will receive any tuples - emitted by the query; if NULL, this function is exactly equivalent to - <function>SPI_execute_plan_with_paramlist</function> - </para> - </listitem> - </varlistentry> </variablelist> </refsect1> @@ -1916,15 +1979,9 @@ int SPI_execute_plan_with_receiver(SPIPlanPtr <parameter>plan</parameter>, </para> <para> - When <parameter>dest</parameter> is NULL, <varname>SPI_processed</varname> and <varname>SPI_tuptable</varname> are set as in - <function>SPI_execute_plan</function>. - When <parameter>dest</parameter> is not NULL, - <varname>SPI_processed</varname> is set to zero and - <varname>SPI_tuptable</varname> is set to NULL. If a tuple count - is required, the caller's <literal>DestReceiver</literal> object must - calculate it. + <function>SPI_execute_plan</function> if successful. </para> </refsect1> </refentry> |