Fix typo; E<GT> -> E<gt>. From jmc@

1 files changed, 91 insertions, 8 deletions

diff --git a/gnu/usr.bin/perl/ext/Storable/Storable.pm b/gnu/usr.bin/perl/ext/Storable/Storable.pm
index 8346fdafc10..5a5eedc97c8 100644
--- a/gnu/usr.bin/perl/ext/Storable/Storable.pm
+++ b/gnu/usr.bin/perl/ext/Storable/Storable.pm
@@ -21,14 +21,17 @@ package Storable; @ISA = qw(Exporter DynaLoader);
 use AutoLoader;
 use vars qw($canonical $forgive_me $VERSION);
 
-$VERSION = '2.04';
+$VERSION = '2.15';
 *AUTOLOAD = \&AutoLoader::AUTOLOAD;		# Grrr...
 
 #
 # Use of Log::Agent is optional
 #
 
-eval "use Log::Agent";
+{
+    local $SIG{__DIE__};
+    eval "use Log::Agent";
+}
 
 require Carp;
 
@@ -47,6 +50,11 @@ BEGIN {
 	}
 }
 
+sub CLONE {
+    # clone context under threads
+    Storable::init_perinterp();
+}
+
 # Can't Autoload cleanly as this clashes 8.3 with &retrieve
 sub retrieve_fd { &fd_retrieve }		# Backward compatibility
 
@@ -361,6 +369,9 @@ sub thaw {
 	return $self;
 }
 
+1;
+__END__
+
 =head1 NAME
 
 Storable - persistence for Perl data structures
@@ -509,6 +520,22 @@ creating lookup tables for complicated queries.
 Canonical order does not imply network order; those are two orthogonal
 settings.
 
+=head1 CODE REFERENCES
+
+Since Storable version 2.05, CODE references may be serialized with
+the help of L<B::Deparse>. To enable this feature, set
+C<$Storable::Deparse> to a true value. To enable deserializazion,
+C<$Storable::Eval> should be set to a true value. Be aware that
+deserialization is done through C<eval>, which is dangerous if the
+Storable file contains malicious data. You can set C<$Storable::Eval>
+to a subroutine reference which would be used instead of C<eval>. See
+below for an example using a L<Safe> compartment for deserialization
+of CODE references.
+
+If C<$Storable::Deparse> and/or C<$Storable::Eval> are set to false
+values, then the value of C<$Storable::forgive_me> (see below) is
+respected while serializing and deserializing.
+
 =head1 FORWARD COMPATIBILITY
 
 This release of Storable can be used on a newer version of Perl to
@@ -671,6 +698,40 @@ It is up to you to use this information to populate I<obj> the way you want.
 
 Returned value: none.
 
+=item C<STORABLE_attach> I<class>, I<cloning>, I<serialized>
+
+While C<STORABLE_freeze> and C<STORABLE_thaw> are useful for classes where
+each instance is independant, this mechanism has difficulty (or is
+incompatible) with objects that exist as common process-level or
+system-level resources, such as singleton objects, database pools, caches
+or memoized objects.
+
+The alternative C<STORABLE_attach> method provides a solution for these
+shared objects. Instead of C<STORABLE_freeze> --E<gt> C<STORABLE_thaw>,
+you implement C<STORABLE_freeze> --E<gt> C<STORABLE_attach> instead.
+
+Arguments: I<class> is the class we are attaching to, I<cloning> is a flag
+indicating whether we're in a dclone() or a regular de-serialization via
+thaw(), and I<serialized> is the stored string for the resource object.
+
+Because these resource objects are considered to be owned by the entire
+process/system, and not the "property" of whatever is being serialized,
+no references underneath the object should be included in the serialized
+string. Thus, in any class that implements C<STORABLE_attach>, the
+C<STORABLE_freeze> method cannot return any references, and C<Storable>
+will throw an error if C<STORABLE_freeze> tries to return references.
+
+All information required to "attach" back to the shared resource object
+B<must> be contained B<only> in the C<STORABLE_freeze> return string.
+Otherwise, C<STORABLE_freeze> behaves as normal for C<STORABLE_attach>
+classes.
+
+Because C<STORABLE_attach> is passed the class (rather than an object),
+it also returns the object directly, rather than modifying the passed
+object.
+
+Returned value: object of type C<class>
+
 =back
 
 =head2 Predicates
@@ -767,10 +828,10 @@ Here are some code samples showing a possible usage of Storable:
 
 	%color = ('Blue' => 0.1, 'Red' => 0.8, 'Black' => 0, 'White' => 1);
 
-	store(\%color, '/tmp/colors') or die "Can't store %a in /tmp/colors!\n";
+	store(\%color, 'mycolors') or die "Can't store %a in mycolors!\n";
 
-	$colref = retrieve('/tmp/colors');
-	die "Unable to retrieve from /tmp/colors!\n" unless defined $colref;
+	$colref = retrieve('mycolors');
+	die "Unable to retrieve from mycolors!\n" unless defined $colref;
 	printf "Blue is still %lf\n", $colref->{'Blue'};
 
 	$colref2 = dclone(\%color);
@@ -784,6 +845,28 @@ which prints (on my machine):
 	Blue is still 0.100000
 	Serialization of %color is 102 bytes long.
 
+Serialization of CODE references and deserialization in a safe
+compartment:
+
+=for example begin
+
+	use Storable qw(freeze thaw);
+	use Safe;
+	use strict;
+	my $safe = new Safe;
+        # because of opcodes used in "use strict":
+	$safe->permit(qw(:default require));
+	local $Storable::Deparse = 1;
+	local $Storable::Eval = sub { $safe->reval($_[0]) };
+	my $serialized = freeze(sub { 42 });
+	my $code = thaw($serialized);
+	$code->() == 42;
+
+=for example end
+
+=for example_testing
+        is( $code->(), 42 );
+
 =head1 WARNING
 
 If you're using references as keys within your hash tables, you're bound
@@ -812,9 +895,9 @@ your data.  There is no slowdown on retrieval.
 
 =head1 BUGS
 
-You can't store GLOB, CODE, FORMLINE, etc.... If you can define
-semantics for those operations, feel free to enhance Storable so that
-it can deal with them.
+You can't store GLOB, FORMLINE, etc.... If you can define semantics
+for those operations, feel free to enhance Storable so that it can
+deal with them.
 
 The store functions will C<croak> if they run into such references
 unless you set C<$Storable::forgive_me> to some C<TRUE> value. In that