On Friday 09 June 2006 09:13, Torsten Foertsch wrote: > The behavior must be well documented and the difference thoroughly > explained. That's all. I'll see if I can come up with a better patch.
How about that? Torsten
Index: docs/api/Apache2/ConnectionUtil.pod
===================================================================
--- docs/api/Apache2/ConnectionUtil.pod (revision 412993)
+++ docs/api/Apache2/ConnectionUtil.pod (working copy)
@@ -91,8 +91,19 @@
the connection instead of the lifetime of the request. If the connection is
lost, so is the data stored in C<pnotes>.
+See
+(C<L<Apache2::RequestUtil::pnotes|docs::2.0::api::Apache2::RequestUtil/C_pnotes_>>)
+also for the differences between
+ $c->pnotes()->{$key} = $val;
+and
+
+ $c->pnotes($key => $val);
+
+
+
+
=head1 See Also
L<Apache2::Connection|docs::2.0::api::Apache2::Connection>.
Index: docs/api/Apache2/RequestUtil.pod
===================================================================
--- docs/api/Apache2/RequestUtil.pod (revision 412993)
+++ docs/api/Apache2/RequestUtil.pod (working copy)
@@ -777,23 +777,60 @@
Share Perl variables between Perl HTTP handlers
+ $r->pnotes()->{$key} = $val;
+
$old_val = $r->pnotes($key => $val);
$val = $r->pnotes($key);
$hash_ref = $r->pnotes();
-B<Note:> sharing variables really means it. The variable is not copied.
-Only its reference count is incremented. If it is changed after being
-put in pnotes that change also affects the stored value. The following
-example illustrates the effect:
+B<Note:> Since C<$r-E<gt>pnotes()> without arguments returns a
+reference to the underlying hash there are 2 ways of setting a note:
- my $v=1; my $v=1;
- $r->pnotes( 'v'=>$v ); $r->pnotes->{v}=$v;
- $v++; $v++;
- my $x=$r->pnotes('v'); my $x=$r->pnotes->{v};
+ $r->pnotes()->{$key} = $val;
-In both cases C<$x> is C<2> not C<1>. See also C<Apache2::SafePnotes> on
-CPAN.
+and
+ $r->pnotes($key => $val);
+
+Although looking very similar there is a slight difference. While the
+first version behaves entirely like a normal Perl hash the second does
+not. When a variable is assinged a value the value is normally copied.
+With the second version this copying is avoided by simply incrementing
+the reference counter of the source variable and storing it directly.
+
+Translated into perlish tongue that means for example:
+
+ $r->pnotes->{key} = 'some string';
+
+is exactly the same as
+
+ $r->pnotes(key => 'some string');
+
+But
+
+ $r->pnotes->{key} = $val;
+
+and
+
+ $r->pnotes(key => $val);
+
+are different. In the first case C<$r-E<gt>pnotes-E<gt>{key}> and C<$val>
+use different storage in the second they use henceforward the same storage.
+That means subsequent changes to C<$val> affect the value of
+C<$r-E<gt>pnotes-E<gt>{key}> and vice versa:
+
+ $val = 1;
+ $r->pnotes(key => $val);
+ $val++;
+ $x = $r->pnotes('key'); # $x 2 not 1
+ # $val++ has also affected the pnote
+
+ $r->pnotes->{key} = 'string';
+ $x = $val; # $x 'string' now
+ # $val has changed behind the scene
+
+See also C<Apache2::SafePnotes> on CPAN.
+
=over 4
=item obj: C<$r>
pgpBTsl02dRsU.pgp
Description: PGP signature
