svn commit: r1062310 - /perl/modperl/docs/trunk/src/docs/2.0/api/Apache2/RequestUtil.pod

[ph...@apache.org]

Author: phred
Date: Sun Jan 23 02:03:45 2011
New Revision: 1062310

URL: http://svn.apache.org/viewvc?rev=1062310&view=rev
Log:
Implement Tim Bunce's suggestion for pnotes sharing by value.

https://rt.cpan.org/Ticket/Display.html?id=30061

Modified:
    perl/modperl/docs/trunk/src/docs/2.0/api/Apache2/RequestUtil.pod

Modified: perl/modperl/docs/trunk/src/docs/2.0/api/Apache2/RequestUtil.pod
URL: http://svn.apache.org/viewvc/perl/modperl/docs/trunk/src/docs/2.0/api/Apache2/RequestUtil.pod?rev=1062310&r1=1062309&r2=1062310&view=diff
==============================================================================
--- perl/modperl/docs/trunk/src/docs/2.0/api/Apache2/RequestUtil.pod (original)
+++ perl/modperl/docs/trunk/src/docs/2.0/api/Apache2/RequestUtil.pod Sun Jan 23 02:03:45 2011
@@ -64,7 +64,7 @@ Apache2::RequestUtil - Perl API for Apac
   # tell the client not to cache the response
   $r->no_cache($boolean);
   
-  # share perl objects like $r->notes
+  # share perl objects by reference like $r->notes
   $r->pnotes($key => [$obj1, $obj2]);
   
   # get HTML signature
@@ -777,6 +777,7 @@ out.
 
 Share Perl variables between Perl HTTP handlers
 
+  # to share variables by value and not reference, $val should be a lexical.
   $old_val  = $r->pnotes($key => $val);
   $val      = $r->pnotes($key);
   $hash_ref = $r->pnotes();
@@ -794,6 +795,35 @@ example illustrates the effect:
 In both cases C<$x> is C<2> not C<1>. See also C<Apache2::SafePnotes> on
 CPAN.
 
+There has been a lot of discussion advocating for pnotes sharing variables
+by value and not reference.  Sharing by reference can create 'spooky action
+at a distance' effects when the sharing is assumed to share a copy of the
+value.  Tim Bunce offers the following summary and suggestion for sharing
+by value.
+
+What's wrong with this code:
+
+  sub foo {
+      my ($r, $status, $why) = @_;
+      $r->pnotes('foo', ($why) ? "$status:$why" : $status);
+      return;
+  }
+
+Nothing, except it doesn't work as expected due to this pnotes bug: If the 
+same code is called in a sub-request then the pnote of $r->prev is magically 
+updated at a distance to the same value!
+
+Try explain why that is to anyone not deeply familar with perl internals!
+
+The fix is to avoid pnotes taking a ref to the invisible op_targ embededed in 
+the code by passing a simple lexical variable as the actual argument. That can be done in-line like this:
+
+  sub mark_as_internally_redirected {
+      my ($r, $status, $why) = @_;
+      $r->pnotes('foo', my $tmp = (($why) ? "$status:$why" : $status));
+      return;
+  }
+
 =over 4
 
 =item obj: C<$r>



---------------------------------------------------------------------
To unsubscribe, e-mail: docs-cvs-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-cvs-help@perl.apache.org