Add warning about plperl nested named subroutines

Andrew Dunstan

doc/src/sgml/plperl.sgml

 <!--
-$PostgreSQL: pgsql/doc/src/sgml/plperl.sgml,v 2.45 2005/08/24 19:16:49 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/plperl.sgml,v 2.46 2005/10/12 14:28:33 momjian Exp $
 -->
 
  <chapter id="plperl">
@@ -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: