diff options
Diffstat (limited to 'gnu/usr.bin/perl')
| -rw-r--r-- | gnu/usr.bin/perl/ext/Storable/Storable.pm | 99 |
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 |