8000 Remove support for version-0 calling conventions. · postgres/postgres@5ded4bd · GitHub
[go: up one dir, main page]
Skip to content

Commit 5ded4bd

Browse files
anarazelanarazel
committed
Remove support for version-0 calling conventions.
The V0 convention is failure prone because we've so far assumed that a function is V0 if PG_FUNCTION_INFO_V1 is missing, leading to crashes if a function was coded against the V1 interface. V0 doesn't allow proper NULL, SRF and toast handling. V0 doesn't offer features that V1 doesn't. Thus remove V0 support and obsolete fmgr README contents relating to it. Author: Andres Freund, with contributions by Peter Eisentraut & Craig Ringer Reviewed-By: Peter Eisentraut, Craig Ringer Discussion: https://postgr.es/m/20161208213441.k3mbno4twhg2qf7g@alap3.anarazel.de
1 parent 389bb28 commit 5ded4bd

File tree

10 files changed

+106
-911
lines changed

10 files changed

+106
-911
lines changed

‎contrib/earthdistance/earthdistance.c‎

Lines changed: 0 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -88,16 +88,8 @@ geo_distance_internal(Point *pt1, Point *pt2)
8888
*
8989
* returns: float8
9090
* distance between the points in miles on earth's surface
91-
*
92-
* If float8 is passed-by-value, the oldstyle version-0 calling convention
93-
* is unportable, so we use version-1. However, if it's passed-by-reference,
94-
* continue to use oldstyle. This is just because we'd like earthdistance
95-
* to serve as a canary for any unintentional breakage of version-0 functions
96-
* with float8 results.
9791
******************************************************/
9892

99-
#ifdef USE_FLOAT8_BYVAL
100-
10193
PG_FUNCTION_INFO_V1(geo_distance);
10294

10395< 8000 code class="diff-text syntax-highlighted-line">
Datum
@@ -110,17 +102,3 @@ geo_distance(PG_FUNCTION_ARGS)
110102
result = geo_distance_internal(pt1, pt2);
111103
PG_RETURN_FLOAT8(result);
112104
}
113-
#else /* !USE_FLOAT8_BYVAL */
114-
115-
double *geo_distance(Point *pt1, Point *pt2);
116-
117-
double *
118-
geo_distance(Point *pt1, Point *pt2)
119-
{
120-
double *resultp = palloc(sizeof(double));
121-
122-
*resultp = geo_distance_internal(pt1, pt2);
123-
return resultp;
124-
}
125-
126-
#endif /* USE_FLOAT8_BYVAL */

‎doc/src/sgml/xfunc.sgml‎

Lines changed: 63 additions & 206 deletions
Original file line numberDiff line numberDiff line change
@@ -1610,14 +1610,10 @@ CREATE FUNCTION square_root(double precision) RETURNS double precision
16101610
</para>
16111611

16121612
<para>
1613-
Two different calling conventions are currently used for C functions.
1614-
The newer <quote>version 1</quote> calling convention is indicated by writing
1615-
a <literal>PG_FUNCTION_INFO_V1()</literal> macro call for the function,
1616-
as illustrated below. Lack of such a macro indicates an old-style
1617-
(<quote>version 0</quote>) function. The language name specified in <command>CREATE FUNCTION</command>
1618-
is <literal>C</literal> in either case. Old-style functions are now deprecated
1619-
because of portability problems and lack of functionality, but they
1620-
are still supported for compatibility reasons.
1613+
Currently only one calling convention is used for C functions
1614+
(<quote>version 1</quote>). Support for that calling convention is
1615+
indicated by writing a <literal>PG_FUNCTION_INFO_V1()</literal> macro
1616+
call for the function, as illustrated below.
16211617
</para>
16221618

16231619
<sect2 id="xfunc-c-dynload">
@@ -2137,160 +2133,6 @@ memcpy(destination->data, buffer, 40);
21372133
</para>
21382134
</sect2>
21392135

