Fix test failures introduced by the change of flags on op_sort

[p5sagit/p5-mst-13.2.git] / ext / Storable / Storable.pm

diff --git a/ext/Storable/Storable.pm b/ext/Storable/Storable.pm
index 19f8834..712f597 100644 (file)
--- a/ext/Storable/Storable.pm
+++ b/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.10';
+$VERSION = '2.15_01';
 *AUTOLOAD = \&AutoLoader::AUTOLOAD;            # Grrr...
 
 #
 # Use of Log::Agent is optional
 #
 
-eval "use Log::Agent";
+{
+    local $SIG{__DIE__};
+    eval "use Log::Agent";
+}
 
 require Carp;
 
@@ -521,7 +524,7 @@ settings.
 
 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::Deparse> to a true value. To enable deserialization,
 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>
@@ -695,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 independent, 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
@@ -791,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);
@@ -894,7 +931,7 @@ data back to 8 bit and C<croak()> if the conversion fails.
 Prior to Storable 2.01, no distinction was made between signed and
 unsigned integers on storing.  By default Storable prefers to store a
 scalars string representation (if it has one) so this would only cause
-problems when storing large unsigned integers that had never been coverted
+problems when storing large unsigned integers that had never been converted
 to string or floating point.  In other words values that had been generated
 by integer operations such as logic ops and then not used in any string or
 arithmetic context before storing.