From 822b0159cc4a4411bb8d2829f7328b7c52fef2f2 Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Thu, 8 Oct 2009 04:41:07 +0000 Subject: [PATCH] Update plhandler.sgml to describe validators and inline handlers for procedural languages. --- doc/src/sgml/plhandler.sgml | 70 +++++++++++++++++++++++++-- doc/src/sgml/ref/create_language.sgml | 4 +- 2 files changed, 67 insertions(+), 7 deletions(-) diff --git a/doc/src/sgml/plhandler.sgml b/doc/src/sgml/plhandler.sgml index 6173d5a678..0d8ec93b86 100644 --- a/doc/src/sgml/plhandler.sgml +++ b/doc/src/sgml/plhandler.sgml @@ -1,4 +1,4 @@ - + Writing A Procedural Language Handler @@ -13,7 +13,7 @@ the current version 1 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 call handler + language interface) go through a call handler 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 @@ It's up to the call handler to fetch the entry of the function from the - system table - pg_proc and to analyze the argument + pg_proc system catalog and to analyze the argument and return types of the called function. The AS clause from the CREATE FUNCTION command for the function will be found in the prosrc column of the @@ -152,10 +151,71 @@ CREATE LANGUAGE plsample + + 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 validator and an + inline handler. A validator can be provided + to allow language-specific checking to be done during + . + An inline handler can be provided to allow the language to support + anonymous code blocks executed via the command. + + + + If a validator is provided by a procedural language, it + must be declared as a function taking a single parameter of type + oid. The validator's result is ignored, so it is customarily + declared to return void. The validator will be called at + the end of a 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 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 ereport() error reporting mechanism. + Throwing an error will force a transaction rollback and thus prevent + the incorrect function definition from being committed. + + + + Validator functions should typically honor the parameter: if it is turned off then + any expensive or context-sensitive checking should be skipped. + In particular, this parameter is turned off by 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 + CREATE FUNCTION command.) + + + + If an inline handler is provided by a procedural language, it + must be declared as a function taking a single parameter of type + internal. The inline handler's result is ignored, so it is + customarily declared to return void. The inline handler + will be called when a DO statement is executed specifying + the procedural language. The parameter actually passed is a pointer + to an InlineCodeBlock struct, which contains information + about the 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. + + 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 src/pl subdirectory of the source tree. + The + reference page also has some useful details. diff --git a/doc/src/sgml/ref/create_language.sgml b/doc/src/sgml/ref/create_language.sgml index 4c0463ddec..f87308edb3 100644 --- a/doc/src/sgml/ref/create_language.sgml +++ b/doc/src/sgml/ref/create_language.sgml @@ -1,5 +1,5 @@ @@ -41,7 +41,7 @@ CREATE [ TRUSTED ] [ PROCEDURAL ] LANGUAGE name CREATE LANGUAGE effectively associates the language name with a call handler that is responsible for executing - functions written in the language. Refer to + functions written in the language. Refer to for more information about language call handlers. -- 2.40.0