Location via proxy:   [ UP ]  
[Report a bug]   [Manage cookies]                
Skip to content

Commit 1fb57af

Browse files
tglsfdctglsfdc
committed
Create the infrastructure for planner support functions.
Rename/repurpose pg_proc.protransform as "prosupport". The idea is still that it names an internal function that provides knowledge to the planner about the behavior of the function it's attached to; but redesign the API specification so that it's not limited to doing just one thing, but can support an extensible set of requests. The original purpose of simplifying a function call is handled by the first request type to be invented, SupportRequestSimplify. Adjust all the existing transform functions to handle this API, and rename them fron "xxx_transform" to "xxx_support" to reflect the potential generalization of what they do. (Since we never previously provided any way for extensions to add transform functions, this change doesn't create an API break for them.) Also add DDL and pg_dump support for attaching a support function to a user-defined function. Unfortunately, DDL access has to be restricted to superusers, at least for now; but seeing that support functions will pretty much have to be written in C, that limitation is just theoretical. (This support is untested in this patch, but a follow-on patch will add cases that exercise it.) Discussion: https://postgr.es/m/15193.1548028093@sss.pgh.pa.us
1 parent 1a8d5af commit 1fb57af

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

41 files changed

+698
-294
lines changed

‎doc/src/sgml/catalogs.sgml

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5146,11 +5146,11 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
51465146
</row>
51475147

51485148
<row>
5149-
<entry><structfield>protransform</structfield></entry>
5149+
<entry><structfield>prosupport</structfield></entry>
51505150
<entry><type>regproc</type></entry>
51515151
<entry><literal><link linkend="catalog-pg-proc"><structname>pg_proc</structname></link>.oid</literal></entry>
5152-
<entry>Calls to this function can be simplified by this other function
5153-
(see <xref linkend="xfunc-transform-functions"/>)</entry>
5152+
<entry>Optional planner support function for this function
5153+
(see <xref linkend="xfunc-optimization"/>)</entry>
51545154
</row>
51555155

51565156
<row>

‎doc/src/sgml/keywords.sgml

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4521,6 +4521,13 @@
45214521
<entry>reserved</entry>
45224522
<entry>reserved</entry>
45234523
</row>
4524+
<row>
4525+
<entry><token>SUPPORT</token></entry>
4526+
<entry>non-reserved</entry>
4527+
<entry></entry>
4528+
<entry></entry>
4529+
<entry></entry>
4530+
</row>
45244531
<row>
45254532
<entry><token>SYMMETRIC</token></entry>
45264533
<entry>reserved</entry>

‎doc/src/sgml/ref/alter_function.sgml

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,7 @@ ALTER FUNCTION <replaceable>name</replaceable> [ ( [ [ <replaceable class="param
4040
PARALLEL { UNSAFE | RESTRICTED | SAFE }
4141
COST <replaceable class="parameter">execution_cost</replaceable>
4242
ROWS <replaceable class="parameter">result_rows</replaceable>
43+
SUPPORT <replaceable class="parameter">support_function</replaceable>
4344
SET <replaceable class="parameter">configuration_parameter</replaceable> { TO | = } { <replaceable class="parameter">value</replaceable> | DEFAULT }
4445
SET <replaceable class="parameter">configuration_parameter</replaceable> FROM CURRENT
4546
RESET <replaceable class="parameter">configuration_parameter</replaceable>
@@ -248,6 +249,24 @@ ALTER FUNCTION <replaceable>name</replaceable> [ ( [ [ <replaceable class="param
248249
</listitem>
249250
</varlistentry>
250251

252+
<varlistentry>
253+
<term><literal>SUPPORT</literal> <replaceable class="parameter">support_function</replaceable></term>
254+
255+
<listitem>
256+
<para>
257+
Set or change the planner support function to use for this function.
258+
See <xref linkend="xfunc-optimization"/> for details. You must be
259+
superuser to use this option.
260+
</para>
261+
262+
<para>
263+
This option cannot be used to remove the support function altogether,
264+
since it must name a new support function. Use <command>CREATE OR
265+
REPLACE FUNCTION</command> if you need to do that.
266+
</para>
267+
</listitem>
268+
</varlistentry>
269+
251270
<varlistentry>
252271
<term><replaceable>configuration_parameter</replaceable></term>
253272
<term><replaceable>value</replaceable></term>

‎doc/src/sgml/ref/create_function.sgml

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,7 @@ CREATE [ OR REPLACE ] FUNCTION
3333
| PARALLEL { UNSAFE | RESTRICTED | SAFE }
3434
| COST <replaceable class="parameter">execution_cost</replaceable>
3535
| ROWS <replaceable class="parameter">result_rows</replaceable>
36+
| SUPPORT <replaceable class="parameter">support_function</replaceable>
3637
| SET <replaceable class="parameter">configuration_parameter</replaceable> { TO <replaceable class="parameter">value</replaceable> | = <replaceable class="parameter">value</replaceable> | FROM CURRENT }
3738
| AS '<replaceable class="parameter">definition</replaceable>'
3839
| AS '<replaceable class="parameter">obj_file</replaceable>', '<replaceable class="parameter">link_symbol</replaceable>'
@@ -477,6 +478,19 @@ CREATE [ OR REPLACE ] FUNCTION
477478
</listitem>
478479
</varlistentry>
479480

481+
<varlistentry>
482+
<term><literal>SUPPORT</literal> <replaceable class="parameter">support_function</replaceable></term>
483+
484+
<listitem>
485+
<para>
486+
The name (optionally schema-qualified) of a <firstterm>planner support
487+
function</firstterm> to use for this function. See
488+
<xref linkend="xfunc-optimization"/> for details.
489+
You must be superuser to use this option.
490+
</para>
491+
</listitem>
492+
</varlistentry>
493+
480494
<varlistentry>
481495
<term><replaceable>configuration_parameter</replaceable></term>
482496
<term><replaceable>value</replaceable></term>

‎doc/src/sgml/xfunc.sgml

Lines changed: 86 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -3241,40 +3241,6 @@ CREATE FUNCTION make_array(anyelement) RETURNS anyarray
32413241
</para>
32423242
</sect2>
32433243

3244-
<sect2 id="xfunc-transform-functions">
3245-
<title>Transform Functions</title>
3246-
3247-
<para>
3248-
Some function calls can be simplified during planning based on
3249-
properties specific to the function. For example,
3250-
<literal>int4mul(n, 1)</literal> could be simplified to just <literal>n</literal>.
3251-
To define such function-specific optimizations, write a
3252-
<firstterm>transform function</firstterm> and place its OID in the
3253-
<structfield>protransform</structfield> field of the primary function's
3254-
<structname>pg_proc</structname> entry. The transform function must have the SQL
3255-
signature <literal>protransform(internal) RETURNS internal</literal>. The
3256-
argument, actually <type>FuncExpr *</type>, is a dummy node representing a
3257-
call to the primary function. If the transform function's study of the
3258-
expression tree proves that a simplified expression tree can substitute
3259-
for all possible concrete calls represented thereby, build and return
3260-
that simplified expression. Otherwise, return a <literal>NULL</literal>
3261-
pointer (<emphasis>not</emphasis> a SQL null).
3262-
</para>
3263-
3264-
<para>
3265-
We make no guarantee that <productname>PostgreSQL</productname> will never call the
3266-
primary function in cases that the transform function could simplify.
3267-
Ensure rigorous equivalence between the simplified expression and an
3268-
actual call to the primary function.
3269-
</para>
3270-
3271-
<para>
3272-
Currently, this facility is not exposed to users at the SQL level
3273-
because of security concerns, so it is only practical to use for
3274-
optimizing built-in functions.
3275-
</para>
3276-
</sect2>
3277-
32783244
<sect2>
32793245
<title>Shared Memory and LWLocks</title>
32803246

@@ -3388,3 +3354,89 @@ if (!ptr)
33883354
</sect2>
33893355

33903356
</sect1>
3357+
3358+
<sect1 id="xfunc-optimization">
3359+
<title>Function Optimization Information</title>
3360+
3361+
<indexterm zone="xfunc-optimization">
3362+
<primary>optimization information</primary>
3363+
<secondary>for functions</secondary>
3364+
</indexterm>
3365+
3366+
<para>
3367+
By default, a function is just a <quote>black box</quote> that the
3368+
database system knows very little about the behavior of. However,
3369+
that means that queries using the function may be executed much less
3370+
efficiently than they could be. It is possible to supply additional
3371+
knowledge that helps the planner optimize function calls.
3372+
</para>
3373+
3374+
<para>
3375+
Some basic facts can be supplied by declarative annotations provided in
3376+
the <xref linkend="sql-createfunction"/> command. Most important of
3377+
these is the function's <link linkend="xfunc-volatility">volatility
3378+
category</link> (<literal>IMMUTABLE</literal>, <literal>STABLE</literal>,
3379+
or <literal>VOLATILE</literal>); one should always be careful to
3380+
specify this correctly when defining a function.
3381+
The parallel safety property (<literal>PARALLEL
3382+
UNSAFE</literal>, <literal>PARALLEL RESTRICTED</literal>, or
3383+
<literal>PARALLEL SAFE</literal>) must also be specified if you hope
3384+
to use the function in parallelized queries.
3385+
It can also be useful to specify the function's estimated execution
3386+
cost, and/or the number of rows a set-returning function is estimated
3387+
to return. However, the declarative way of specifying those two
3388+
facts only allows specifying a constant value, which is often
3389+
inadequate.
3390+
</para>
3391+
3392+
<para>
3393+
It is also possible to attach a <firstterm>planner support
3394+
function</firstterm> to a SQL-callable function (called
3395+
its <firstterm>target function</firstterm>), and thereby provide
3396+
knowledge about the target function that is too complex to be
3397+
represented declaratively. Planner support functions have to be
3398+
written in C (although their target functions might not be), so this is
3399+
an advanced feature that relatively few people will use.
3400+
</para>
3401+
3402+
<para>
3403+
A planner support function must have the SQL signature
3404+
<programlisting>
3405+
supportfn(internal) returns internal
3406+
</programlisting>
3407+
It is attached to its target function by specifying
3408+
the <literal>SUPPORT</literal> clause when creating the target function.
3409+
</para>
3410+
3411+
<para>
3412+
The details of the API for planner support functions can be found in
3413+
file <filename>src/include/nodes/supportnodes.h</filename> in the
3414+
<productname>PostgreSQL</productname> source code. Here we provide
3415+
just an overview of what planner support functions can do.
3416+
The set of possible requests to a support function is extensible,
3417+
so more things might be possible in future versions.
3418+
</para>
3419+
3420+
<para>
3421+
Some function calls can be simplified during planning based on
3422+
properties specific to the function. For example,
3423+
<literal>int4mul(n, 1)</literal> could be simplified to
3424+
just <literal>n</literal>. This type of transformation can be
3425+
performed by a planner support function, by having it implement
3426+
the <literal>SupportRequestSimplify</literal> request type.
3427+
The support function will be called for each instance of its target
3428+
function found in a query parse tree. If it finds that the particular
3429+
call can be simplified into some other form, it can build and return a
3430+
parse tree representing that expression. This will automatically work
3431+
for operators based on the function, too &mdash; in the example just
3432+
given, <literal>n * 1</literal> would also be simplified to
3433+
<literal>n</literal>.
3434+
(But note that this is just an example; this particular
3435+
optimization is not actually performed by
3436+
standard <productname>PostgreSQL</productname>.)
3437+
We make no guarantee that <productname>PostgreSQL</productname> will
3438+
never call the target function in cases that the support function could
3439+
simplify. Ensure rigorous equivalence between the simplified
3440+
expression and an actual execution of the target function.
3441+
</para>
3442+
</sect1>

‎doc/src/sgml/xoper.sgml

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -78,6 +78,11 @@ SELECT (a + b) AS c FROM test_complex;
7878
<sect1 id="xoper-optimization">
7979
<title>Operator Optimization Information</title>
8080

81+
<indexterm zone="xoper-optimization">
82+
<primary>optimization information</primary>
83+
<secondary>for operators</secondary>
84+
</indexterm>
85+
8186
<para>
8287
A <productname>PostgreSQL</productname> operator definition can include
8388
several optional clauses that tell the system useful things about how
@@ -97,6 +102,13 @@ SELECT (a + b) AS c FROM test_complex;
97102
the ones that release &version; understands.
98103
</para>
99104

105+
<para>
106+
It is also possible to attach a planner support function to the function
107+
that underlies an operator, providing another way of telling the system
108+
about the behavior of the operator.
109+
See <xref linkend="xfunc-optimization"/> for more information.
110+
</para>
111+
100112
<sect2>
101113
<title><literal>COMMUTATOR</literal></title>
102114

‎src/backend/catalog/pg_aggregate.c

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -632,6 +632,7 @@ AggregateCreate(const char *aggName,
632632
parameterDefaults, /* parameterDefaults */
633633
PointerGetDatum(NULL), /* trftypes */
634634
PointerGetDatum(NULL), /* proconfig */
635+
InvalidOid, /* no prosupport */
635636
1, /* procost */
636637
0); /* prorows */
637638
procOid = myself.objectId;

‎src/backend/catalog/pg_depend.c

Lines changed: 36 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -286,9 +286,12 @@ deleteDependencyRecordsForClass(Oid classId, Oid objectId,
286286
* newRefObjectId is the new referenced object (must be of class refClassId).
287287
*
288288
* Note the lack of objsubid parameters. If there are subobject references
289-
* they will all be readjusted.
289+
* they will all be readjusted. Also, there is an expectation that we are
290+
* dealing with NORMAL dependencies: if we have to replace an (implicit)
291+
* dependency on a pinned object with an explicit dependency on an unpinned
292+
* one, the new one will be NORMAL.
290293
*
291-
* Returns the number of records updated.
294+
* Returns the number of records updated -- zero indicates a problem.
292295
*/
293296
long
294297
changeDependencyFor(Oid classId, Oid objectId,
@@ -301,35 +304,52 @@ changeDependencyFor(Oid classId, Oid objectId,
301304
SysScanDesc scan;
302305
HeapTuple tup;
303306
ObjectAddress objAddr;
307+
ObjectAddress depAddr;
308+
bool oldIsPinned;
304309
bool newIsPinned;
305310

306311
depRel = table_open(DependRelationId, RowExclusiveLock);
307312

308313
/*
309-
* If oldRefObjectId is pinned, there won't be any dependency entries on
310-
* it --- we can't cope in that case. (This isn't really worth expending
311-
* code to fix, in current usage; it just means you can't rename stuff out
312-
* of pg_catalog, which would likely be a bad move anyway.)
314+
* Check to see if either oldRefObjectId or newRefObjectId is pinned.
315+
* Pinned objects should not have any dependency entries pointing to them,
316+
* so in these cases we should add or remove a pg_depend entry, or do
317+
* nothing at all, rather than update an entry as in the normal case.
313318
*/
314319
objAddr.classId = refClassId;
315320
objAddr.objectId = oldRefObjectId;
316321
objAddr.objectSubId = 0;
317322

318-
if (isObjectPinned(&objAddr, depRel))
319-
ereport(ERROR,
320-
(errcode(ERRCODE_FEATURE_NOT_SUPPORTED),
321-
errmsg("cannot remove dependency on %s because it is a system object",
322-
getObjectDescription(&objAddr))));
323+
oldIsPinned = isObjectPinned(&objAddr, depRel);
323324

324-
/*
325-
* We can handle adding a dependency on something pinned, though, since
326-
* that just means deleting the dependency entry.
327-
*/
328325
objAddr.objectId = newRefObjectId;
329326

330327
newIsPinned = isObjectPinned(&objAddr, depRel);
331328

332-
/* Now search for dependency records */
329+
if (oldIsPinned)
330+
{
331+
table_close(depRel, RowExclusiveLock);
332+
333+
/*
334+
* If both are pinned, we need do nothing. However, return 1 not 0,
335+
* else callers will think this is an error case.
336+
*/
337+
if (newIsPinned)
338+
return 1;
339+
340+
/*
341+
* There is no old dependency record, but we should insert a new one.
342+
* Assume a normal dependency is wanted.
343+
*/
344+
depAddr.classId = classId;
345+
depAddr.objectId = objectId;
346+
depAddr.objectSubId = 0;
347+
recordDependencyOn(&depAddr, &objAddr, DEPENDENCY_NORMAL);
348+
349+
return 1;
350+
}
351+
352+
/* There should be existing dependency record(s), so search. */
333353
ScanKeyInit(&key[0],
334354
Anum_pg_depend_classid,
335355
BTEqualStrategyNumber, F_OIDEQ,

‎src/backend/catalog/pg_proc.c

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -88,6 +88,7 @@ ProcedureCreate(const char *procedureName,
8888
List *parameterDefaults,
8989
Datum trftypes,
9090
Datum proconfig,
91+
Oid prosupport,
9192
float4 procost,
9293
float4 prorows)
9394
{
@@ -319,7 +320,7 @@ ProcedureCreate(const char *procedureName,
319320
values[Anum_pg_proc_procost - 1] = Float4GetDatum(procost);
320321
values[Anum_pg_proc_prorows - 1] = Float4GetDatum(prorows);
321322
values[Anum_pg_proc_provariadic - 1] = ObjectIdGetDatum(variadicType);
322-
values[Anum_pg_proc_protransform - 1] = ObjectIdGetDatum(InvalidOid);
323+
values[Anum_pg_proc_prosupport - 1] = ObjectIdGetDatum(prosupport);
323324
values[Anum_pg_proc_prokind - 1] = CharGetDatum(prokind);
324325
values[Anum_pg_proc_prosecdef - 1] = BoolGetDatum(security_definer);
325326
values[Anum_pg_proc_proleakproof - 1] = BoolGetDatum(isLeakProof);
@@ -656,6 +657,15 @@ ProcedureCreate(const char *procedureName,
656657
recordDependencyOnExpr(&myself, (Node *) parameterDefaults,
657658
NIL, DEPENDENCY_NORMAL);
658659

660+
/* dependency on support function, if any */
661+
if (OidIsValid(prosupport))
662+
{
663+
referenced.classId = ProcedureRelationId;
664+
referenced.objectId = prosupport;
665+
referenced.objectSubId = 0;
666+
recordDependencyOn(&myself, &referenced, DEPENDENCY_NORMAL);
667+
}
668+
659669
/* dependency on owner */
660670
if (!is_update)
661671
recordDependencyOnOwner(ProcedureRelationId, retval, proowner);

0 commit comments

Comments
 (0)