| 1 |
<!-- doc/src/sgml/plhandler.sgml --> |
| 2 |
|
| 3 |
<chapter id="plhandler"> |
| 4 |
<title>Writing a Procedural Language Handler</title> |
| 5 |
|
| 6 |
<indexterm zone="plhandler"> |
| 7 |
<primary>procedural language</primary> |
| 8 |
<secondary>handler for</secondary> |
| 9 |
</indexterm> |
| 10 |
|
| 11 |
<para> |
| 12 |
All calls to functions that are written in a language other than |
| 13 |
the current <quote>version 1</quote> interface for compiled |
| 14 |
languages (this includes functions in user-defined procedural languages |
| 15 |
and functions written in SQL) go through a <firstterm>call handler</firstterm> |
| 16 |
function for the specific language. It is the responsibility of |
| 17 |
the call handler to execute the function in a meaningful way, such |
| 18 |
as by interpreting the supplied source text. This chapter outlines |
| 19 |
how a new procedural language's call handler can be written. |
| 20 |
</para> |
| 21 |
|
| 22 |
<para> |
| 23 |
The call handler for a procedural language is a |
| 24 |
<quote>normal</quote> function that must be written in a compiled |
| 25 |
language such as C, using the version-1 interface, and registered |
| 26 |
with <productname>PostgreSQL</productname> as taking no arguments |
| 27 |
and returning the type <type>language_handler</type>. This |
| 28 |
special pseudo-type identifies the function as a call handler and |
| 29 |
prevents it from being called directly in SQL commands. |
| 30 |
For more details on C language calling conventions and dynamic loading, |
| 31 |
see <xref linkend="xfunc-c"/>. |
| 32 |
</para> |
| 33 |
|
| 34 |
<para> |
| 35 |
The call handler is called in the same way as any other function: |
| 36 |
It receives a pointer to a |
| 37 |
<structname>FunctionCallInfoBaseData</structname> <type>struct</type> containing |
| 38 |
argument values and information about the called function, and it |
| 39 |
is expected to return a <type>Datum</type> result (and possibly |
| 40 |
set the <structfield>isnull</structfield> field of the |
| 41 |
<structname>FunctionCallInfoBaseData</structname> structure, if it wishes |
| 42 |
to return an SQL null result). The difference between a call |
| 43 |
handler and an ordinary callee function is that the |
| 44 |
<structfield>flinfo->fn_oid</structfield> field of the |
| 45 |
<structname>FunctionCallInfoBaseData</structname> structure will contain |
| 46 |
the OID of the actual function to be called, not of the call |
| 47 |
handler itself. The call handler must use this field to determine |
| 48 |
which function to execute. Also, the passed argument list has |
| 49 |
been set up according to the declaration of the target function, |
| 50 |
not of the call handler. |
| 51 |
</para> |
| 52 |
|
| 53 |
<para> |
| 54 |
It's up to the call handler to fetch the entry of the function from the |
| 55 |
<classname>pg_proc</classname> system catalog and to analyze the argument |
| 56 |
and return types of the called function. The <literal>AS</literal> clause from the |
| 57 |
<command>CREATE FUNCTION</command> command for the function will be found |
| 58 |
in the <literal>prosrc</literal> column of the |
| 59 |
<classname>pg_proc</classname> row. This is commonly source |
| 60 |
text in the procedural language, but in theory it could be something else, |
| 61 |
such as a path name to a file, or anything else that tells the call handler |
| 62 |
what to do in detail. |
| 63 |
</para> |
| 64 |
|
| 65 |
<para> |
| 66 |
Often, the same function is called many times per SQL statement. |
| 67 |
A call handler can avoid repeated lookups of information about the |
| 68 |
called function by using the |
| 69 |
<structfield>flinfo->fn_extra</structfield> field. This will |
| 70 |
initially be <symbol>NULL</symbol>, but can be set by the call handler to point at |
| 71 |
information about the called function. On subsequent calls, if |
| 72 |
<structfield>flinfo->fn_extra</structfield> is already non-<symbol>NULL</symbol> |
| 73 |
then it can be used and the information lookup step skipped. The |
| 74 |
call handler must make sure that |
| 75 |
<structfield>flinfo->fn_extra</structfield> is made to point at |
| 76 |
memory that will live at least until the end of the current query, |
| 77 |
since an <structname>FmgrInfo</structname> data structure could be |
| 78 |
kept that long. One way to do this is to allocate the extra data |
| 79 |
in the memory context specified by |
| 80 |
<structfield>flinfo->fn_mcxt</structfield>; such data will |
| 81 |
normally have the same lifespan as the |
| 82 |
<structname>FmgrInfo</structname> itself. But the handler could |
| 83 |
also choose to use a longer-lived memory context so that it can cache |
| 84 |
function definition information across queries. |
| 85 |
</para> |
| 86 |
|
| 87 |
<para> |
| 88 |
When a procedural-language function is invoked as a trigger, no arguments |
| 89 |
are passed in the usual way, but the |
| 90 |
<structname>FunctionCallInfoBaseData</structname>'s |
| 91 |
<structfield>context</structfield> field points at a |
| 92 |
<structname>TriggerData</structname> structure, rather than being <symbol>NULL</symbol> |
| 93 |
as it is in a plain function call. A language handler should |
| 94 |
provide mechanisms for procedural-language functions to get at the trigger |
| 95 |
information. |
| 96 |
</para> |
| 97 |
|
| 98 |
<para> |
| 99 |
A template for a procedural-language handler written as a C extension is |
| 100 |
provided in <literal>src/test/modules/plsample</literal>. This is a |
| 101 |
working sample demonstrating one way to create a procedural-language |
| 102 |
handler, process parameters, and return a value. |
| 103 |
</para> |
| 104 |
|
| 105 |
<para> |
| 106 |
Although providing a call handler is sufficient to create a minimal |
| 107 |
procedural language, there are two other functions that can optionally |
| 108 |
be provided to make the language more convenient to use. These |
| 109 |
are a <firstterm>validator</firstterm> and an |
| 110 |
<firstterm>inline handler</firstterm>. A validator can be provided |
| 111 |
to allow language-specific checking to be done during |
| 112 |
<xref linkend="sql-createfunction"/>. |
| 113 |
An inline handler can be provided to allow the language to support |
| 114 |
anonymous code blocks executed via the <xref linkend="sql-do"/> command. |
| 115 |
</para> |
| 116 |
|
| 117 |
<para> |
| 118 |
If a validator is provided by a procedural language, it |
| 119 |
must be declared as a function taking a single parameter of type |
| 120 |
<type>oid</type>. The validator's result is ignored, so it is customarily |
| 121 |
declared to return <type>void</type>. The validator will be called at |
| 122 |
the end of a <command>CREATE FUNCTION</command> command that has created |
| 123 |
or updated a function written in the procedural language. |
| 124 |
The passed-in OID is the OID of the function's <classname>pg_proc</classname> |
| 125 |
row. The validator must fetch this row in the usual way, and do |
| 126 |
whatever checking is appropriate. |
| 127 |
First, call <function>CheckFunctionValidatorAccess()</function> to diagnose |
| 128 |
explicit calls to the validator that the user could not achieve through |
| 129 |
<command>CREATE FUNCTION</command>. Typical checks then include verifying |
| 130 |
that the function's argument and result types are supported by the |
| 131 |
language, and that the function's body is syntactically correct |
| 132 |
in the language. If the validator finds the function to be okay, |
| 133 |
it should just return. If it finds an error, it should report that |
| 134 |
via the normal <function>ereport()</function> error reporting mechanism. |
| 135 |
Throwing an error will force a transaction rollback and thus prevent |
| 136 |
the incorrect function definition from being committed. |
| 137 |
</para> |
| 138 |
|
| 139 |
<para> |
| 140 |
Validator functions should typically honor the <xref |
| 141 |
linkend="guc-check-function-bodies"/> parameter: if it is turned off then |
| 142 |
any expensive or context-sensitive checking should be skipped. If the |
| 143 |
language provides for code execution at compilation time, the validator |
| 144 |
must suppress checks that would induce such execution. In particular, |
| 145 |
this parameter is turned off by <application>pg_dump</application> so that it can |
| 146 |
load procedural language functions without worrying about side effects or |
| 147 |
dependencies of the function bodies on other database objects. |
| 148 |
(Because of this requirement, the call handler should avoid |
| 149 |
assuming that the validator has fully checked the function. The point |
| 150 |
of having a validator is not to let the call handler omit checks, but |
| 151 |
to notify the user immediately if there are obvious errors in a |
| 152 |
<command>CREATE FUNCTION</command> command.) |
| 153 |
While the choice of exactly what to check is mostly left to the |
| 154 |
discretion of the validator function, note that the core |
| 155 |
<command>CREATE FUNCTION</command> code only executes <literal>SET</literal> clauses |
| 156 |
attached to a function when <varname>check_function_bodies</varname> is on. |
| 157 |
Therefore, checks whose results might be affected by GUC parameters |
| 158 |
definitely should be skipped when <varname>check_function_bodies</varname> is |
| 159 |
off, to avoid false failures when restoring a dump. |
| 160 |
</para> |
| 161 |
|
| 162 |
<para> |
| 163 |
If an inline handler is provided by a procedural language, it |
| 164 |
must be declared as a function taking a single parameter of type |
| 165 |
<type>internal</type>. The inline handler's result is ignored, so it is |
| 166 |
customarily declared to return <type>void</type>. The inline handler |
| 167 |
will be called when a <command>DO</command> statement is executed specifying |
| 168 |
the procedural language. The parameter actually passed is a pointer |
| 169 |
to an <structname>InlineCodeBlock</structname> struct, which contains information |
| 170 |
about the <command>DO</command> statement's parameters, in particular the |
| 171 |
text of the anonymous code block to be executed. The inline handler |
| 172 |
should execute this code and return. |
| 173 |
</para> |
| 174 |
|
| 175 |
<para> |
| 176 |
It's recommended that you wrap all these function declarations, |
| 177 |
as well as the <command>CREATE LANGUAGE</command> command itself, into |
| 178 |
an <firstterm>extension</firstterm> so that a simple <command>CREATE EXTENSION</command> |
| 179 |
command is sufficient to install the language. See |
| 180 |
<xref linkend="extend-extensions"/> for information about writing |
| 181 |
extensions. |
| 182 |
</para> |
| 183 |
|
| 184 |
<para> |
| 185 |
The procedural languages included in the standard distribution |
| 186 |
are good references when trying to write your own language handler. |
| 187 |
Look into the <filename>src/pl</filename> subdirectory of the source tree. |
| 188 |
The <xref linkend="sql-createlanguage"/> |
| 189 |
reference page also has some useful details. |
| 190 |
</para> |
| 191 |
|
| 192 |
</chapter> |