This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Bumping version of Storable for release per Porting/cmpVERSION.pl
[perl5.git] / dist / Storable / Storable.pm
1 #
2 #  Copyright (c) 1995-2000, Raphael Manfredi
3 #  
4 #  You may redistribute only under the same terms as Perl 5, as specified
5 #  in the README file that comes with the distribution.
6 #
7
8 require DynaLoader;
9 require Exporter;
10 package Storable; @ISA = qw(Exporter DynaLoader);
11
12 @EXPORT = qw(store retrieve);
13 @EXPORT_OK = qw(
14         nstore store_fd nstore_fd fd_retrieve
15         freeze nfreeze thaw
16         dclone
17         retrieve_fd
18         lock_store lock_nstore lock_retrieve
19         file_magic read_magic
20 );
21
22 use AutoLoader;
23 use FileHandle;
24 use vars qw($canonical $forgive_me $VERSION);
25
26 $VERSION = '2.26';
27 *AUTOLOAD = \&AutoLoader::AUTOLOAD;             # Grrr...
28
29 #
30 # Use of Log::Agent is optional
31 #
32
33 {
34     local $SIG{__DIE__};
35     eval "use Log::Agent";
36 }
37
38 require Carp;
39
40 #
41 # They might miss :flock in Fcntl
42 #
43
44 BEGIN {
45         if (eval { require Fcntl; 1 } && exists $Fcntl::EXPORT_TAGS{'flock'}) {
46                 Fcntl->import(':flock');
47         } else {
48                 eval q{
49                         sub LOCK_SH ()  {1}
50                         sub LOCK_EX ()  {2}
51                 };
52         }
53 }
54
55 sub CLONE {
56     # clone context under threads
57     Storable::init_perinterp();
58 }
59
60 # Can't Autoload cleanly as this clashes 8.3 with &retrieve
61 sub retrieve_fd { &fd_retrieve }                # Backward compatibility
62
63 # By default restricted hashes are downgraded on earlier perls.
64
65 $Storable::downgrade_restricted = 1;
66 $Storable::accept_future_minor = 1;
67 bootstrap Storable;
68 1;
69 __END__
70 #
71 # Use of Log::Agent is optional. If it hasn't imported these subs then
72 # Autoloader will kindly supply our fallback implementation.
73 #
74
75 sub logcroak {
76     Carp::croak(@_);
77 }
78
79 sub logcarp {
80   Carp::carp(@_);
81 }
82
83 #
84 # Determine whether locking is possible, but only when needed.
85 #
86
87 sub CAN_FLOCK; my $CAN_FLOCK; sub CAN_FLOCK {
88         return $CAN_FLOCK if defined $CAN_FLOCK;
89         require Config; import Config;
90         return $CAN_FLOCK =
91                 $Config{'d_flock'} ||
92                 $Config{'d_fcntl_can_lock'} ||
93                 $Config{'d_lockf'};
94 }
95
96 sub show_file_magic {
97     print <<EOM;
98 #
99 # To recognize the data files of the Perl module Storable,
100 # the following lines need to be added to the local magic(5) file,
101 # usually either /usr/share/misc/magic or /etc/magic.
102 #
103 0       string  perl-store      perl Storable(v0.6) data
104 >4      byte    >0      (net-order %d)
105 >>4     byte    &01     (network-ordered)
106 >>4     byte    =3      (major 1)
107 >>4     byte    =2      (major 1)
108
109 0       string  pst0    perl Storable(v0.7) data
110 >4      byte    >0
111 >>4     byte    &01     (network-ordered)
112 >>4     byte    =5      (major 2)
113 >>4     byte    =4      (major 2)
114 >>5     byte    >0      (minor %d)
115 EOM
116 }
117
118 sub file_magic {
119     my $file = shift;
120     my $fh = new FileHandle;
121     open($fh, "<". $file) || die "Can't open '$file': $!";
122     binmode($fh);
123     defined(sysread($fh, my $buf, 32)) || die "Can't read from '$file': $!";
124     close($fh);
125
126     $file = "./$file" unless $file;  # ensure TRUE value
127
128     return read_magic($buf, $file);
129 }
130
131 sub read_magic {
132     my($buf, $file) = @_;
133     my %info;
134
135     my $buflen = length($buf);
136     my $magic;
137     if ($buf =~ s/^(pst0|perl-store)//) {
138         $magic = $1;
139         $info{file} = $file || 1;
140     }
141     else {
142         return undef if $file;
143         $magic = "";
144     }
145
146     return undef unless length($buf);
147
148     my $net_order;
149     if ($magic eq "perl-store" && ord(substr($buf, 0, 1)) > 1) {
150         $info{version} = -1;
151         $net_order = 0;
152     }
153     else {
154         $buf =~ s/(.)//s;
155         my $major = (ord $1) >> 1;
156         return undef if $major > 4; # sanity (assuming we never go that high)
157         $info{major} = $major;
158         $net_order = (ord $1) & 0x01;
159         if ($major > 1) {
160             return undef unless $buf =~ s/(.)//s;
161             my $minor = ord $1;
162             $info{minor} = $minor;
163             $info{version} = "$major.$minor";
164             $info{version_nv} = sprintf "%d.%03d", $major, $minor;
165         }
166         else {
167             $info{version} = $major;
168         }
169     }
170     $info{version_nv} ||= $info{version};
171     $info{netorder} = $net_order;
172
173     unless ($net_order) {
174         return undef unless $buf =~ s/(.)//s;
175         my $len = ord $1;
176         return undef unless length($buf) >= $len;
177         return undef unless $len == 4 || $len == 8;  # sanity
178         @info{qw(byteorder intsize longsize ptrsize)}
179             = unpack "a${len}CCC", $buf;
180         (substr $buf, 0, $len + 3) = '';
181         if ($info{version_nv} >= 2.002) {
182             return undef unless $buf =~ s/(.)//s;
183             $info{nvsize} = ord $1;
184         }
185     }
186     $info{hdrsize} = $buflen - length($buf);
187
188     return \%info;
189 }
190
191 sub BIN_VERSION_NV {
192     sprintf "%d.%03d", BIN_MAJOR(), BIN_MINOR();
193 }
194
195 sub BIN_WRITE_VERSION_NV {
196     sprintf "%d.%03d", BIN_MAJOR(), BIN_WRITE_MINOR();
197 }
198
199 #
200 # store
201 #
202 # Store target object hierarchy, identified by a reference to its root.
203 # The stored object tree may later be retrieved to memory via retrieve.
204 # Returns undef if an I/O error occurred, in which case the file is
205 # removed.
206 #
207 sub store {
208         return _store(\&pstore, @_, 0);
209 }
210
211 #
212 # nstore
213 #
214 # Same as store, but in network order.
215 #
216 sub nstore {
217         return _store(\&net_pstore, @_, 0);
218 }
219
220 #
221 # lock_store
222 #
223 # Same as store, but flock the file first (advisory locking).
224 #
225 sub lock_store {
226         return _store(\&pstore, @_, 1);
227 }
228
229 #
230 # lock_nstore
231 #
232 # Same as nstore, but flock the file first (advisory locking).
233 #
234 sub lock_nstore {
235         return _store(\&net_pstore, @_, 1);
236 }
237
238 # Internal store to file routine
239 sub _store {
240         my $xsptr = shift;
241         my $self = shift;
242         my ($file, $use_locking) = @_;
243         logcroak "not a reference" unless ref($self);
244         logcroak "wrong argument number" unless @_ == 2;        # No @foo in arglist
245         local *FILE;
246         if ($use_locking) {
247                 open(FILE, ">>$file") || logcroak "can't write into $file: $!";
248                 unless (&CAN_FLOCK) {
249                         logcarp "Storable::lock_store: fcntl/flock emulation broken on $^O";
250                         return undef;
251                 }
252                 flock(FILE, LOCK_EX) ||
253                         logcroak "can't get exclusive lock on $file: $!";
254                 truncate FILE, 0;
255                 # Unlocking will happen when FILE is closed
256         } else {
257                 open(FILE, ">$file") || logcroak "can't create $file: $!";
258         }
259         binmode FILE;                           # Archaic systems...
260         my $da = $@;                            # Don't mess if called from exception handler
261         my $ret;
262         # Call C routine nstore or pstore, depending on network order
263         eval { $ret = &$xsptr(*FILE, $self) };
264         # close will return true on success, so the or short-circuits, the ()
265         # expression is true, and for that case the block will only be entered
266         # if $@ is true (ie eval failed)
267         # if close fails, it returns false, $ret is altered, *that* is (also)
268         # false, so the () expression is false, !() is true, and the block is
269         # entered.
270         if (!(close(FILE) or undef $ret) || $@) {
271                 unlink($file) or warn "Can't unlink $file: $!\n";
272         }
273         logcroak $@ if $@ =~ s/\.?\n$/,/;
274         $@ = $da;
275         return $ret;
276 }
277
278 #
279 # store_fd
280 #
281 # Same as store, but perform on an already opened file descriptor instead.
282 # Returns undef if an I/O error occurred.
283 #
284 sub store_fd {
285         return _store_fd(\&pstore, @_);
286 }
287
288 #
289 # nstore_fd
290 #
291 # Same as store_fd, but in network order.
292 #
293 sub nstore_fd {
294         my ($self, $file) = @_;
295         return _store_fd(\&net_pstore, @_);
296 }
297
298 # Internal store routine on opened file descriptor
299 sub _store_fd {
300         my $xsptr = shift;
301         my $self = shift;
302         my ($file) = @_;
303         logcroak "not a reference" unless ref($self);
304         logcroak "too many arguments" unless @_ == 1;   # No @foo in arglist
305         my $fd = fileno($file);
306         logcroak "not a valid file descriptor" unless defined $fd;
307         my $da = $@;                            # Don't mess if called from exception handler
308         my $ret;
309         # Call C routine nstore or pstore, depending on network order
310         eval { $ret = &$xsptr($file, $self) };
311         logcroak $@ if $@ =~ s/\.?\n$/,/;
312         local $\; print $file '';       # Autoflush the file if wanted
313         $@ = $da;
314         return $ret;
315 }
316
317 #
318 # freeze
319 #
320 # Store oject and its hierarchy in memory and return a scalar
321 # containing the result.
322 #
323 sub freeze {
324         _freeze(\&mstore, @_);
325 }
326
327 #
328 # nfreeze
329 #
330 # Same as freeze but in network order.
331 #
332 sub nfreeze {
333         _freeze(\&net_mstore, @_);
334 }
335
336 # Internal freeze routine
337 sub _freeze {
338         my $xsptr = shift;
339         my $self = shift;
340         logcroak "not a reference" unless ref($self);
341         logcroak "too many arguments" unless @_ == 0;   # No @foo in arglist
342         my $da = $@;                            # Don't mess if called from exception handler
343         my $ret;
344         # Call C routine mstore or net_mstore, depending on network order
345         eval { $ret = &$xsptr($self) };
346         logcroak $@ if $@ =~ s/\.?\n$/,/;
347         $@ = $da;
348         return $ret ? $ret : undef;
349 }
350
351 #
352 # retrieve
353 #
354 # Retrieve object hierarchy from disk, returning a reference to the root
355 # object of that tree.
356 #
357 sub retrieve {
358         _retrieve($_[0], 0);
359 }
360
361 #
362 # lock_retrieve
363 #
364 # Same as retrieve, but with advisory locking.
365 #
366 sub lock_retrieve {
367         _retrieve($_[0], 1);
368 }
369
370 # Internal retrieve routine
371 sub _retrieve {
372         my ($file, $use_locking) = @_;
373         local *FILE;
374         open(FILE, $file) || logcroak "can't open $file: $!";
375         binmode FILE;                                                   # Archaic systems...
376         my $self;
377         my $da = $@;                                                    # Could be from exception handler
378         if ($use_locking) {
379                 unless (&CAN_FLOCK) {
380                         logcarp "Storable::lock_store: fcntl/flock emulation broken on $^O";
381                         return undef;
382                 }
383                 flock(FILE, LOCK_SH) || logcroak "can't get shared lock on $file: $!";
384                 # Unlocking will happen when FILE is closed
385         }
386         eval { $self = pretrieve(*FILE) };              # Call C routine
387         close(FILE);
388         logcroak $@ if $@ =~ s/\.?\n$/,/;
389         $@ = $da;
390         return $self;
391 }
392
393 #
394 # fd_retrieve
395 #
396 # Same as retrieve, but perform from an already opened file descriptor instead.
397 #
398 sub fd_retrieve {
399         my ($file) = @_;
400         my $fd = fileno($file);
401         logcroak "not a valid file descriptor" unless defined $fd;
402         my $self;
403         my $da = $@;                                                    # Could be from exception handler
404         eval { $self = pretrieve($file) };              # Call C routine
405         logcroak $@ if $@ =~ s/\.?\n$/,/;
406         $@ = $da;
407         return $self;
408 }
409
410 #
411 # thaw
412 #
413 # Recreate objects in memory from an existing frozen image created
414 # by freeze.  If the frozen image passed is undef, return undef.
415 #
416 sub thaw {
417         my ($frozen) = @_;
418         return undef unless defined $frozen;
419         my $self;
420         my $da = $@;                                                    # Could be from exception handler
421         eval { $self = mretrieve($frozen) };    # Call C routine
422         logcroak $@ if $@ =~ s/\.?\n$/,/;
423         $@ = $da;
424         return $self;
425 }
426
427 1;
428 __END__
429
430 =head1 NAME
431
432 Storable - persistence for Perl data structures
433
434 =head1 SYNOPSIS
435
436  use Storable;
437  store \%table, 'file';
438  $hashref = retrieve('file');
439
440  use Storable qw(nstore store_fd nstore_fd freeze thaw dclone);
441
442  # Network order
443  nstore \%table, 'file';
444  $hashref = retrieve('file');   # There is NO nretrieve()
445
446  # Storing to and retrieving from an already opened file
447  store_fd \@array, \*STDOUT;
448  nstore_fd \%table, \*STDOUT;
449  $aryref = fd_retrieve(\*SOCKET);
450  $hashref = fd_retrieve(\*SOCKET);
451
452  # Serializing to memory
453  $serialized = freeze \%table;
454  %table_clone = %{ thaw($serialized) };
455
456  # Deep (recursive) cloning
457  $cloneref = dclone($ref);
458
459  # Advisory locking
460  use Storable qw(lock_store lock_nstore lock_retrieve)
461  lock_store \%table, 'file';
462  lock_nstore \%table, 'file';
463  $hashref = lock_retrieve('file');
464
465 =head1 DESCRIPTION
466
467 The Storable package brings persistence to your Perl data structures
468 containing SCALAR, ARRAY, HASH or REF objects, i.e. anything that can be
469 conveniently stored to disk and retrieved at a later time.
470
471 It can be used in the regular procedural way by calling C<store> with
472 a reference to the object to be stored, along with the file name where
473 the image should be written.
474
475 The routine returns C<undef> for I/O problems or other internal error,
476 a true value otherwise. Serious errors are propagated as a C<die> exception.
477
478 To retrieve data stored to disk, use C<retrieve> with a file name.
479 The objects stored into that file are recreated into memory for you,
480 and a I<reference> to the root object is returned. In case an I/O error
481 occurs while reading, C<undef> is returned instead. Other serious
482 errors are propagated via C<die>.
483
484 Since storage is performed recursively, you might want to stuff references
485 to objects that share a lot of common data into a single array or hash
486 table, and then store that object. That way, when you retrieve back the
487 whole thing, the objects will continue to share what they originally shared.
488
489 At the cost of a slight header overhead, you may store to an already
490 opened file descriptor using the C<store_fd> routine, and retrieve
491 from a file via C<fd_retrieve>. Those names aren't imported by default,
492 so you will have to do that explicitly if you need those routines.
493 The file descriptor you supply must be already opened, for read
494 if you're going to retrieve and for write if you wish to store.
495
496         store_fd(\%table, *STDOUT) || die "can't store to stdout\n";
497         $hashref = fd_retrieve(*STDIN);
498
499 You can also store data in network order to allow easy sharing across
500 multiple platforms, or when storing on a socket known to be remotely
501 connected. The routines to call have an initial C<n> prefix for I<network>,
502 as in C<nstore> and C<nstore_fd>. At retrieval time, your data will be
503 correctly restored so you don't have to know whether you're restoring
504 from native or network ordered data.  Double values are stored stringified
505 to ensure portability as well, at the slight risk of loosing some precision
506 in the last decimals.
507
508 When using C<fd_retrieve>, objects are retrieved in sequence, one
509 object (i.e. one recursive tree) per associated C<store_fd>.
510
511 If you're more from the object-oriented camp, you can inherit from
512 Storable and directly store your objects by invoking C<store> as
513 a method. The fact that the root of the to-be-stored tree is a
514 blessed reference (i.e. an object) is special-cased so that the
515 retrieve does not provide a reference to that object but rather the
516 blessed object reference itself. (Otherwise, you'd get a reference
517 to that blessed object).
518
519 =head1 MEMORY STORE
520
521 The Storable engine can also store data into a Perl scalar instead, to
522 later retrieve them. This is mainly used to freeze a complex structure in
523 some safe compact memory place (where it can possibly be sent to another
524 process via some IPC, since freezing the structure also serializes it in
525 effect). Later on, and maybe somewhere else, you can thaw the Perl scalar
526 out and recreate the original complex structure in memory.
527
528 Surprisingly, the routines to be called are named C<freeze> and C<thaw>.
529 If you wish to send out the frozen scalar to another machine, use
530 C<nfreeze> instead to get a portable image.
531
532 Note that freezing an object structure and immediately thawing it
533 actually achieves a deep cloning of that structure:
534
535     dclone(.) = thaw(freeze(.))
536
537 Storable provides you with a C<dclone> interface which does not create
538 that intermediary scalar but instead freezes the structure in some
539 internal memory space and then immediately thaws it out.
540
541 =head1 ADVISORY LOCKING
542
543 The C<lock_store> and C<lock_nstore> routine are equivalent to
544 C<store> and C<nstore>, except that they get an exclusive lock on
545 the file before writing.  Likewise, C<lock_retrieve> does the same
546 as C<retrieve>, but also gets a shared lock on the file before reading.
547
548 As with any advisory locking scheme, the protection only works if you
549 systematically use C<lock_store> and C<lock_retrieve>.  If one side of
550 your application uses C<store> whilst the other uses C<lock_retrieve>,
551 you will get no protection at all.
552
553 The internal advisory locking is implemented using Perl's flock()
554 routine.  If your system does not support any form of flock(), or if
555 you share your files across NFS, you might wish to use other forms
556 of locking by using modules such as LockFile::Simple which lock a
557 file using a filesystem entry, instead of locking the file descriptor.
558
559 =head1 SPEED
560
561 The heart of Storable is written in C for decent speed. Extra low-level
562 optimizations have been made when manipulating perl internals, to
563 sacrifice encapsulation for the benefit of greater speed.
564
565 =head1 CANONICAL REPRESENTATION
566
567 Normally, Storable stores elements of hashes in the order they are
568 stored internally by Perl, i.e. pseudo-randomly.  If you set
569 C<$Storable::canonical> to some C<TRUE> value, Storable will store
570 hashes with the elements sorted by their key.  This allows you to
571 compare data structures by comparing their frozen representations (or
572 even the compressed frozen representations), which can be useful for
573 creating lookup tables for complicated queries.
574
575 Canonical order does not imply network order; those are two orthogonal
576 settings.
577
578 =head1 CODE REFERENCES
579
580 Since Storable version 2.05, CODE references may be serialized with
581 the help of L<B::Deparse>. To enable this feature, set
582 C<$Storable::Deparse> to a true value. To enable deserialization,
583 C<$Storable::Eval> should be set to a true value. Be aware that
584 deserialization is done through C<eval>, which is dangerous if the
585 Storable file contains malicious data. You can set C<$Storable::Eval>
586 to a subroutine reference which would be used instead of C<eval>. See
587 below for an example using a L<Safe> compartment for deserialization
588 of CODE references.
589
590 If C<$Storable::Deparse> and/or C<$Storable::Eval> are set to false
591 values, then the value of C<$Storable::forgive_me> (see below) is
592 respected while serializing and deserializing.
593
594 =head1 FORWARD COMPATIBILITY
595
596 This release of Storable can be used on a newer version of Perl to
597 serialize data which is not supported by earlier Perls.  By default,
598 Storable will attempt to do the right thing, by C<croak()>ing if it
599 encounters data that it cannot deserialize.  However, the defaults
600 can be changed as follows:
601
602 =over 4
603
604 =item utf8 data
605
606 Perl 5.6 added support for Unicode characters with code points > 255,
607 and Perl 5.8 has full support for Unicode characters in hash keys.
608 Perl internally encodes strings with these characters using utf8, and
609 Storable serializes them as utf8.  By default, if an older version of
610 Perl encounters a utf8 value it cannot represent, it will C<croak()>.
611 To change this behaviour so that Storable deserializes utf8 encoded
612 values as the string of bytes (effectively dropping the I<is_utf8> flag)
613 set C<$Storable::drop_utf8> to some C<TRUE> value.  This is a form of
614 data loss, because with C<$drop_utf8> true, it becomes impossible to tell
615 whether the original data was the Unicode string, or a series of bytes
616 that happen to be valid utf8.
617
618 =item restricted hashes
619
620 Perl 5.8 adds support for restricted hashes, which have keys
621 restricted to a given set, and can have values locked to be read only.
622 By default, when Storable encounters a restricted hash on a perl
623 that doesn't support them, it will deserialize it as a normal hash,
624 silently discarding any placeholder keys and leaving the keys and
625 all values unlocked.  To make Storable C<croak()> instead, set
626 C<$Storable::downgrade_restricted> to a C<FALSE> value.  To restore
627 the default set it back to some C<TRUE> value.
628
629 =item files from future versions of Storable
630
631 Earlier versions of Storable would immediately croak if they encountered
632 a file with a higher internal version number than the reading Storable
633 knew about.  Internal version numbers are increased each time new data
634 types (such as restricted hashes) are added to the vocabulary of the file
635 format.  This meant that a newer Storable module had no way of writing a
636 file readable by an older Storable, even if the writer didn't store newer
637 data types.
638
639 This version of Storable will defer croaking until it encounters a data
640 type in the file that it does not recognize.  This means that it will
641 continue to read files generated by newer Storable modules which are careful
642 in what they write out, making it easier to upgrade Storable modules in a
643 mixed environment.
644
645 The old behaviour of immediate croaking can be re-instated by setting
646 C<$Storable::accept_future_minor> to some C<FALSE> value.
647
648 =back
649
650 All these variables have no effect on a newer Perl which supports the
651 relevant feature.
652
653 =head1 ERROR REPORTING
654
655 Storable uses the "exception" paradigm, in that it does not try to workaround
656 failures: if something bad happens, an exception is generated from the
657 caller's perspective (see L<Carp> and C<croak()>).  Use eval {} to trap
658 those exceptions.
659
660 When Storable croaks, it tries to report the error via the C<logcroak()>
661 routine from the C<Log::Agent> package, if it is available.
662
663 Normal errors are reported by having store() or retrieve() return C<undef>.
664 Such errors are usually I/O errors (or truncated stream errors at retrieval).
665
666 =head1 WIZARDS ONLY
667
668 =head2 Hooks
669
670 Any class may define hooks that will be called during the serialization
671 and deserialization process on objects that are instances of that class.
672 Those hooks can redefine the way serialization is performed (and therefore,
673 how the symmetrical deserialization should be conducted).
674
675 Since we said earlier:
676
677     dclone(.) = thaw(freeze(.))
678
679 everything we say about hooks should also hold for deep cloning. However,
680 hooks get to know whether the operation is a mere serialization, or a cloning.
681
682 Therefore, when serializing hooks are involved,
683
684     dclone(.) <> thaw(freeze(.))
685
686 Well, you could keep them in sync, but there's no guarantee it will always
687 hold on classes somebody else wrote.  Besides, there is little to gain in
688 doing so: a serializing hook could keep only one attribute of an object,
689 which is probably not what should happen during a deep cloning of that
690 same object.
691
692 Here is the hooking interface:
693
694 =over 4
695
696 =item C<STORABLE_freeze> I<obj>, I<cloning>
697
698 The serializing hook, called on the object during serialization.  It can be
699 inherited, or defined in the class itself, like any other method.
700
701 Arguments: I<obj> is the object to serialize, I<cloning> is a flag indicating
702 whether we're in a dclone() or a regular serialization via store() or freeze().
703
704 Returned value: A LIST C<($serialized, $ref1, $ref2, ...)> where $serialized
705 is the serialized form to be used, and the optional $ref1, $ref2, etc... are
706 extra references that you wish to let the Storable engine serialize.
707
708 At deserialization time, you will be given back the same LIST, but all the
709 extra references will be pointing into the deserialized structure.
710
711 The B<first time> the hook is hit in a serialization flow, you may have it
712 return an empty list.  That will signal the Storable engine to further
713 discard that hook for this class and to therefore revert to the default
714 serialization of the underlying Perl data.  The hook will again be normally
715 processed in the next serialization.
716
717 Unless you know better, serializing hook should always say:
718
719     sub STORABLE_freeze {
720         my ($self, $cloning) = @_;
721         return if $cloning;         # Regular default serialization
722         ....
723     }
724
725 in order to keep reasonable dclone() semantics.
726
727 =item C<STORABLE_thaw> I<obj>, I<cloning>, I<serialized>, ...
728
729 The deserializing hook called on the object during deserialization.
730 But wait: if we're deserializing, there's no object yet... right?
731
732 Wrong: the Storable engine creates an empty one for you.  If you know Eiffel,
733 you can view C<STORABLE_thaw> as an alternate creation routine.
734
735 This means the hook can be inherited like any other method, and that
736 I<obj> is your blessed reference for this particular instance.
737
738 The other arguments should look familiar if you know C<STORABLE_freeze>:
739 I<cloning> is true when we're part of a deep clone operation, I<serialized>
740 is the serialized string you returned to the engine in C<STORABLE_freeze>,
741 and there may be an optional list of references, in the same order you gave
742 them at serialization time, pointing to the deserialized objects (which
743 have been processed courtesy of the Storable engine).
744
745 When the Storable engine does not find any C<STORABLE_thaw> hook routine,
746 it tries to load the class by requiring the package dynamically (using
747 the blessed package name), and then re-attempts the lookup.  If at that
748 time the hook cannot be located, the engine croaks.  Note that this mechanism
749 will fail if you define several classes in the same file, but L<perlmod>
750 warned you.
751
752 It is up to you to use this information to populate I<obj> the way you want.
753
754 Returned value: none.
755
756 =item C<STORABLE_attach> I<class>, I<cloning>, I<serialized>
757
758 While C<STORABLE_freeze> and C<STORABLE_thaw> are useful for classes where
759 each instance is independent, this mechanism has difficulty (or is
760 incompatible) with objects that exist as common process-level or
761 system-level resources, such as singleton objects, database pools, caches
762 or memoized objects.
763
764 The alternative C<STORABLE_attach> method provides a solution for these
765 shared objects. Instead of C<STORABLE_freeze> --E<gt> C<STORABLE_thaw>,
766 you implement C<STORABLE_freeze> --E<gt> C<STORABLE_attach> instead.
767
768 Arguments: I<class> is the class we are attaching to, I<cloning> is a flag
769 indicating whether we're in a dclone() or a regular de-serialization via
770 thaw(), and I<serialized> is the stored string for the resource object.
771
772 Because these resource objects are considered to be owned by the entire
773 process/system, and not the "property" of whatever is being serialized,
774 no references underneath the object should be included in the serialized
775 string. Thus, in any class that implements C<STORABLE_attach>, the
776 C<STORABLE_freeze> method cannot return any references, and C<Storable>
777 will throw an error if C<STORABLE_freeze> tries to return references.
778
779 All information required to "attach" back to the shared resource object
780 B<must> be contained B<only> in the C<STORABLE_freeze> return string.
781 Otherwise, C<STORABLE_freeze> behaves as normal for C<STORABLE_attach>
782 classes.
783
784 Because C<STORABLE_attach> is passed the class (rather than an object),
785 it also returns the object directly, rather than modifying the passed
786 object.
787
788 Returned value: object of type C<class>
789
790 =back
791
792 =head2 Predicates
793
794 Predicates are not exportable.  They must be called by explicitly prefixing
795 them with the Storable package name.
796
797 =over 4
798
799 =item C<Storable::last_op_in_netorder>
800
801 The C<Storable::last_op_in_netorder()> predicate will tell you whether
802 network order was used in the last store or retrieve operation.  If you
803 don't know how to use this, just forget about it.
804
805 =item C<Storable::is_storing>
806
807 Returns true if within a store operation (via STORABLE_freeze hook).
808
809 =item C<Storable::is_retrieving>
810
811 Returns true if within a retrieve operation (via STORABLE_thaw hook).
812
813 =back
814
815 =head2 Recursion
816
817 With hooks comes the ability to recurse back to the Storable engine.
818 Indeed, hooks are regular Perl code, and Storable is convenient when
819 it comes to serializing and deserializing things, so why not use it
820 to handle the serialization string?
821
822 There are a few things you need to know, however:
823
824 =over 4
825
826 =item *
827
828 You can create endless loops if the things you serialize via freeze()
829 (for instance) point back to the object we're trying to serialize in
830 the hook.
831
832 =item *
833
834 Shared references among objects will not stay shared: if we're serializing
835 the list of object [A, C] where both object A and C refer to the SAME object
836 B, and if there is a serializing hook in A that says freeze(B), then when
837 deserializing, we'll get [A', C'] where A' refers to B', but C' refers to D,
838 a deep clone of B'.  The topology was not preserved.
839
840 =back
841
842 That's why C<STORABLE_freeze> lets you provide a list of references
843 to serialize.  The engine guarantees that those will be serialized in the
844 same context as the other objects, and therefore that shared objects will
845 stay shared.
846
847 In the above [A, C] example, the C<STORABLE_freeze> hook could return:
848
849         ("something", $self->{B})
850
851 and the B part would be serialized by the engine.  In C<STORABLE_thaw>, you
852 would get back the reference to the B' object, deserialized for you.
853
854 Therefore, recursion should normally be avoided, but is nonetheless supported.
855
856 =head2 Deep Cloning
857
858 There is a Clone module available on CPAN which implements deep cloning
859 natively, i.e. without freezing to memory and thawing the result.  It is
860 aimed to replace Storable's dclone() some day.  However, it does not currently
861 support Storable hooks to redefine the way deep cloning is performed.
862
863 =head1 Storable magic
864
865 Yes, there's a lot of that :-) But more precisely, in UNIX systems
866 there's a utility called C<file>, which recognizes data files based on
867 their contents (usually their first few bytes).  For this to work,
868 a certain file called F<magic> needs to taught about the I<signature>
869 of the data.  Where that configuration file lives depends on the UNIX
870 flavour; often it's something like F</usr/share/misc/magic> or
871 F</etc/magic>.  Your system administrator needs to do the updating of
872 the F<magic> file.  The necessary signature information is output to
873 STDOUT by invoking Storable::show_file_magic().  Note that the GNU
874 implementation of the C<file> utility, version 3.38 or later,
875 is expected to contain support for recognising Storable files
876 out-of-the-box, in addition to other kinds of Perl files.
877
878 You can also use the following functions to extract the file header
879 information from Storable images:
880
881 =over
882
883 =item $info = Storable::file_magic( $filename )
884
885 If the given file is a Storable image return a hash describing it.  If
886 the file is readable, but not a Storable image return C<undef>.  If
887 the file does not exist or is unreadable then croak.
888
889 The hash returned has the following elements:
890
891 =over
892
893 =item C<version>
894
895 This returns the file format version.  It is a string like "2.7".
896
897 Note that this version number is not the same as the version number of
898 the Storable module itself.  For instance Storable v0.7 create files
899 in format v2.0 and Storable v2.15 create files in format v2.7.  The
900 file format version number only increment when additional features
901 that would confuse older versions of the module are added.
902
903 Files older than v2.0 will have the one of the version numbers "-1",
904 "0" or "1".  No minor number was used at that time.
905
906 =item C<version_nv>
907
908 This returns the file format version as number.  It is a string like
909 "2.007".  This value is suitable for numeric comparisons.
910
911 The constant function C<Storable::BIN_VERSION_NV> returns a comparable
912 number that represent the highest file version number that this
913 version of Storable fully support (but see discussion of
914 C<$Storable::accept_future_minor> above).  The constant
915 C<Storable::BIN_WRITE_VERSION_NV> function returns what file version
916 is written and might be less than C<Storable::BIN_VERSION_NV> in some
917 configurations.
918
919 =item C<major>, C<minor>
920
921 This also returns the file format version.  If the version is "2.7"
922 then major would be 2 and minor would be 7.  The minor element is
923 missing for when major is less than 2.
924
925 =item C<hdrsize>
926
927 The is the number of bytes that the Storable header occupies.
928
929 =item C<netorder>
930
931 This is TRUE if the image store data in network order.  This means
932 that it was created with nstore() or similar.
933
934 =item C<byteorder>
935
936 This is only present when C<netorder> is FALSE.  It is the
937 $Config{byteorder} string of the perl that created this image.  It is
938 a string like "1234" (32 bit little endian) or "87654321" (64 bit big
939 endian).  This must match the current perl for the image to be
940 readable by Storable.
941
942 =item C<intsize>, C<longsize>, C<ptrsize>, C<nvsize>
943
944 These are only present when C<netorder> is FALSE. These are the sizes of
945 various C datatypes of the perl that created this image.  These must
946 match the current perl for the image to be readable by Storable.
947
948 The C<nvsize> element is only present for file format v2.2 and
949 higher.
950
951 =item C<file>
952
953 The name of the file.
954
955 =back
956
957 =item $info = Storable::read_magic( $buffer )
958
959 =item $info = Storable::read_magic( $buffer, $must_be_file )
960
961 The $buffer should be a Storable image or the first few bytes of it.
962 If $buffer starts with a Storable header, then a hash describing the
963 image is returned, otherwise C<undef> is returned.
964
965 The hash has the same structure as the one returned by
966 Storable::file_magic().  The C<file> element is true if the image is a
967 file image.
968
969 If the $must_be_file argument is provided and is TRUE, then return
970 C<undef> unless the image looks like it belongs to a file dump.
971
972 The maximum size of a Storable header is currently 21 bytes.  If the
973 provided $buffer is only the first part of a Storable image it should
974 at least be this long to ensure that read_magic() will recognize it as
975 such.
976
977 =back
978
979 =head1 EXAMPLES
980
981 Here are some code samples showing a possible usage of Storable:
982
983         use Storable qw(store retrieve freeze thaw dclone);
984
985         %color = ('Blue' => 0.1, 'Red' => 0.8, 'Black' => 0, 'White' => 1);
986
987         store(\%color, 'mycolors') or die "Can't store %a in mycolors!\n";
988
989         $colref = retrieve('mycolors');
990         die "Unable to retrieve from mycolors!\n" unless defined $colref;
991         printf "Blue is still %lf\n", $colref->{'Blue'};
992
993         $colref2 = dclone(\%color);
994
995         $str = freeze(\%color);
996         printf "Serialization of %%color is %d bytes long.\n", length($str);
997         $colref3 = thaw($str);
998
999 which prints (on my machine):
1000
1001         Blue is still 0.100000
1002         Serialization of %color is 102 bytes long.
1003
1004 Serialization of CODE references and deserialization in a safe
1005 compartment:
1006
1007 =for example begin
1008
1009         use Storable qw(freeze thaw);
1010         use Safe;
1011         use strict;
1012         my $safe = new Safe;
1013         # because of opcodes used in "use strict":
1014         $safe->permit(qw(:default require));
1015         local $Storable::Deparse = 1;
1016         local $Storable::Eval = sub { $safe->reval($_[0]) };
1017         my $serialized = freeze(sub { 42 });
1018         my $code = thaw($serialized);
1019         $code->() == 42;
1020
1021 =for example end
1022
1023 =for example_testing
1024         is( $code->(), 42 );
1025
1026 =head1 WARNING
1027
1028 If you're using references as keys within your hash tables, you're bound
1029 to be disappointed when retrieving your data. Indeed, Perl stringifies
1030 references used as hash table keys. If you later wish to access the
1031 items via another reference stringification (i.e. using the same
1032 reference that was used for the key originally to record the value into
1033 the hash table), it will work because both references stringify to the
1034 same string.
1035
1036 It won't work across a sequence of C<store> and C<retrieve> operations,
1037 however, because the addresses in the retrieved objects, which are
1038 part of the stringified references, will probably differ from the
1039 original addresses. The topology of your structure is preserved,
1040 but not hidden semantics like those.
1041
1042 On platforms where it matters, be sure to call C<binmode()> on the
1043 descriptors that you pass to Storable functions.
1044
1045 Storing data canonically that contains large hashes can be
1046 significantly slower than storing the same data normally, as
1047 temporary arrays to hold the keys for each hash have to be allocated,
1048 populated, sorted and freed.  Some tests have shown a halving of the
1049 speed of storing -- the exact penalty will depend on the complexity of
1050 your data.  There is no slowdown on retrieval.
1051
1052 =head1 BUGS
1053
1054 You can't store GLOB, FORMLINE, REGEXP, etc.... If you can define semantics
1055 for those operations, feel free to enhance Storable so that it can
1056 deal with them.
1057
1058 The store functions will C<croak> if they run into such references
1059 unless you set C<$Storable::forgive_me> to some C<TRUE> value. In that
1060 case, the fatal message is turned in a warning and some
1061 meaningless string is stored instead.
1062
1063 Setting C<$Storable::canonical> may not yield frozen strings that
1064 compare equal due to possible stringification of numbers. When the
1065 string version of a scalar exists, it is the form stored; therefore,
1066 if you happen to use your numbers as strings between two freezing
1067 operations on the same data structures, you will get different
1068 results.
1069
1070 When storing doubles in network order, their value is stored as text.
1071 However, you should also not expect non-numeric floating-point values
1072 such as infinity and "not a number" to pass successfully through a
1073 nstore()/retrieve() pair.
1074
1075 As Storable neither knows nor cares about character sets (although it
1076 does know that characters may be more than eight bits wide), any difference
1077 in the interpretation of character codes between a host and a target
1078 system is your problem.  In particular, if host and target use different
1079 code points to represent the characters used in the text representation
1080 of floating-point numbers, you will not be able be able to exchange
1081 floating-point data, even with nstore().
1082
1083 C<Storable::drop_utf8> is a blunt tool.  There is no facility either to
1084 return B<all> strings as utf8 sequences, or to attempt to convert utf8
1085 data back to 8 bit and C<croak()> if the conversion fails.
1086
1087 Prior to Storable 2.01, no distinction was made between signed and
1088 unsigned integers on storing.  By default Storable prefers to store a
1089 scalars string representation (if it has one) so this would only cause
1090 problems when storing large unsigned integers that had never been converted
1091 to string or floating point.  In other words values that had been generated
1092 by integer operations such as logic ops and then not used in any string or
1093 arithmetic context before storing.
1094
1095 =head2 64 bit data in perl 5.6.0 and 5.6.1
1096
1097 This section only applies to you if you have existing data written out
1098 by Storable 2.02 or earlier on perl 5.6.0 or 5.6.1 on Unix or Linux which
1099 has been configured with 64 bit integer support (not the default)
1100 If you got a precompiled perl, rather than running Configure to build
1101 your own perl from source, then it almost certainly does not affect you,
1102 and you can stop reading now (unless you're curious). If you're using perl
1103 on Windows it does not affect you.
1104
1105 Storable writes a file header which contains the sizes of various C
1106 language types for the C compiler that built Storable (when not writing in
1107 network order), and will refuse to load files written by a Storable not
1108 on the same (or compatible) architecture.  This check and a check on
1109 machine byteorder is needed because the size of various fields in the file
1110 are given by the sizes of the C language types, and so files written on
1111 different architectures are incompatible.  This is done for increased speed.
1112 (When writing in network order, all fields are written out as standard
1113 lengths, which allows full interworking, but takes longer to read and write)
1114
1115 Perl 5.6.x introduced the ability to optional configure the perl interpreter
1116 to use C's C<long long> type to allow scalars to store 64 bit integers on 32
1117 bit systems.  However, due to the way the Perl configuration system
1118 generated the C configuration files on non-Windows platforms, and the way
1119 Storable generates its header, nothing in the Storable file header reflected
1120 whether the perl writing was using 32 or 64 bit integers, despite the fact
1121 that Storable was storing some data differently in the file.  Hence Storable
1122 running on perl with 64 bit integers will read the header from a file
1123 written by a 32 bit perl, not realise that the data is actually in a subtly
1124 incompatible format, and then go horribly wrong (possibly crashing) if it
1125 encountered a stored integer.  This is a design failure.
1126
1127 Storable has now been changed to write out and read in a file header with
1128 information about the size of integers.  It's impossible to detect whether
1129 an old file being read in was written with 32 or 64 bit integers (they have
1130 the same header) so it's impossible to automatically switch to a correct
1131 backwards compatibility mode.  Hence this Storable defaults to the new,
1132 correct behaviour.
1133
1134 What this means is that if you have data written by Storable 1.x running
1135 on perl 5.6.0 or 5.6.1 configured with 64 bit integers on Unix or Linux
1136 then by default this Storable will refuse to read it, giving the error
1137 I<Byte order is not compatible>.  If you have such data then you you
1138 should set C<$Storable::interwork_56_64bit> to a true value to make this
1139 Storable read and write files with the old header.  You should also
1140 migrate your data, or any older perl you are communicating with, to this
1141 current version of Storable.
1142
1143 If you don't have data written with specific configuration of perl described
1144 above, then you do not and should not do anything.  Don't set the flag -
1145 not only will Storable on an identically configured perl refuse to load them,
1146 but Storable a differently configured perl will load them believing them
1147 to be correct for it, and then may well fail or crash part way through
1148 reading them.
1149
1150 =head1 CREDITS
1151
1152 Thank you to (in chronological order):
1153
1154         Jarkko Hietaniemi <jhi@iki.fi>
1155         Ulrich Pfeifer <pfeifer@charly.informatik.uni-dortmund.de>
1156         Benjamin A. Holzman <bholzman@earthlink.net>
1157         Andrew Ford <A.Ford@ford-mason.co.uk>
1158         Gisle Aas <gisle@aas.no>
1159         Jeff Gresham <gresham_jeffrey@jpmorgan.com>
1160         Murray Nesbitt <murray@activestate.com>
1161         Marc Lehmann <pcg@opengroup.org>
1162         Justin Banks <justinb@wamnet.com>
1163         Jarkko Hietaniemi <jhi@iki.fi> (AGAIN, as perl 5.7.0 Pumpkin!)
1164         Salvador Ortiz Garcia <sog@msg.com.mx>
1165         Dominic Dunlop <domo@computer.org>
1166         Erik Haugan <erik@solbors.no>
1167     Benjamin A. Holzman <ben.holzman@grantstreet.com>
1168
1169 for their bug reports, suggestions and contributions.
1170
1171 Benjamin Holzman contributed the tied variable support, Andrew Ford
1172 contributed the canonical order for hashes, and Gisle Aas fixed
1173 a few misunderstandings of mine regarding the perl internals,
1174 and optimized the emission of "tags" in the output streams by
1175 simply counting the objects instead of tagging them (leading to
1176 a binary incompatibility for the Storable image starting at version
1177 0.6--older images are, of course, still properly understood).
1178 Murray Nesbitt made Storable thread-safe.  Marc Lehmann added overloading
1179 and references to tied items support.  Benjamin Holzman added a performance
1180 improvement for overloaded classes; thanks to Grant Street Group for footing
1181 the bill.
1182
1183 =head1 AUTHOR
1184
1185 Storable was written by Raphael Manfredi F<E<lt>Raphael_Manfredi@pobox.comE<gt>>
1186 Maintenance is now done by the perl5-porters F<E<lt>perl5-porters@perl.orgE<gt>>
1187
1188 Please e-mail us with problems, bug fixes, comments and complaints,
1189 although if you have compliments you should send them to Raphael.
1190 Please don't e-mail Raphael with problems, as he no longer works on
1191 Storable, and your message will be delayed while he forwards it to us.
1192
1193 =head1 SEE ALSO
1194
1195 L<Clone>.
1196
1197 =cut