From 5bb2300b59b74cdc7c8e3f0bf3c8d31c27657670 Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Mon, 20 Nov 2000 20:36:57 +0000 Subject: Revise handling of oldstyle/newstyle functions per recent discussions in pghackers list. Support for oldstyle internal functions is gone (no longer needed, since conversion is complete) and pg_language entry 'internal' now implies newstyle call convention. pg_language entry 'newC' is gone; both old and newstyle dynamically loaded C functions are now called language 'C'. A newstyle function must be identified by an associated info routine. See src/backend/utils/fmgr/README. --- doc/src/sgml/ref/create_function.sgml | 7 ++- doc/src/sgml/ref/create_language.sgml | 16 +++--- doc/src/sgml/trigger.sgml | 6 ++- doc/src/sgml/xfunc.sgml | 98 ++++++++++++++++++++--------------- 4 files changed, 71 insertions(+), 56 deletions(-) (limited to 'doc/src') diff --git a/doc/src/sgml/ref/create_function.sgml b/doc/src/sgml/ref/create_function.sgml index 20a7b6f8b03..bb733b8df2e 100644 --- a/doc/src/sgml/ref/create_function.sgml +++ b/doc/src/sgml/ref/create_function.sgml @@ -1,5 +1,5 @@ @@ -119,8 +119,7 @@ CREATE FUNCTION name ( [ May be 'sql', - 'C', 'newC', - 'internal', 'newinternal', + 'C', 'internal', or 'plname', where 'plname' is the name of a created procedural language. See @@ -258,7 +257,7 @@ CREATE - Two internal or newinternal + Two internal functions cannot have the same C name without causing errors at link time. To get around that, give them different C names (for example, use the argument types as part of the C names), then diff --git a/doc/src/sgml/ref/create_language.sgml b/doc/src/sgml/ref/create_language.sgml index 934b6cbaf9e..f5e1c6ffa90 100644 --- a/doc/src/sgml/ref/create_language.sgml +++ b/doc/src/sgml/ref/create_language.sgml @@ -1,5 +1,5 @@ @@ -163,7 +163,8 @@ ERROR: PL handler function funcname In Postgres 7.1 and later, call handlers - must adhere to the "new style" function manager interface. + must adhere to the "version 1" function manager interface, not the + old-style interface. @@ -180,7 +181,7 @@ ERROR: PL handler function funcname - The call handler is called in the same way as any other new-style + The call handler is called in the same way as any other function: it receives a pointer to a FunctionCallInfoData struct containing argument values and information about the called function, and it is expected to return a Datum result (and possibly set the @@ -269,9 +270,7 @@ ERROR: PL handler function funcname @@ -279,8 +278,9 @@ ERROR: PL handler function funcname The call handler for a procedural language must normally be written - in C and registered as 'newinternal' or 'newC' language, depending + in C and registered as 'internal' or 'C' language, depending on whether it is linked into the backend or dynamically loaded. + The call handler cannot use the old-style 'C' function interface. @@ -306,6 +306,8 @@ ERROR: PL handler function funcname CREATE FUNCTION plsample_call_handler () RETURNS opaque AS '/usr/local/pgsql/lib/plsample.so' - LANGUAGE 'newC'; + LANGUAGE 'C'; CREATE PROCEDURAL LANGUAGE 'plsample' HANDLER plsample_call_handler LANCOMPILER 'PL/Sample'; diff --git a/doc/src/sgml/trigger.sgml b/doc/src/sgml/trigger.sgml index 0b3442517c9..d248887a599 100644 --- a/doc/src/sgml/trigger.sgml +++ b/doc/src/sgml/trigger.sgml @@ -22,7 +22,7 @@ The trigger function must be created before the trigger is created as a function taking no arguments and returning opaque. If the function is - written in C, it must follow the "new style" function manager interface. + written in C, it must use the "version 1" function manager interface. @@ -447,6 +447,8 @@ execution of Q) or after Q is done. extern Datum trigf(PG_FUNCTION_ARGS); +PG_FUNCTION_INFO_V1(trigf); + Datum trigf(PG_FUNCTION_ARGS) { @@ -513,7 +515,7 @@ trigf(PG_FUNCTION_ARGS) create function trigf () returns opaque as -'...path_to_so' language 'newC'; +'...path_to_so' language 'C'; create table ttest (x int4); diff --git a/doc/src/sgml/xfunc.sgml b/doc/src/sgml/xfunc.sgml index d02718d53a7..f2dc2981746 100644 --- a/doc/src/sgml/xfunc.sgml +++ b/doc/src/sgml/xfunc.sgml @@ -1,5 +1,5 @@ @@ -339,9 +339,9 @@ SELECT clean_EMP(); - There are two procedural languages available with the standard - Postgres distribution (PLTCL and PLSQL), and other - languages can be defined. + There are currently three procedural languages available in the standard + Postgres distribution (PLSQL, PLTCL and + PLPERL), and other languages can be defined. Refer to for more information. @@ -366,12 +366,7 @@ SELECT clean_EMP(); Internal functions are declared in CREATE FUNCTION - with language name internal or - newinternal, depending on whether they follow the - old (pre-7.1) or new (7.1 and later) function call conventions. - The details of the call conventions are the same as for - C and newC functions respectively; - see the next section for details. + with language name internal. @@ -404,9 +399,9 @@ SELECT clean_EMP(); The string which specifies the object file (the first string in the AS clause) should be the full path of the object - code file for the function, bracketed by quotation marks. If a + code file for the function, bracketed by single quote marks. If a link symbol is given in the AS clause, the link symbol should also be - bracketed by single quotation marks, and should be exactly the + bracketed by single quote marks, and should be exactly the same as the name of the function in the C source code. On Unix systems the command nm will print all of the link symbols in a dynamically loadable object. @@ -422,11 +417,11 @@ SELECT clean_EMP(); Two different calling conventions are currently used for C functions. - The "old style" (pre-Postgres-7.1) method - is selected by writing language name 'C' in the - CREATE FUNCTION command, while the "new style" - (7.1 and later) method is selecting by writing language name - 'newC'. Old-style functions are now deprecated + The newer "version 1" calling convention is indicated by writing + a PG_FUNCTION_INFO_V1() macro call for the function, + as illustrated below. Lack of such a macro indicates an old-style + ("version 0") function. The language name specified in CREATE FUNCTION + is 'C' in either case. Old-style functions are now deprecated because of portability problems and lack of functionality, but they are still supported for compatibility reasons. @@ -484,7 +479,7 @@ SELECT clean_EMP(); include/postgres.h - char + "char" char N/A @@ -583,16 +578,6 @@ SELECT clean_EMP(); TimeInterval utils/nabstime.h - - uint2 - uint16 - include/c.h - - - uint4 - uint32 - include/c.h - xid (XID *) @@ -694,7 +679,7 @@ typedef struct { - Obviously, the data field is not long enough to hold + Obviously, the data field shown here is not long enough to hold all possible strings; it's impossible to declare such a structure in C. When manipulating variable-length types, we must be careful to allocate @@ -721,12 +706,12 @@ memmove(destination->data, buffer, 40); - Old-style Calling Conventions for C-Language Functions + Version-0 Calling Conventions for C-Language Functions We present the "old style" calling convention first --- although this approach is now deprecated, it's easier to get a handle on - initially. In the "old style" method, the arguments and result + initially. In the version-0 method, the arguments and result of the C function are just declared in normal C style, but being careful to use the C representation of each SQL data type as shown above. @@ -854,26 +839,39 @@ CREATE FUNCTION concat_text(text, text) RETURNS text - Although this old-style calling convention is simple to use, + Although this calling convention is simple to use, it is not very portable; on some architectures there are problems with passing smaller-than-int data types this way. Also, there is no simple way to return a NULL result, nor to cope with NULL arguments - in any way other than making the function strict. The new-style + in any way other than making the function strict. The version-1 convention, presented next, overcomes these objections. - New-style Calling Conventions for C-Language Functions + Version-1 Calling Conventions for C-Language Functions - The new-style calling convention relies on macros to suppress most + The version-1 calling convention relies on macros to suppress most of the complexity of passing arguments and results. The C declaration - of a new-style function is always + of a version-1 function is always Datum funcname(PG_FUNCTION_ARGS) - Each actual argument is fetched using a PG_GETARG_xxx() macro that + In addition, the macro call + + PG_FUNCTION_INFO_V1(funcname); + + must appear in the same source file (conventionally it's written + just before the function itself). This macro call is not needed + for "internal"-language functions, since Postgres currently assumes + all internal functions are version-1. However, it is + required for dynamically-loaded functions. + + + + In a version-1 function, + each actual argument is fetched using a PG_GETARG_xxx() macro that corresponds to the argument's datatype, and the result is returned using a PG_RETURN_xxx() macro for the return type. @@ -887,6 +885,8 @@ CREATE FUNCTION concat_text(text, text) RETURNS text #include "fmgr.h" /* By Value */ + +PG_FUNCTION_INFO_V1(add_one); Datum add_one(PG_FUNCTION_ARGS) @@ -898,6 +898,8 @@ add_one(PG_FUNCTION_ARGS) /* By Reference, Fixed Length */ +PG_FUNCTION_INFO_V1(add_one_float8); + Datum add_one_float8(PG_FUNCTION_ARGS) { @@ -907,6 +909,8 @@ add_one_float8(PG_FUNCTION_ARGS) PG_RETURN_FLOAT8(arg + 1.0); } +PG_FUNCTION_INFO_V1(makepoint); + Datum makepoint(PG_FUNCTION_ARGS) { @@ -922,6 +926,8 @@ makepoint(PG_FUNCTION_ARGS) /* By Reference, Variable Length */ +PG_FUNCTION_INFO_V1(copytext); + Datum copytext(PG_FUNCTION_ARGS) { @@ -940,6 +946,8 @@ copytext(PG_FUNCTION_ARGS) PG_RETURN_TEXT_P(new_t); } +PG_FUNCTION_INFO_V1(concat_text); + Datum concat_text(PG_FUNCTION_ARGS) { @@ -959,12 +967,11 @@ concat_text(PG_FUNCTION_ARGS) The CREATE FUNCTION commands are the same as - for the old-style equivalents, except that the language is specified - as 'newC' not 'C'. + for the old-style equivalents. - At first glance, the new-style coding conventions may appear to be + At first glance, the version-1 coding conventions may appear to be just pointless obscurantism. However, they do offer a number of improvements, because the macros can hide unnecessary detail. An example is that in coding add_one_float8, we no longer need to @@ -973,11 +980,14 @@ concat_text(PG_FUNCTION_ARGS) to deal with fetching "toasted" (compressed or out-of-line) values. The old-style copytext and concat_text functions shown above are actually wrong in the presence of toasted values, because they don't - call pg_detoast_datum() on their inputs. + call pg_detoast_datum() on their inputs. (The handler for old-style + dynamically-loaded functions currently takes care of this detail, + but it does so less efficiently than is possible for a version-1 + function.) - The new-style function call conventions also make it possible to + The version-1 function call conventions also make it possible to test for NULL inputs to a non-strict function, return a NULL result (from either strict or non-strict functions), return "set" results, and implement trigger functions and procedural-language call handlers. @@ -1026,7 +1036,9 @@ c_overpaid(TupleTableSlot *t, /* the current instance of EMP */ return salary > limit; } -/* In new-style coding, the above would look like this: */ +/* In version-1 coding, the above would look like this: */ + +PG_FUNCTION_INFO_V1(c_overpaid); Datum c_overpaid(PG_FUNCTION_ARGS) -- cgit v1.2.3