readme

PostgreSQL 8.1.4的源码 适用于Linux下的开源数据库系统

palloc() their result space explicitly.  I recommend naming the GETARG and
RETURN macros for such types to end in "_P", as a reminder that they
produce or take a pointer.  For example, PG_GETARG_TEXT_P yields "text *".

When a function needs to access fcinfo->flinfo or one of the other auxiliary
fields of FunctionCallInfo, it should just do it.  I doubt that providing
syntactic-sugar macros for these cases is useful.


Call-site coding conventions
----------------------------

There are many places in the system that call either a specific function
(for example, the parser invokes "textin" by name in places) or a
particular group of functions that have a common argument list (for
example, the optimizer invokes selectivity estimation functions with
a fixed argument list).  These places will need to change, but we should
try to avoid making them significantly uglier than before.

Places that invoke an arbitrary function with an arbitrary argument list
can simply be changed to fill a FunctionCallInfoData structure directly;
that'll be no worse and possibly cleaner than what they do now.

When invoking a specific built-in function by name, we have generally
just written something like
	result = textin ( ... args ... )
which will not work after textin() is converted to the new call style.
I suggest that code like this be converted to use "helper" functions
that will create and fill in a FunctionCallInfoData struct.  For
example, if textin is being called with one argument, it'd look
something like
	result = DirectFunctionCall1(textin, PointerGetDatum(argument));
These helper routines will have declarations like
	Datum DirectFunctionCall2(PGFunction func, Datum arg1, Datum arg2);
Note it will be the caller's responsibility to convert to and from
Datum; appropriate conversion macros should be used.

