perldelta: Blanket entry for memory leaks

[perl5.git] / pod / perlpragma.pod

diff --git a/pod/perlpragma.pod b/pod/perlpragma.pod
index c43ff49..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";
     
     no myint;
     print "E: ", $l + $r, "\n";

-   
+

 to give the output
 
     A: 4.6
 to give the output
 
     A: 4.6


@@ -71,28 +71,28 @@ this:
     
     1;
 
     
     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 {
     use strict;
     use warnings;
     
     sub import {

-        $^H{myint} = 1;
+        $^H{"myint/in_effect"} = 1;

     }
     
     sub unimport {
     }
     
     sub unimport {

-        $^H{myint} = 0;
+        $^H{"myint/in_effect"} = 0;

     }
     
     sub in_effect {
         my $level = shift // 0;
         my $hinthash = (caller($level))[10];
     }
     
     sub in_effect {
         my $level = shift // 0;
         my $hinthash = (caller($level))[10];

-        return $hinthash->{myint};
+        return $hinthash->{"myint/in_effect"};

     }
     
     1;
     }
     
     1;


@@ -117,15 +117,31 @@ for the user's code.
 
 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
 
 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 at runtime with C<caller>, at
-index 10 of the list of returned results. In the example pragma, retrieval
+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
 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}> when each line of the user's script was called, and
+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.
 
 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.  This means there is a possibility that
 =head1 Implementation details
 
 The optree is shared between threads.  This means there is a possibility that


@@ -138,3 +154,10 @@ 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>.
 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.