2140-
<sect2>
2141-
<title>Version 0 Calling Conventions</title>
2142-
2143-
<para>
2144-
We present the <quote>old style</quote> calling convention first &mdash; although
2145-
this approach is now deprecated, it's easier to get a handle on
2146-
initially. In the version-0 method, the arguments and result
2147-
of the C function are just declared in normal C style, but being
2148-
careful to use the C representation of each SQL data type as shown
2149-
above.
2150-
</para>
2151-
2152-
<para>
2153-
Here are some examples:
2154-
2155-
<programlisting><![CDATA[
2156-
#include "postgres.h"
2157-
#include <string.h>
2158-
#include "utils/geo_decls.h"
2159-
2160-
#ifdef PG_MODULE_MAGIC
2161-
PG_MODULE_MAGIC;
2162-
#endif
2163-
2164-
/* by value */
2165-
2166-
int
2167-
add_one(int arg)
2168-
{
2169-
return arg + 1;
2170-
}
2171-
2172-
/* by reference, fixed length */
2173-
2174-
float8 *
2175-
add_one_float8(float8 *arg)
2176-
{
2177-
float8 *result = (float8 *) palloc(sizeof(float8));
2178-
2179-
*result = *arg + 1.0;
2180-
2181-
return result;
2182-
}
2183-
2184-
Point *
2185-
makepoint(Point *pointx, Point *pointy)
2186-
{
2187-
Point *new_point = (Point *) palloc(sizeof(Point));
2188-
2189-
new_point->x = pointx->x;
2190-
new_point->y = pointy->y;
2191-
2192-
return new_point;
2193-
}
2194-
2195-
/* by reference, variable length */
2196-
2197-
text *
2198-
copytext(text *t)
2199-
{
2200-
/*
2201-
* VARSIZE is the total size of the struct in bytes.
2202-
*/
2203-
text *new_t = (text *) palloc(VARSIZE(t));
2204-
SET_VARSIZE(new_t, VARSIZE(t));
2205-
/*
2206-
* VARDATA is a pointer to the data region of the struct.
2207-
*/
2208-
memcpy((void *) VARDATA(new_t), /* destination */
2209-
(void *) VARDATA(t), /* source */
2210-
VARSIZE(t) - VARHDRSZ); /* how many bytes */
2211-
return new_t;
2212-
}
2213-
2214-
text *
2215-
concat_text(text *arg1, text *arg2)
2216-
{
2217-
int32 new_text_size = VARSIZE(arg1) + VARSIZE(arg2) - VARHDRSZ;
2218-
text *new_text = (text *) palloc(new_text_size);
2219-
2220-
SET_VARSIZE(new_text, new_text_size);
2221-
memcpy(VARDATA(new_text), VARDATA(arg1), VARSIZE(arg1) - VARHDRSZ);
2222-
memcpy(VARDATA(new_text) + (VARSIZE(arg1) - VARHDRSZ),
2223-
VARDATA(arg2), VARSIZE(arg2) - VARHDRSZ);
2224-
return new_text;
2225-
}
2226-
]]>
2227-
</programlisting>
2228-
</para>
2229-
2230-
<para>
2231-
Supposing that the above code has been prepared in file
2232-
<filename>funcs.c</filename> and compiled into a shared object,
2233-
we could define the functions to <productname>PostgreSQL</productname>
2234-
with commands like this:
2235-
2236-
<programlisting>
2237-
CREATE FUNCTION add_one(integer) RETURNS integer
2238-
AS '<replaceable>DIRECTORY</replaceable>/funcs', 'add_one'
2239-
LANGUAGE C STRICT;
2240-
2241-
-- note overloading of SQL function name "add_one"
2242-
CREATE FUNCTION add_one(double precision) RETURNS double precision
2243-
AS '<replaceable>DIRECTORY</replaceable>/funcs', 'add_one_float8'
2244-
LANGUAGE C STRICT;
2245-
2246-
CREATE FUNCTION makepoint(point, point) RETURNS point
2247-
AS '<replaceable>DIRECTORY</replaceable>/funcs', 'makepoint'
2248-
LANGUAGE C STRICT;
2249-
2250-
CREATE FUNCTION copytext(text) RETURNS text
2251-
AS '<replaceable>DIRECTORY</replaceable>/funcs', 'copytext'
2252-
LANGUAGE C STRICT;
2253-
2254-
CREATE FUNCTION concat_text(text, text) RETURNS text
2255-
AS '<replaceable>DIRECTORY</replaceable>/funcs', 'concat_text'
2256-
LANGUAGE C STRICT;
2257-
</programlisting>
2258-
</para>
2259-
2260-
<para>
2261-
Here, <replaceable>DIRECTORY</replaceable> stands for the
2262-
directory of the shared library file (for instance the
2263-
<productname>PostgreSQL</productname> tutorial directory, which
2264-
contains the code for the examples used in this section).
2265-
(Better style would be to use just <literal>'funcs'</> in the
2266-
<literal>AS</> clause, after having added
2267-
<replaceable>DIRECTORY</replaceable> to the search path. In any
2268-
case, we can omit the system-specific extension for a shared
2269-
library, commonly <literal>.so</literal> or
2270-
<literal>.sl</literal>.)
2271-
</para>
2272-
2273-
<para>
2274-
Notice that we have specified the functions as <quote>strict</quote>,
2275-
meaning that
2276-
the system should automatically assume a null result if any input
2277-
value is null. By doing this, we avoid having to check for null inputs
2278-
in the function code. Without this, we'd have to check for null values
2279-
explicitly, by checking for a null pointer for each
2280-
pass-by-reference argument. (For pass-by-value arguments, we don't
2281-
even have a way to check!)
2282-
</para>
2283-
2284-
<para>
2285-
Although this calling convention is simple to use,
2286-
it is not very portable; on some architectures there are problems
2287-
with passing data types that are smaller than <type>int</type> this way. Also, there is
2288-
no simple way to return a null result, nor to cope with null arguments
2289-
in any way other than making the function strict. The version-1
2290-
convention, presented next, overcomes these objections.
2291-
</para>
2292-
</sect2>
2293-
22942136
<sect2>
22952137
<title>Version 1 Calling Conventions</title>
22962138

