readme

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

Proposal for function-manager redesign			19-Nov-2000
--------------------------------------

We know that the existing mechanism for calling Postgres functions needs
to be redesigned.  It has portability problems because it makes
assumptions about parameter passing that violate ANSI C; it fails to
handle NULL arguments and results cleanly; and "function handlers" that
support a class of functions (such as fmgr_pl) can only be done via a
really ugly, non-reentrant kluge.  (Global variable set during every
function call, forsooth.)  Here is a proposal for fixing these problems.

In the past, the major objections to redoing the function-manager
interface have been (a) it'll be quite tedious to implement, since every
built-in function and everyplace that calls such functions will need to
be touched; (b) such wide-ranging changes will be difficult to make in
parallel with other development work; (c) it will break existing
user-written loadable modules that define "C language" functions.  While
I have no solution to the "tedium" aspect, I believe I see an answer to
the other problems: by use of function handlers, we can support both old
and new interfaces in parallel for both callers and callees, at some
small efficiency cost for the old styles.  That way, most of the changes
can be done on an incremental file-by-file basis --- we won't need a
"big bang" where everything changes at once.  Support for callees
written in the old style can be left in place indefinitely, to provide
backward compatibility for user-written C functions.


Changes in pg_proc (system data about a function)
-------------------------------------------------

