perldelta: Blanket entry for memory leaks

[perl5.git] / pod / perlpragma.pod

diff --git a/pod/perlpragma.pod b/pod/perlpragma.pod
index 9267bab..604387d 100644 (file)
--- a/pod/perlpragma.pod
+++ b/pod/perlpragma.pod
@@ -34,7 +34,7 @@ functions much like C<use integer;> You'd like this code
     
     no myint;
     print "E: ", $l + $r, "\n";
-   
+
 to give the output
 
     A: 4.6
@@ -71,28 +71,28 @@ this:
     
     1;
 
-Note how we load the user pragma C<myint> with C<()> to prevent its C<import>
-being called.
-
-The interaction with the Perl compile happens inside package C<myint>:
+Note how we load the user pragma C<myint> with an empty list C<()> to
+prevent its C<import> being called.
 
-package myint;
+The interaction with the Perl compilation happens inside package C<myint>:
 
+    package myint;
+    
     use strict;
     use warnings;
     
     sub import {
-        $^H{myint} = 1;
+        $^H{"myint/in_effect"} = 1;
     }
     
     sub unimport {
-        $^H{myint} = 0;
+        $^H{"myint/in_effect"} = 0;
     }
     
     sub in_effect {
         my $level = shift // 0;
         my $hinthash = (caller($level))[10];
-        return $hinthash->{myint};
+        return $hinthash->{"myint/in_effect"};
     }
     
     1;
@@ -115,24 +115,49 @@ and C<no myint;> is
 Hence the C<import> and C<unimport> routines are called at B<compile time>
 for the user's code.
 
-User pragmata store their state by writing to C<%^H>, hence these two
-routines manipulate C<%^H>. The state information in C<%^H> stored in the
-optree, and can be retrieved at runtime with C<caller>, at index 10 of the
-list of returned results. In the example pragma, retrieval is encapsulated
-into the routine C<in_effect()>. This uses C<caller(1)> to determine the
-state of C<$^H{myint}> when each line of the user's script was called, and
+User pragmata store their state by writing to the magical hash C<%^H>,
+hence these two routines manipulate it. The state information in C<%^H> is
+stored in the optree, and can be retrieved read-only at runtime with C<caller()>,
+at index 10 of the list of returned results. In the example pragma, retrieval
+is encapsulated into the routine C<in_effect()>, which takes as parameter
+the number of call frames to go up to find the value of the pragma in the
+user's script. This uses C<caller()> to determine the value of
+C<$^H{"myint/in_effect"}> when each line of the user's script was called, and
 therefore provide the correct semantics in the subroutine implementing the
 overloaded addition.
 
+=head1 Key naming
+
+There is only a single C<%^H>, but arbitrarily many modules that want
+to use its scoping semantics.  To avoid stepping on each other's toes,
+they need to be sure to use different keys in the hash.  It is therefore
+conventional for a module to use only keys that begin with the module's
+name (the name of its main package) and a "/" character.  After this
+module-identifying prefix, the rest of the key is entirely up to the
+module: it may include any characters whatsoever.  For example, a module
+C<Foo::Bar> should use keys such as C<Foo::Bar/baz> and C<Foo::Bar/$%/_!>.
+Modules following this convention all play nicely with each other.
+
+The Perl core uses a handful of keys in C<%^H> which do not follow this
+convention, because they predate it.  Keys that follow the convention
+won't conflict with the core's historical keys.
+
 =head1 Implementation details
 
-The optree is shared between threads, which means there is a possibility that
-the optree will outlive the particular thread (and therefore interpreter
+The optree is shared between threads.  This means there is a possibility that
+the optree will outlive the particular thread (and therefore the interpreter
 instance) that created it, so true Perl scalars cannot be stored in the
-optree. Instead a compact form is used, which can only store values that are
+optree.  Instead a compact form is used, which can only store values that are
 integers (signed and unsigned), strings or C<undef> - references and
 floating point values are stringified.  If you need to store multiple values
 or complex structures, you should serialise them, for example with C<pack>.
 The deletion of a hash key from C<%^H> is recorded, and as ever can be
 distinguished from the existence of a key with value C<undef> with
 C<exists>.
+
+B<Don't> attempt to store references to data structures as integers which
+are retrieved via C<caller> and converted back, as this will not be threadsafe.
+Accesses would be to the structure without locking (which is not safe for
+Perl's scalars), and either the structure has to leak, or it has to be
+freed when its creating thread terminates, which may be before the optree
+referencing it is deleted, if other threads outlive it.