@@ -2316,8 +2158,10 @@ PG_FUNCTION_INFO_V1(funcname);
23162158
<para>
23172159
In a version-1 function, each actual argument is fetched using a
23182160
<function>PG_GETARG_<replaceable>xxx</replaceable>()</function>
2319-
macro that corresponds to the argument's data type, and the
2320-
result is returned using a
2161+
macro that corresponds to the argument's data type. In non-strict
2162+
functions there needs to be a previous check about argument null-ness
2163+
using <function>PG_ARGNULL_<replaceable>xxx</replaceable>()</function>.
2164+
The result is returned using a
23212165
<function>PG_RETURN_<replaceable>xxx</replaceable>()</function>
23222166
macro for the return type.
23232167
<function>PG_GETARG_<replaceable>xxx</replaceable>()</function>
@@ -2328,7 +2172,7 @@ PG_FUNCTION_INFO_V1(funcname);
23282172
</para>
23292173

23302174
<para>
2331-
Here we show the same functions as above, coded in version-1 style:
2175+
Here are some examples using the version-1 calling convention:
23322176

23332177
<programlisting><![CDATA[
23342178
#include "postgres.h"
@@ -2427,27 +2271,67 @@ concat_text(PG_FUNCTION_ARGS)
24272271
}
24282272
]]>
24292273
</programlisting>
2274+
2275+
<para>
2276+
Supposing that the above code has been prepared in file
2277+
<filename>funcs.c</filename> and compiled into a shared object,
2278+
we could define the functions to <productname>PostgreSQL</productname>
2279+
with commands like this:
2280+
2281+
<programlisting>
2282+
CREATE FUNCTION add_one(integer) RETURNS integer
2283+
AS '<replaceable>DIRECTORY</replaceable>/funcs', 'add_one'
2284+
LANGUAGE C STRICT;
2285+
2286+
-- note overloading of SQL function name "add_one"
2287+
CREATE FUNCTION add_one(double precision) RETURNS double precision
2288+
AS '<replaceable>DIRECTORY</replaceable>/funcs', 'add_one_float8'
2289+
LANGUAGE C STRICT;
2290+
2291+
CREATE FUNCTION makepoint(point, point) RETURNS point
2292+
AS '<replaceable>DIRECTORY</replaceable>/funcs', 'makepoint'
2293+
LANGUAGE C STRICT;
2294+
2295+
CREATE FUNCTION copytext(text) RETURNS text
2296+
AS '<replaceable>DIRECTORY</replaceable>/funcs', 'copytext'
2297+
LANGUAGE C STRICT;
2298+
2299+
CREATE FUNCTION concat_text(text, text) RETURNS text
2300+
AS '<replaceable>DIRECTORY</replaceable>/funcs', 'concat_text'
2301+
LANGUAGE C STRICT;
2302+
</programlisting>
2303+
2304+
<para>
2305+
Here, <replaceable>DIRECTORY</replaceable> stands for the
2306+
directory of the shared library file (for instance the
2307+
<productname>PostgreSQL</productname> tutorial directory, which
2308+
contains the code for the examples used in this section).
2309+
(Better style would be to use just <literal>'funcs'</> in the
2310+
<literal>AS</> clause, after having added
2311+
<replaceable>DIRECTORY</replaceable> to the search path. In any
2312+
case, we can omit the system-specific extension for a shared
2313+
library, commonly <literal>.so</literal>.)
24302314
</para>
24312315