The DirectFunctionCallN routines will not bother to fill in
fcinfo->flinfo (indeed cannot, since they have no idea about an OID for
the target function); they will just set it NULL.  This is unlikely to
bother any built-in function that could be called this way.  Note also
that this style of coding cannot pass a NULL input value nor cope with
a NULL result (it couldn't before, either!).  We can make the helper
routines ereport an error if they see that the function returns a NULL.

When invoking a function that has a known argument signature, we have
usually written either
	result = fmgr(targetfuncOid, ... args ... );
or
	result = fmgr_ptr(FmgrInfo *finfo, ... args ... );
depending on whether an FmgrInfo lookup has been done yet or not.
This kind of code can be recast using helper routines, in the same
style as above:
	result = OidFunctionCall1(funcOid, PointerGetDatum(argument));
	result = FunctionCall2(funcCallInfo,
	                       PointerGetDatum(argument),
	                       Int32GetDatum(argument));
Again, this style of coding does not allow for expressing NULL inputs
or receiving a NULL result.

As with the callee-side situation, I propose adding argument conversion
macros that hide the pass-by-reference nature of int8, float4, and
float8, with an eye to making those types relatively painless to convert
to pass-by-value.

The existing helper functions fmgr(), fmgr_c(), etc will be left in
place until all uses of them are gone.  Of course their internals will
have to change in the first step of implementation, but they can
continue to support the same external appearance.


Support for TOAST-able data types
---------------------------------

For TOAST-able data types, the PG_GETARG macro will deliver a de-TOASTed
data value.  There might be a few cases where the still-toasted value is
wanted, but the vast majority of cases want the de-toasted result, so
that will be the default.  To get the argument value without causing
de-toasting, use PG_GETARG_RAW_VARLENA_P(n).

Some functions require a modifiable copy of their input values.  In these
cases, it's silly to do an extra copy step if we copied the data anyway
to de-TOAST it.  Therefore, each toastable datatype has an additional
fetch macro, for example PG_GETARG_TEXT_P_COPY(n), which delivers a
guaranteed-fresh copy, combining this with the detoasting step if possible.

There is also a PG_FREE_IF_COPY(ptr,n) macro, which pfree's the given
pointer if and only if it is different from the original value of the n'th
argument.  This can be used to free the de-toasted value of the n'th
argument, if it was actually de-toasted.  Currently, doing this is not
necessary for the majority of functions because the core backend code
releases temporary space periodically, so that memory leaked in function
execution isn't a big problem.  However, as of 7.1 memory leaks in
functions that are called by index searches will not be cleaned up until
end of transaction.  Therefore, functions that are listed in pg_amop or
pg_amproc should be careful not to leak detoasted copies, and so these
functions do need to use PG_FREE_IF_COPY() for toastable inputs.

A function should never try to re-TOAST its result value; it should just
deliver an untoasted result that's been palloc'd in the current memory
context.  When and if the value is actually stored into a tuple, the
tuple toaster will decide whether toasting is needed.


Functions accepting or returning sets
-------------------------------------

[ this section revised 29-Aug-2002 for 7.3 ]

If a function is marked in pg_proc as returning a set, then it is called
with fcinfo->resultinfo pointing to a node of type ReturnSetInfo.  A
function that desires to return a set should raise an error "called in
context that does not accept a set result" if resultinfo is NULL or does
not point to a ReturnSetInfo node.

There are currently two modes in which a function can return a set result:
value-per-call, or materialize.  In value-per-call mode, the function returns
one value each time it is called, and finally reports "done" when it has no
more values to return.  In materialize mode, the function's output set is
instantiated in a Tuplestore object; all the values are returned in one call.
Additional modes might be added in future.

ReturnSetInfo contains a field "allowedModes" which is set (by the caller)
to a bitmask that's the OR of the modes the caller can support.  The actual
mode used by the function is returned in another field "returnMode".  For
backwards-compatibility reasons, returnMode is initialized to value-per-call
and need only be changed if the function wants to use a different mode.
The function should ereport() if it cannot use any of the modes the caller is
willing to support.

Value-per-call mode works like this: ReturnSetInfo contains a field
"isDone", which should be set to one of these values:

    ExprSingleResult             /* expression does not return a set */
    ExprMultipleResult           /* this result is an element of a set */
    ExprEndResult                /* there are no more elements in the set */

(the caller will initialize it to ExprSingleResult).  If the function simply
returns a Datum without touching ReturnSetInfo, then the call is over and a
single-item set has been returned.  To return a set, the function must set
isDone to ExprMultipleResult for each set element.  After all elements have
been returned, the next call should set isDone to ExprEndResult and return a
null result.  (Note it is possible to return an empty set by doing this on
the first call.)

The ReturnSetInfo node also contains a link to the ExprContext within which
the function is being evaluated.  This is useful for value-per-call functions
that need to close down internal state when they are not run to completion:
they can register a shutdown callback function in the ExprContext.

Materialize mode works like this: the function creates a Tuplestore holding
the (possibly empty) result set, and returns it.  There are no multiple calls.
The function must also return a TupleDesc that indicates the tuple structure.
The Tuplestore and TupleDesc should be created in the context
econtext->ecxt_per_query_memory (note this will *not* be the context the
function is called in).  The function stores pointers to the Tuplestore and
TupleDesc into ReturnSetInfo, sets returnMode to indicate materialize mode,
and returns null.  isDone is not used and should be left at ExprSingleResult.

If the function is being called as a table function (ie, it appears in a
FROM item), then the expected tuple descriptor is passed in ReturnSetInfo;
in other contexts the expectedDesc field will be NULL.  The function need
not pay attention to expectedDesc, but it may be useful in special cases.

There is no support for functions accepting sets; instead, the function will
be called multiple times, once for each element of the input set.


Notes about function handlers
-----------------------------

Handlers for classes of functions should find life much easier and
cleaner in this design.  The OID of the called function is directly
reachable from the passed parameters; we don't need the global variable
fmgr_pl_finfo anymore.  Also, by modifying fcinfo->flinfo->fn_extra,
the handler can cache lookup info to avoid repeat lookups when the same
function is invoked many times.  (fn_extra can only be used as a hint,
since callers are not required to re-use an FmgrInfo struct.
But in performance-critical paths they normally will do so.)

If the handler wants to allocate memory to hold fn_extra data, it should
NOT do so in CurrentMemoryContext, since the current context may well be
much shorter-lived than the context where the FmgrInfo is.  Instead,
allocate the memory in context flinfo->fn_mcxt, or in a long-lived cache
context.  fn_mcxt normally points at the context that was
CurrentMemoryContext at the time the FmgrInfo structure was created;
in any case it is required to be a context at least as long-lived as the
FmgrInfo itself.


Telling the difference between old- and new-style functions
-----------------------------------------------------------

During the conversion process, we carried two different pg_language
entries, "internal" and "newinternal", for internal functions.  The
function manager used the language code to distinguish which calling
convention to use.  (Old-style internal functions were supported via
a function handler.)  As of Nov. 2000, no old-style internal functions
remain, so we can drop support for them.  We will remove the old "internal"
pg_language entry and rename "newinternal" to "internal".

The interim solution for dynamically-loaded compiled functions has been
similar: two pg_language entries "C" and "newC".  This naming convention
is not desirable for the long run, and yet we cannot stop supporting
old-style user functions.  Instead, it seems better to use just one
pg_language entry "C", and require the dynamically-loaded library to
provide additional information that identifies new-style functions.
This avoids compatibility problems --- for example, existing dump
scripts will identify PL language handlers as being in language "C",
which would be wrong under the "newC" convention.  Also, this approach
should generalize more conveniently for future extensions to the function
interface specification.

Given a dynamically loaded function named "foo" (note that the name being
considered here is the link-symbol name, not the SQL-level function name),
the function manager will look for another function in the same dynamically
loaded library named "pg_finfo_foo".  If this second function does not
exist, then foo is assumed to be called old-style, thus ensuring backwards
compatibility with existing libraries.  If the info function does exist,
it is expected to have the signature

	Pg_finfo_record * pg_finfo_foo (void);

The info function will be called by the fmgr, and must return a pointer
to a Pg_finfo_record struct.  (The returned struct will typically be a
statically allocated constant in the dynamic-link library.)  The current
definition of the struct is just

	typedef struct {
		int	api_version;
	} Pg_finfo_record;

where api_version is 0 to indicate old-style or 1 to indicate new-style
calling convention.  In future releases, additional fields may be defined
after api_version, but these additional fields will only be used if
api_version is greater than 1.

These details will be hidden from the author of a dynamically loaded
function by using a macro.  To define a new-style dynamically loaded
function named foo, write

	PG_FUNCTION_INFO_V1(foo);

	Datum
	foo(PG_FUNCTION_ARGS)
	{
		...
	}

The function itself is written using the same conventions as for new-style
internal functions; you just need to add the PG_FUNCTION_INFO_V1() macro.
Note that old-style and new-style functions can be intermixed in the same
library, depending on whether or not you write a PG_FUNCTION_INFO_V1() for
each one.

The SQL declaration for a dynamically-loaded function is CREATE FUNCTION
foo ... LANGUAGE 'C' regardless of whether it is old- or new-style.

New-style dynamic functions will be invoked directly by fmgr, and will
therefore have the same performance as internal functions after the initial
pg_proc lookup overhead.  Old-style dynamic functions will be invoked via
a handler, and will therefore have a small performance penalty.

To allow old-style dynamic functions to work safely on toastable datatypes,
the handler for old-style functions will automatically detoast toastable
arguments before passing them to the old-style function.  A new-style
function is expected to take care of toasted arguments by using the
standard argument access macros defined above.