Improve documentation about function volatility: mention the snapshot

visibility effects in a couple of places where people are likely to look
for it.  Per discussion of recent question from Karl Nack.

diff --git a/doc/src/sgml/trigger.sgml b/doc/src/sgml/trigger.sgml
index ac4812278e7dd060caee72472d5b353b92489270..473e107c84012f937b701d4d65ccb0757bd0c885 100644 (file)
--- a/doc/src/sgml/trigger.sgml
+++ b/doc/src/sgml/trigger.sgml
@@ -1,4 +1,4 @@
-
+
 
  
   Triggers
@@ -249,6 +249,14 @@
     
    
 
+   
+    If your trigger function is written in any of the standard procedural
+    languages, then the above statements apply only if the function is
+    declared VOLATILE.  Functions that are declared
+    STABLE or IMMUTABLE will not see changes made by
+    the calling command in any case.
+   
+
    
     Further information about data visibility rules can be found in
     .  The example in 


diff --git a/doc/src/sgml/xfunc.sgml b/doc/src/sgml/xfunc.sgml

index 258472f7b9d7a621bdd8a5d9030a204e083c3f52..bb4fd68bb460da0e83c3dc45d69725a586ce2e98 100644 (file)

--- a/doc/src/sgml/xfunc.sgml
+++ b/doc/src/sgml/xfunc.sgml
@@ -1,4 +1,4 @@
-
+
 
  
   User-Defined Functions
@@ -1177,6 +1177,12 @@ CREATE FUNCTION test(int, int) RETURNS int
     timeofday().
    
 
+   
+    Another important example is that the current_timestamp
+    family of functions qualify as STABLE, since their values do
+    not change within a transaction.
+   
+
    
     There is relatively little difference between STABLE and
     IMMUTABLE categories when considering simple interactive
@@ -1192,16 +1198,35 @@ CREATE FUNCTION test(int, int) RETURNS int
    
 
    
-    Because of the snapshotting behavior of MVCC (see )
+    For functions written in SQL or in any of the standard procedural
+    languages, there is a second important property determined by the
+    volatility category, namely the visibility of any data changes that have
+    been made by the SQL command that is calling the function.  A
+    VOLATILE function will see such changes, a STABLE
+    or IMMUTABLE function will not.  This behavior is implemented
+    using the snapshotting behavior of MVCC (see ):
+    STABLE and IMMUTABLE functions use a snapshot
+    established as of the start of the calling query, whereas
+    VOLATILE functions obtain a fresh snapshot at the start of
+    each query they execute.
+   
+
+   
+    
+     Functions written in C can manage snapshots however they want, but it's
+     usually a good idea to make C functions work this way too.
+    
+   
+
+   
+    Because of this snapshotting behavior,
     a function containing only SELECT commands can safely be
     marked STABLE, even if it selects from tables that might be
     undergoing modifications by concurrent queries.
-    PostgreSQL will execute a STABLE
-    function using the snapshot established for the calling query, and so it
-    will see a fixed view of the database throughout that query.
-    Also note
-    that the current_timestamp family of functions qualify
-    as stable, since their values do not change within a transaction.
+    PostgreSQL will execute all commands of a
+    STABLE function using the snapshot established for the
+    calling query, and so it will see a fixed view of the database throughout
+    that query.
    
 
    
@@ -1225,14 +1250,14 @@ CREATE FUNCTION test(int, int) RETURNS int
     
      Before PostgreSQL release 8.0, the requirement
      that STABLE and IMMUTABLE functions cannot modify
-     the database was not enforced by the system.  Release 8.0 enforces it
+     the database was not enforced by the system.  Releases 8.0 and later enforce it
      by requiring SQL functions and procedural language functions of these
      categories to contain no SQL commands other than SELECT.
      (This is not a completely bulletproof test, since such functions could
      still call VOLATILE functions that modify the database.
      If you do that, you will find that the STABLE or
      IMMUTABLE function does not notice the database changes
-     applied by the called function.)
+     applied by the called function, since they are hidden from its snapshot.)
     
    
   

diff --git a/doc/src/sgml/xfunc.sgml b/doc/src/sgml/xfunc.sgml
index 258472f7b9d7a621bdd8a5d9030a204e083c3f52..bb4fd68bb460da0e83c3dc45d69725a586ce2e98 100644 (file)
--- a/doc/src/sgml/xfunc.sgml
+++ b/doc/src/sgml/xfunc.sgml
@@ -1,4 +1,4 @@
-
+
 
  
   User-Defined Functions
@@ -1177,6 +1177,12 @@ CREATE FUNCTION test(int, int) RETURNS int
     timeofday().
    
 
+   
+    Another important example is that the current_timestamp
+    family of functions qualify as STABLE, since their values do
+    not change within a transaction.
+   
+
    
     There is relatively little difference between STABLE and
     IMMUTABLE categories when considering simple interactive
@@ -1192,16 +1198,35 @@ CREATE FUNCTION test(int, int) RETURNS int
    
 
    
-    Because of the snapshotting behavior of MVCC (see )
+    For functions written in SQL or in any of the standard procedural
+    languages, there is a second important property determined by the
+    volatility category, namely the visibility of any data changes that have
+    been made by the SQL command that is calling the function.  A
+    VOLATILE function will see such changes, a STABLE
+    or IMMUTABLE function will not.  This behavior is implemented
+    using the snapshotting behavior of MVCC (see ):
+    STABLE and IMMUTABLE functions use a snapshot
+    established as of the start of the calling query, whereas
+    VOLATILE functions obtain a fresh snapshot at the start of
+    each query they execute.
+   
+
+   
+    
+     Functions written in C can manage snapshots however they want, but it's
+     usually a good idea to make C functions work this way too.
+    
+   
+
+   
+    Because of this snapshotting behavior,
     a function containing only SELECT commands can safely be
     marked STABLE, even if it selects from tables that might be
     undergoing modifications by concurrent queries.
-    PostgreSQL will execute a STABLE
-    function using the snapshot established for the calling query, and so it
-    will see a fixed view of the database throughout that query.
-    Also note
-    that the current_timestamp family of functions qualify
-    as stable, since their values do not change within a transaction.
+    PostgreSQL will execute all commands of a
+    STABLE function using the snapshot established for the
+    calling query, and so it will see a fixed view of the database throughout
+    that query.
    
 
    
@@ -1225,14 +1250,14 @@ CREATE FUNCTION test(int, int) RETURNS int
     
      Before PostgreSQL release 8.0, the requirement
      that STABLE and IMMUTABLE functions cannot modify
-     the database was not enforced by the system.  Release 8.0 enforces it
+     the database was not enforced by the system.  Releases 8.0 and later enforce it
      by requiring SQL functions and procedural language functions of these
      categories to contain no SQL commands other than SELECT.
      (This is not a completely bulletproof test, since such functions could
      still call VOLATILE functions that modify the database.
      If you do that, you will find that the STABLE or
      IMMUTABLE function does not notice the database changes
-     applied by the called function.)
+     applied by the called function, since they are hidden from its snapshot.)