diff options
Diffstat (limited to 'doc/src')
| -rw-r--r-- | doc/src/sgml/catalogs.sgml | 37 | ||||
| -rw-r--r-- | doc/src/sgml/ref/create_function.sgml | 67 | ||||
| -rw-r--r-- | doc/src/sgml/release.sgml | 3 |
3 files changed, 80 insertions, 27 deletions
diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml index 31f82d12370..ba9c9b15e79 100644 --- a/doc/src/sgml/catalogs.sgml +++ b/doc/src/sgml/catalogs.sgml @@ -1,6 +1,6 @@ <!-- Documentation of the system catalogs, directed toward PostgreSQL developers - $Header: /cvsroot/pgsql/doc/src/sgml/catalogs.sgml,v 2.39 2002/03/29 19:05:57 tgl Exp $ + $Header: /cvsroot/pgsql/doc/src/sgml/catalogs.sgml,v 2.40 2002/04/05 00:31:22 tgl Exp $ --> <chapter id="catalogs"> @@ -1654,6 +1654,15 @@ </row> <row> + <entry>pronamespace</entry> + <entry><type>oid</type></entry> + <entry>pg_namespace.oid</entry> + <entry> + The OID of the namespace that contains this function + </entry> + </row> + + <row> <entry>proowner</entry> <entry><type>int4</type></entry> <entry>pg_shadow.usesysid</entry> @@ -1682,13 +1691,6 @@ </row> <row> - <entry>proiscachable</entry> - <entry><type>bool</type></entry> - <entry></entry> - <entry>Function returns same result for same input values</entry> - </row> - - <row> <entry>proisstrict</entry> <entry><type>bool</type></entry> <entry></entry> @@ -1701,6 +1703,25 @@ </row> <row> + <entry>provolatile</entry> + <entry><type>char</type></entry> + <entry></entry> + <entry> + <structfield>provolatile</structfield> tells whether the function's + result depends only on its input arguments, or is affected by outside + factors. + It is <literal>i</literal> for <quote>immutable</> functions, + which always deliver the same result for the same inputs. + It is <literal>s</literal> for <quote>stable</> functions, + whose results (for fixed inputs) do not change within a scan. + It is <literal>v</literal> for <quote>volatile</> functions, + whose results may change at any time. (Use <literal>v</literal> also + for functions with side-effects, so that calls to them cannot get + optimized away.) + </entry> + </row> + + <row> <entry>pronargs</entry> <entry><type>int2</type></entry> <entry></entry> diff --git a/doc/src/sgml/ref/create_function.sgml b/doc/src/sgml/ref/create_function.sgml index c6ee3e25efd..28c54e1eb89 100644 --- a/doc/src/sgml/ref/create_function.sgml +++ b/doc/src/sgml/ref/create_function.sgml @@ -1,5 +1,5 @@ <!-- -$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_function.sgml,v 1.34 2002/03/22 19:20:37 petere Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_function.sgml,v 1.35 2002/04/05 00:31:24 tgl Exp $ --> <refentry id="SQL-CREATEFUNCTION"> @@ -160,35 +160,63 @@ CREATE [ OR REPLACE ] FUNCTION <replaceable class="parameter">name</replaceable> <variablelist> <varlistentry> - <term>iscachable</term> + <term>isStrict</term> <listitem> <para> - <option>Iscachable</option> indicates that the function always - returns the same result when given the same argument values (i.e., - it does not do database lookups or otherwise use information not - directly present in its parameter list). The optimizer uses - <option>iscachable</option> to know whether it is safe to - pre-evaluate a call of the function. + <option>isStrict</option> indicates that the function always + returns NULL whenever any of its arguments are NULL. If this + attribute is specified, the function is not executed when there + are NULL arguments; instead a NULL result is assumed automatically. + When <option>isStrict</option> is not specified, the function will + be called for NULL inputs. It is then the function author's + responsibility to check for NULLs if necessary and respond + appropriately. </para> </listitem> </varlistentry> <varlistentry> - <term>isstrict</term> + <term>isImmutable</term> + <term>isCachable</term> + <term>isStable</term> + <term>isVolatile</term> <listitem> <para> - <option>isstrict</option> indicates that the function always - returns NULL whenever any of its arguments are NULL. If this - attribute is specified, the function is not executed when there - are NULL arguments; instead a NULL result is assumed automatically. - When <option>isstrict</option> is not specified, the function will - be called for NULL inputs. It is then the function author's - responsibility to check for NULLs if necessary and respond - appropriately. + These attributes inform the system whether it is safe to replace + multiple evaluations of the function with a single evaluation. + At most one choice should be specified. (If none of these appear, + <option>isVolatile</option> is the default assumption.) + <option>isImmutable</option> indicates that the function always + returns the same result when given the same argument values; that + is, it does not do database lookups or otherwise use information not + directly present in its parameter list. If this option is given, + any call of the function with all-constant arguments can be + immediately replaced with the function value. + <option>isCachable</option> is an + obsolete equivalent of <option>isImmutable</option>; it's still + accepted for backwards-compatibility reasons. + <option>isStable</option> indicates that within a single table scan + the function will consistently + return the same result for the same argument values, but that its + result could change across SQL statements. This is the appropriate + selection for functions whose results depend on database lookups, + parameter variables (such as the current timezone), etc. Also note + that the <literal>CURRENT_TIMESTAMP</> family of functions qualify + as stable, since their values do not change within a transaction. + <option>isVolatile</option> indicates that the function value can + change even within a single table scan, so no optimizations can be + made. Relatively few database functions are volatile in this sense; + some examples are <literal>random()</>, <literal>currval()</>, + <literal>timeofday()</>. Note that any function that has side-effects + must be classified volatile, even if its result is quite predictable, + to prevent calls from being optimized away; an example is + <literal>setval()</>. </para> </listitem> </varlistentry> </variablelist> + + Attribute names are not case-sensitive. </para> </refsect1> @@ -342,7 +370,7 @@ CREATE TABLE product ( <programlisting> CREATE FUNCTION point(complex) RETURNS point AS '/home/bernie/pgsql/lib/complex.so', 'complex_to_point' - LANGUAGE C; + LANGUAGE C WITH (isStrict); </programlisting> The C declaration of the function could be: @@ -359,6 +387,9 @@ Point * complex_to_point (Complex *z) return p; } </programlisting> + + Note that the function is marked <quote>strict</>; this allows us + to skip checking for NULL input in the function body. </para> </refsect1> diff --git a/doc/src/sgml/release.sgml b/doc/src/sgml/release.sgml index dfb96e4ff8e..e70bb7fa099 100644 --- a/doc/src/sgml/release.sgml +++ b/doc/src/sgml/release.sgml @@ -1,5 +1,5 @@ <!-- -$Header: /cvsroot/pgsql/doc/src/sgml/release.sgml,v 1.130 2002/04/03 05:39:28 petere Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/release.sgml,v 1.131 2002/04/05 00:31:23 tgl Exp $ --> <appendix id="release"> @@ -24,6 +24,7 @@ CDATA means the content is "SGML-free", so you can write without worries about funny characters. --> <literallayout><![CDATA[ +Define a third class of function volatility to allow indexscans in more cases Locale support is now built by default; choice of locale is set by initdb and/or at run-time ALTER TABLE ALTER COLUMN SET/DROP NOT NULL EXPLAIN output comes out as a query result, not a NOTICE message |