A new column "proisstrict" will be added to the system pg_proc table.
This is a boolean value which will be TRUE if the function is "strict",
that is it always returns NULL when any of its inputs are NULL.  The
function manager will check this field and skip calling the function when
it's TRUE and there are NULL inputs.  This allows us to remove explicit
NULL-value tests from many functions that currently need them (not to
mention fixing many more that need them but don't have them).  A function
that is not marked "strict" is responsible for checking whether its inputs
are NULL or not.  Most builtin functions will be marked "strict".

An optional WITH parameter will be added to CREATE FUNCTION to allow
specification of whether user-defined functions are strict or not.  I am
inclined to make the default be "not strict", since that seems to be the
more useful case for functions expressed in SQL or a PL language, but
am open to arguments for the other choice.


The new function-manager interface
----------------------------------

The core of the new design is revised data structures for representing
the result of a function lookup and for representing the parameters
passed to a specific function invocation.  (We want to keep function
lookup separate from function call, since many parts of the system apply
the same function over and over; the lookup overhead should be paid once
per query, not once per tuple.)


When a function is looked up in pg_proc, the result is represented as

typedef struct
{
    PGFunction  fn_addr;    /* pointer to function or handler to be called */
    Oid         fn_oid;     /* OID of function (NOT of handler, if any) */
    short       fn_nargs;   /* 0..FUNC_MAX_ARGS, or -1 if variable arg count */
    bool        fn_strict;  /* function is "strict" (NULL in => NULL out) */
    bool        fn_retset;  /* function returns a set (over multiple calls) */
    void       *fn_extra;   /* extra space for use by handler */
    MemoryContext fn_mcxt;  /* memory context to store fn_extra in */
    Node       *fn_expr;    /* expression parse tree for call, or NULL */
} FmgrInfo;

For an ordinary built-in function, fn_addr is just the address of the C
routine that implements the function.  Otherwise it is the address of a
handler for the class of functions that includes the target function.
The handler can use the function OID and perhaps also the fn_extra slot
to find the specific code to execute.  (fn_oid = InvalidOid can be used
to denote a not-yet-initialized FmgrInfo struct.  fn_extra will always
be NULL when an FmgrInfo is first filled by the function lookup code, but
a function handler could set it to avoid making repeated lookups of its
own when the same FmgrInfo is used repeatedly during a query.)  fn_nargs
is the number of arguments expected by the function, fn_strict is its
strictness flag, and fn_retset shows whether it returns a set; all of
these values come from the function's pg_proc entry.  If the function is
being called as part of a SQL expression, fn_expr will point to the
expression parse tree for the function call; this can be used to extract
parse-time knowledge about the actual arguments.

FmgrInfo already exists in the current code, but has fewer fields.  This
change should be transparent at the source-code level.


During a call of a function, the following data structure is created
and passed to the function:

typedef struct
{
    FmgrInfo   *flinfo;         /* ptr to lookup info used for this call */
    Node       *context;        /* pass info about context of call */
    Node       *resultinfo;     /* pass or return extra info about result */
    bool        isnull;         /* function must set true if result is NULL */
    short       nargs;          /* # arguments actually passed */
    Datum       arg[FUNC_MAX_ARGS];  /* Arguments passed to function */
    bool        argnull[FUNC_MAX_ARGS];  /* T if arg[i] is actually NULL */
} FunctionCallInfoData;
typedef FunctionCallInfoData* FunctionCallInfo;

flinfo points to the lookup info used to make the call.  Ordinary functions
will probably ignore this field, but function class handlers will need it
to find out the OID of the specific function being called.

context is NULL for an "ordinary" function call, but may point to additional
info when the function is called in certain contexts.  (For example, the
trigger manager will pass information about the current trigger event here.)
If context is used, it should point to some subtype of Node; the particular
kind of context is indicated by the node type field.  (A callee should
always check the node type before assuming it knows what kind of context is
being passed.)  fmgr itself puts no other restrictions on the use of this
field.

resultinfo is NULL when calling any function from which a simple Datum
result is expected.  It may point to some subtype of Node if the function
returns more than a Datum.  (For example, resultinfo is used when calling a
function that returns a set, as discussed below.)  Like the context field,
resultinfo is a hook for expansion; fmgr itself doesn't constrain the use
of the field.

nargs, arg[], and argnull[] hold the arguments being passed to the function.
Notice that all the arguments passed to a function (as well as its result
value) will now uniformly be of type Datum.  As discussed below, callers
and callees should apply the standard Datum-to-and-from-whatever macros
to convert to the actual argument types of a particular function.  The
value in arg[i] is unspecified when argnull[i] is true.

It is generally the responsibility of the caller to ensure that the
number of arguments passed matches what the callee is expecting; except
for callees that take a variable number of arguments, the callee will
typically ignore the nargs field and just grab values from arg[].

The isnull field will be initialized to "false" before the call.  On
return from the function, isnull is the null flag for the function result:
if it is true the function's result is NULL, regardless of the actual
function return value.  Note that simple "strict" functions can ignore
both isnull and argnull[], since they won't even get called when there
are any TRUE values in argnull[].

FunctionCallInfo replaces FmgrValues plus a bunch of ad-hoc parameter
conventions, global variables (fmgr_pl_finfo and CurrentTriggerData at
least), and other uglinesses.


Callees, whether they be individual functions or function handlers,
shall always have this signature:

Datum function (FunctionCallInfo fcinfo);

which is represented by the typedef

typedef Datum (*PGFunction) (FunctionCallInfo fcinfo);

The function is responsible for setting fcinfo->isnull appropriately
as well as returning a result represented as a Datum.  Note that since
all callees will now have exactly the same signature, and will be called
through a function pointer declared with exactly that signature, we
should have no portability or optimization problems.


Function coding conventions
---------------------------

As an example, int4 addition goes from old-style

int32
int4pl(int32 arg1, int32 arg2)
{
    return arg1 + arg2;
}

to new-style

Datum
int4pl(FunctionCallInfo fcinfo)
{
    /* we assume the function is marked "strict", so we can ignore
     * NULL-value handling */

    return Int32GetDatum(DatumGetInt32(fcinfo->arg[0]) +
                         DatumGetInt32(fcinfo->arg[1]));
}

This is, of course, much uglier than the old-style code, but we can
improve matters with some well-chosen macros for the boilerplate parts.
I propose below macros that would make the code look like

Datum
int4pl(PG_FUNCTION_ARGS)
{
    int32   arg1 = PG_GETARG_INT32(0);
    int32   arg2 = PG_GETARG_INT32(1);

    PG_RETURN_INT32( arg1 + arg2 );
}

This is still more code than before, but it's fairly readable, and it's
also amenable to machine processing --- for example, we could probably
write a script that scans code like this and extracts argument and result
type info for comparison to the pg_proc table.

For the standard data types float4, float8, and int8, these macros should
hide the indirection and space allocation involved, so that the function's
code is not explicitly aware that these types are pass-by-reference.  This
will offer a considerable gain in readability, and it also opens up the
opportunity to make these types be pass-by-value on machines where it's
feasible to do so.  (For example, on an Alpha it's pretty silly to make int8
be pass-by-ref, since Datum is going to be 64 bits anyway.  float4 could
become pass-by-value on all machines...)

Here are the proposed macros and coding conventions:

The definition of an fmgr-callable function will always look like

Datum
function_name(PG_FUNCTION_ARGS)
{
	...
}

"PG_FUNCTION_ARGS" just expands to "FunctionCallInfo fcinfo".  The main
reason for using this macro is to make it easy for scripts to spot function
definitions.  However, if we ever decide to change the calling convention
again, it might come in handy to have this macro in place.

A nonstrict function is responsible for checking whether each individual
argument is null or not, which it can do with PG_ARGISNULL(n) (which is
just "fcinfo->argnull[n]").  It should avoid trying to fetch the value
of any argument that is null.

Both strict and nonstrict functions can return NULL, if needed, with
	PG_RETURN_NULL();
which expands to
	{ fcinfo->isnull = true; return (Datum) 0; }

Argument values are ordinarily fetched using code like
	int32	name = PG_GETARG_INT32(number);

For float4, float8, and int8, the PG_GETARG macros will hide the pass-by-
reference nature of the data types; for example PG_GETARG_FLOAT4 expands to
	(* (float4 *) DatumGetPointer(fcinfo->arg[number]))
and would typically be called like this:
	float4  arg = PG_GETARG_FLOAT4(0);
Note that "float4" and "float8" are the recommended typedefs to use, not
"float32data" and "float64data", and the macros are named accordingly.
But 64-bit ints should be declared as "int64".

Non-null values are returned with a PG_RETURN_XXX macro of the appropriate
type.  For example, PG_RETURN_INT32 expands to
	return Int32GetDatum(x)
PG_RETURN_FLOAT4, PG_RETURN_FLOAT8, and PG_RETURN_INT64 hide the pass-by-
reference nature of their datatypes.

fmgr.h will provide PG_GETARG and PG_RETURN macros for all the basic data
types.  Modules or header files that define specialized SQL datatypes
(eg, timestamp) should define appropriate macros for those types, so that
functions manipulating the types can be coded in the standard style.

For non-primitive data types (particularly variable-length types) it won't
be very practical to hide the pass-by-reference nature of the data type,
so the PG_GETARG and PG_RETURN macros for those types won't do much more
than DatumGetPointer/PointerGetDatum plus the appropriate typecast (but see
TOAST discussion, below).  Functions returning such types will need to