Add warning about plperl nested named subroutines

Andrew Dunstan

diff --git a/doc/src/sgml/plperl.sgml b/doc/src/sgml/plperl.sgml
index 51bc9e3de3280fd9634e62a050af4e476af2c060..e94ec872827ba79123da80c41dbca02abf107017 100644 (file)
--- a/doc/src/sgml/plperl.sgml
+++ b/doc/src/sgml/plperl.sgml
@@ -53,22 +53,34 @@ CREATE FUNCTION <replaceable>funcname</replaceable> (<replaceable>argument-types
     # PL/Perl function body
 $$ LANGUAGE plperl;
 </programlisting>
-   The body of the function is ordinary Perl code. A PL/Perl function must
+   The body of the function is ordinary Perl code. In fact, the PL/Perl
+   glue code wraps it inside a Perl subroutine. A PL/Perl function must
    always return a scalar value.  You can return more complex structures
    (arrays, records, and sets) by returning a reference, as discussed below.
    Never return a list.
   </para>
 
+  <note>
    <para>
-    The syntax of the <command>CREATE FUNCTION</command> command requires
-    the function body to be written as a string constant.  It is usually
-    most convenient to use dollar quoting (see <xref
-    linkend="sql-syntax-dollar-quoting">) for the string constant.
-    If you choose to use regular single-quoted string constant syntax,
-    you must escape single quote marks (<literal>'</>) and backslashes
-    (<literal>\</>) used in the body of the function, typically by
-    doubling them (see <xref linkend="sql-syntax-strings">).
+    The use of named nested subroutines is dangerous in Perl, especially if
+    they refer to lexical variables in the enclosing scope. Because a PL/Perl
+    function is wrapped in a subroutine, any named subroutine you create will
+    be nested. In general, it is far safer to create anonymous subroutines
+    which you call via a coderef. See the <literal>perldiag</literal>
+    man page for more details.
    </para>
+  </note>
+
+  <para>
+   The syntax of the <command>CREATE FUNCTION</command> command requires
+   the function body to be written as a string constant.  It is usually
+   most convenient to use dollar quoting (see <xref
+   linkend="sql-syntax-dollar-quoting">) for the string constant.
+   If you choose to use regular single-quoted string constant syntax,
+   you must escape single quote marks (<literal>'</>) and backslashes
+   (<literal>\</>) used in the body of the function, typically by
+   doubling them (see <xref linkend="sql-syntax-strings">).
+  </para>
 
   <para>
    Arguments and results are handled as in any other Perl subroutine: