From 4bdb4be62e652ee3220dae21a4fa340832c93429 Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Fri, 5 Apr 2002 00:31:36 +0000 Subject: Divide functions into three volatility classes (immutable, stable, and volatile), rather than the old cachable/noncachable distinction. This allows indexscan optimizations in many places where we formerly didn't. Also, add a pronamespace column to pg_proc (it doesn't do anything yet, however). --- doc/src/sgml/catalogs.sgml | 37 ++++++++++++++----- doc/src/sgml/ref/create_function.sgml | 67 +++++++++++++++++++++++++---------- doc/src/sgml/release.sgml | 3 +- 3 files changed, 80 insertions(+), 27 deletions(-) (limited to 'doc/src') 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 @@ @@ -1653,6 +1653,15 @@ Name of the function + + pronamespace + oid + pg_namespace.oid + + The OID of the namespace that contains this function + + + proowner int4 @@ -1681,13 +1690,6 @@ not functional - - proiscachable - bool - - Function returns same result for same input values - - proisstrict bool @@ -1700,6 +1702,25 @@ + + provolatile + char + + + provolatile tells whether the function's + result depends only on its input arguments, or is affected by outside + factors. + It is i for immutable functions, + which always deliver the same result for the same inputs. + It is s for stable functions, + whose results (for fixed inputs) do not change within a scan. + It is v for volatile functions, + whose results may change at any time. (Use v also + for functions with side-effects, so that calls to them cannot get + optimized away.) + + + pronargs int2 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 @@ @@ -160,35 +160,63 @@ CREATE [ OR REPLACE ] FUNCTION name - iscachable + isStrict - 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 - to know whether it is safe to - pre-evaluate a call of the function. + 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 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. - isstrict + isImmutable + isCachable + isStable + isVolatile - 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 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, + is the default assumption.) + 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. + is an + obsolete equivalent of ; it's still + accepted for backwards-compatibility reasons. + 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 CURRENT_TIMESTAMP family of functions qualify + as stable, since their values do not change within a transaction. + 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 random(), currval(), + 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 + setval(). + + Attribute names are not case-sensitive. @@ -342,7 +370,7 @@ CREATE TABLE product ( CREATE FUNCTION point(complex) RETURNS point AS '/home/bernie/pgsql/lib/complex.so', 'complex_to_point' - LANGUAGE C; + LANGUAGE C WITH (isStrict); The C declaration of the function could be: @@ -359,6 +387,9 @@ Point * complex_to_point (Complex *z) return p; } + + Note that the function is marked strict; this allows us + to skip checking for NULL input in the function body. 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 @@ @@ -24,6 +24,7 @@ CDATA means the content is "SGML-free", so you can write without worries about funny characters. -->