Обсуждение: WIP patch: improve documentation for user defined final functions of aggregates

The fact that a final function may be called
multiple times does not appear to be mentioned
in the docs, and a reasonable reading of the
docs gives the alternate impression.  For
people writing final functions in C, there
should be some warning about changing the
transition value, such as exists in the comments
in src/backend/executor/nodeWindowAgg.c


I'm not sure if this warning should be placed
in the docs of the CREATE AGGREGATE command, or
in section 35.10.  The documentation for the
CREATE AGGREGATE command talks more about what
final functions do, and hence is the more natural
placement in that sense, but for users who are
not doing C programming, changing the state of
the transition value is probably not a problem.

WIP WIP WIP WIP WIP


diff --git a/doc/src/sgml/ref/create_aggregate.sgml b/doc/src/sgml/ref/create_aggregate.sgml
index d15fcba..d4603cc 100644
--- a/doc/src/sgml/ref/create_aggregate.sgml
+++ b/doc/src/sgml/ref/create_aggregate.sgml
@@ -111,6 +111,12 @@ CREATE AGGREGATE <replaceable class="PARAMETER">name</replaceable> (
   </para>
 
   <para>
+   The final function may be invoked at other times during the processing
+   of all rows and must not damage the internal state value.  It is unwise
+   to assume that the final function will only be invoked once.
+  </para>
+
+  <para>
    An aggregate function can provide an initial condition,
    that is, an initial value for the internal state value.
    This is specified and stored in the database as a value of type

Mark Dilger <markdilger@yahoo.com> writes:
> The fact that a final function may be called
> multiple times does not appear to be mentioned
> in the docs,

It's in xaggr.sgml, near the discussion of AggCheckCallContext
(the end of section 35.10, in current HEAD's section numbering).

In general, people writing C functions should not expect that they
can scribble on pass-by-ref arguments, so I don't see a need to
belabor the point in multiple places.
        regards, tom lane