X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlpragma.pod;h=51292a8a12c0382f07d80d04b0087a5b47705e33;hb=6d1e6673d7386f4f9139111a6e44d555b8252741;hp=3bdf8b79aa31cfe6cef877795daba93d8ccfb41c;hpb=46e5f5f47696caa998bfcb1e374d29f888f44b9b;p=p5sagit%2Fp5-mst-13.2.git

diff --git a/pod/perlpragma.pod b/pod/perlpragma.pod
index 3bdf8b7..51292a8 100644
--- 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;
     
@@ -117,7 +117,7 @@ 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
-stored in the optree, and can be retrieved at runtime with C<caller>, at
+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
@@ -128,13 +128,20 @@ 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.