24322316
<para>
2433-
The <command>CREATE FUNCTION</command> commands are the same as
2434-
for the version-0 equivalents.
2317+
Notice that we have specified the functions as <quote>strict</quote>,
2318+
meaning that
2319+
the system should automatically assume a null result if any input
2320+
value is null. By doing this, we avoid having to check for null inputs
2321+
in the function code. Without this, we'd have to check for null values
2322+
explicitly, using PG_ARGISNULL().
24352323
</para>
24362324

24372325
<para>
2438-
At first glance, the version-1 coding conventions might appear to
2439-
be just pointless obscurantism. They do, however, offer a number
2440-
of improvements, because the macros can hide unnecessary detail.
2441-
An example is that in coding <function>add_one_float8</>, we no longer need to
2442-
be aware that <type>float8</type> is a pass-by-reference type. Another
2443-
example is that the <literal>GETARG</> macros for variable-length types allow
2444-
for more efficient fetching of <quote>toasted</quote> (compressed or
2326+
At first glance, the version-1 coding conventions might appear to be just
2327+
pointless obscurantism, over using plain <literal>C</> calling
2328+
conventions. They do however allow to deal with <literal>NULL</>able
2329+
arguments/return values, and <quote>toasted</quote> (compressed or
24452330
out-of-line) values.
24462331
</para>
24472332

24482333
<para>
2449-
One big improvement in version-1 functions is better handling of null
2450-
inputs and results. The macro <function>PG_ARGISNULL(<replaceable>n</>)</function>
2334+
The macro <function>PG_ARGISNULL(<replaceable>n</>)</function>
24512335
allows a function to test whether each input is null. (Of course, doing
24522336
this is only necessary in functions not declared <quote>strict</>.)
24532337
As with the
@@ -2461,7 +2345,7 @@ concat_text(PG_FUNCTION_ARGS)
24612345
</para>
24622346

24632347
<para>
2464-
Other options provided in the new-style interface are two
2348+
Other options provided by the version-1 interface are two
24652349
variants of the
24662350
<function>PG_GETARG_<replaceable>xxx</replaceable>()</function>
24672351
macros. The first of these,
@@ -2493,9 +2377,7 @@ concat_text(PG_FUNCTION_ARGS)
24932377
to return set results (<xref linkend="xfunc-c-return-set">) and
24942378
implement trigger functions (<xref linkend="triggers">) and
24952379
procedural-language call handlers (<xref
2496-
linkend="plhandler">). Version-1 code is also more
2497-
portable than version-0, because it does not break restrictions
2498-
on function call protocol in the C standard. For more details
2380+
linkend="plhandler">). For more details
24992381
see <filename>src/backend/utils/fmgr/README</filename> in the
25002382
source distribution.
25012383
</para>
@@ -2630,7 +2512,7 @@ SELECT name, c_overpaid(emp, 1500) AS overpaid
26302512
WHERE name = 'Bill' OR name = 'Sam';
26312513
</programlisting>
26322514

2633-
Using call conventions version 0, we can define
2515+
Using the version-1 calling conventions, we can define
26342516
<function>c_overpaid</> as:
26352517

26362518
<programlisting><![CDATA[
@@ -2641,31 +2523,6 @@ SELECT name, c_overpaid(emp, 1500) AS overpaid
26412523
PG_MODULE_MAGIC;
26422524
#endif
26432525

2644-
bool
2645-
c_overpaid(HeapTupleHeader t, /* the current row of emp */
2646-
int32 limit)
2647-
{
2648-
bool isnull;
2649-
int32 salary;
2650-
2651-
salary = DatumGetInt32(GetAttributeByName(t, "salary", &isnull));
2652-
if (isnull)
2653-
return false;
2654-
return salary > limit;
2655-
}
2656-
]]>
2657-
</programlisting>
2658-
2659-
In version-1 coding, the above would look like this:
2660-
2661-
<programlisting><![CDATA[
2662-
#include "postgres.h"
2663-
#include "executor/executor.h" /* for GetAttributeByName() */
2664-
2665-
#ifdef PG_MODULE_MAGIC
2666-
PG_MODULE_MAGIC;
2667-
#endif
2668-
26692526
PG_FUNCTION_INFO_V1(c_overpaid);
26702527

26712528
Datum

0 commit comments

Comments
 (0)
0