Add warning about plperl nested named subroutines

Andrew Dunstan

diff --git a/doc/src/sgml/plperl.sgml b/doc/src/sgml/plperl.sgml
index f1a99a1f999f9e7deaf50f06c57930b69296cb57..9ae95feb1b4afb38d5b9e432af8218bc6800efa8 100644 (file)
--- a/doc/src/sgml/plperl.sgml
+++ b/doc/src/sgml/plperl.sgml
@@ -1,5 +1,5 @@
 
 
  
@@ -53,22 +53,34 @@ CREATE FUNCTION funcname (argument-types
     # PL/Perl function body
 $$ LANGUAGE plperl;
 
-   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.
   
 
+  
    
-    The syntax of the CREATE FUNCTION command requires
-    the function body to be written as a string constant.  It is usually
-    most convenient to use dollar quoting (see 
-    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 (') and backslashes
-    (\) used in the body of the function, typically by
-    doubling them (see ).
+    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 perldiag
+    man page for more details.
    
+  
+
+  
+   The syntax of the CREATE FUNCTION command requires
+   the function body to be written as a string constant.  It is usually
+   most convenient to use dollar quoting (see 
+   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 (') and backslashes
+   (\) used in the body of the function, typically by
+   doubling them (see ).
+  
 
   
    Arguments and results are handled as in any other Perl subroutine: