More perldelta rototilling.

[perl5.git] / pod / perlpragma.pod

diff --git a/pod/perlpragma.pod b/pod/perlpragma.pod
index 9267bab..51292a8 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,13 +71,13 @@ 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;
     
@@ -115,24 +115,33 @@ 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 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}> when each line of the user's script was called, and
 therefore provide the correct semantics in the subroutine implementing the
 overloaded addition.
 
 =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.