mirrors/postgres
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Update plhandler.sgml to describe validators and inline handlers for

Browse Source 
procedural languages.
This commit is contained in:
Tom Lane 2009-10-08 04:41:07 +00:00
parent 717fa274d1
commit 822b0159cc
2 changed files with 67 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

70
doc/src/sgml/plhandler.sgml
View File

@ -1,4 +1,4 @@
<!-- $PostgreSQL: pgsql/doc/src/sgml/plhandler.sgml,v 1.7 2006/09/16 00:30:14 momjian Exp $ -->
<!-- $PostgreSQL: pgsql/doc/src/sgml/plhandler.sgml,v 1.8 2009/10/08 04:41:07 tgl Exp $ -->
<chapter id="plhandler">
<title>Writing A Procedural Language Handler</title>
@ -13,7 +13,7 @@
the current <quote>version 1</quote> interface for compiled
languages (this includes functions in user-defined procedural languages,
functions written in SQL, and functions using the version 0 compiled
language interface), go through a <firstterm>call handler</firstterm>
language interface) go through a <firstterm>call handler</firstterm>
function for the specific language. It is the responsibility of
the call handler to execute the function in a meaningful way, such
as by interpreting the supplied source text. This chapter outlines
@ -51,8 +51,7 @@
<para>
It's up to the call handler to fetch the entry of the function from the
system table
<classname>pg_proc</classname> and to analyze the argument
<classname>pg_proc</classname> system catalog and to analyze the argument
and return types of the called function. The <literal>AS</> clause from the
<command>CREATE FUNCTION</command> command for the function will be found
in the <literal>prosrc</literal> column of the
@ -152,10 +151,71 @@ CREATE LANGUAGE plsample
</programlisting>
</para>
<para>
Although providing a call handler is sufficient to create a minimal
procedural language, there are two other functions that can optionally
be provided to make the language more convenient to use. These
are a <firstterm>validator</firstterm> and an
<firstterm>inline handler</firstterm>. A validator can be provided
to allow language-specific checking to be done during
<xref linkend="sql-createfunction" endterm="sql-createfunction-title">.
An inline handler can be provided to allow the language to support
anonymous code blocks executed via the <xref linkend="sql-do"
endterm="sql-do-title"> command.
</para>
<para>
If a validator is provided by a procedural language, it
must be declared as a function taking a single parameter of type
<type>oid</>. The validator's result is ignored, so it is customarily
declared to return <type>void</>. The validator will be called at
the end of a <command>CREATE FUNCTION</> command that has created
or updated a function written in the procedural language.
The passed-in OID is the OID of the function's <classname>pg_proc</>
row. The validator must fetch this row in the usual way, and do
whatever checking is appropriate. Typical checks include verifying
that the function's argument and result types are supported by the
language, and that the function's body is syntactically correct
in the language. If the validator finds the function to be okay,
it should just return. If it finds an error, it should report that
via the normal <function>ereport()</> error reporting mechanism.
Throwing an error will force a transaction rollback and thus prevent
the incorrect function definition from being committed.
</para>
<para>
Validator functions should typically honor the <xref
linkend="guc-check-function-bodies"> parameter: if it is turned off then
any expensive or context-sensitive checking should be skipped.
In particular, this parameter is turned off by <application>pg_dump</>
so that it can load procedural language functions without worrying
about possible dependencies of the function bodies on other database
objects. (Because of this requirement, the call handler should avoid
assuming that the validator has fully checked the function. The point
of having a validator is not to let the call handler omit checks, but
to notify the user immediately if there are obvious errors in a
<command>CREATE FUNCTION</> command.)
</para>
<para>
If an inline handler is provided by a procedural language, it
must be declared as a function taking a single parameter of type
<type>internal</>. The inline handler's result is ignored, so it is
customarily declared to return <type>void</>. The inline handler
will be called when a <command>DO</> statement is executed specifying
the procedural language. The parameter actually passed is a pointer
to an <structname>InlineCodeBlock</> struct, which contains information
about the <command>DO</> statement's parameters, in particular the
text of the anonymous code block to be executed. The inline handler
should execute this code and return.
</para>
<para>
The procedural languages included in the standard distribution
are good references when trying to write your own call handler.
are good references when trying to write your own language handler.
Look into the <filename>src/pl</> subdirectory of the source tree.
The <xref linkend="sql-createlanguage" endterm="sql-createlanguage-title">
reference page also has some useful details.
</para>
</chapter>

4
doc/src/sgml/ref/create_language.sgml
View File

@ -1,5 +1,5 @@
<!--
$PostgreSQL: pgsql/doc/src/sgml/ref/create_language.sgml,v 1.46 2009/09/22 23:43:37 tgl Exp $
$PostgreSQL: pgsql/doc/src/sgml/ref/create_language.sgml,v 1.47 2009/10/08 04:41:07 tgl Exp $
PostgreSQL documentation
-->
@ -41,7 +41,7 @@ CREATE [ TRUSTED ] [ PROCEDURAL ] LANGUAGE <replaceable class="parameter">name</
<para>
<command>CREATE LANGUAGE</command> effectively associates the
language name with a call handler that is responsible for executing
functions written in the language. Refer to <xref linkend="xplang">
functions written in the language. Refer to <xref linkend="plhandler">
for more information about language call handlers.
</para>