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";
     
     no myint;
     print "E: ", $l + $r, "\n";

-   
+

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


@@ -71,13 +71,13 @@ 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;
     
     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.
 
 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
 
 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
 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>.
 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.