This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
two and a half steps further for WinCE cross-build
[perl5.git] / ext / Storable / Storable.pm
CommitLineData
596596d5 1;# $Id: Storable.pm,v 1.0.1.13 2001/12/01 13:34:49 ram Exp $
7a6a85bf
RG
2;#
3;# Copyright (c) 1995-2000, Raphael Manfredi
4;#
9e21b3d0
JH
5;# You may redistribute only under the same terms as Perl 5, as specified
6;# in the README file that comes with the distribution.
7a6a85bf
RG
7;#
8;# $Log: Storable.pm,v $
596596d5
JH
9;# Revision 1.0.1.13 2001/12/01 13:34:49 ram
10;# patch14: avoid requiring Fcntl upfront, useful to embedded runtimes
11;# patch14: store_fd() will now correctly autoflush file if needed
12;#
6e0ac6f5
JH
13;# Revision 1.0.1.12 2001/08/28 21:51:51 ram
14;# patch13: fixed truncation race with lock_retrieve() in lock_store()
15;#
e993d95c
JH
16;# Revision 1.0.1.11 2001/07/01 11:22:14 ram
17;# patch12: systematically use "=over 4" for POD linters
18;# patch12: updated version number
19;#
8be2b38b
JH
20;# Revision 1.0.1.10 2001/03/15 00:20:25 ram
21;# patch11: updated version number
22;#
23;# Revision 1.0.1.9 2001/02/17 12:37:32 ram
24;# patch10: forgot to increase version number at previous patch
25;#
b12202d0
JH
26;# Revision 1.0.1.8 2001/02/17 12:24:37 ram
27;# patch8: fixed incorrect error message
28;#
862382c7
JH
29;# Revision 1.0.1.7 2001/01/03 09:39:02 ram
30;# patch7: added CAN_FLOCK to determine whether we can flock() or not
31;#
90826881
JH
32;# Revision 1.0.1.6 2000/11/05 17:20:25 ram
33;# patch6: increased version number
34;#
212e9bde
JH
35;# Revision 1.0.1.5 2000/10/26 17:10:18 ram
36;# patch5: documented that store() and retrieve() can return undef
37;# patch5: added paragraph explaining the auto require for thaw hooks
38;#
39;# Revision 1.0.1.4 2000/10/23 18:02:57 ram
40;# patch4: protected calls to flock() for dos platform
41;# patch4: added logcarp emulation if they don't have Log::Agent
42;#
8be2b38b
JH
43;# Revision 1.0.1.3 2000/09/29 19:49:01 ram
44;# patch3: updated version number
45;#
46;# Revision 1.0.1.2 2000/09/28 21:42:51 ram
47;# patch2: added lock_store lock_nstore lock_retrieve
48;#
49;# Revision 1.0.1.1 2000/09/17 16:46:21 ram
50;# patch1: documented that doubles are stringified by nstore()
51;# patch1: added Salvador Ortiz Garcia in CREDITS section
52;#
9e21b3d0
JH
53;# Revision 1.0 2000/09/01 19:40:41 ram
54;# Baseline for first official release.
7a6a85bf
RG
55;#
56
57require DynaLoader;
58require Exporter;
59package Storable; @ISA = qw(Exporter DynaLoader);
60
61@EXPORT = qw(store retrieve);
62@EXPORT_OK = qw(
9e21b3d0 63 nstore store_fd nstore_fd fd_retrieve
7a6a85bf
RG
64 freeze nfreeze thaw
65 dclone
9e21b3d0 66 retrieve_fd
dd19458b 67 lock_store lock_nstore lock_retrieve
7a6a85bf
RG
68);
69
70use AutoLoader;
71use vars qw($forgive_me $VERSION);
72
0a0da639 73$VERSION = '1.015';
7a6a85bf
RG
74*AUTOLOAD = \&AutoLoader::AUTOLOAD; # Grrr...
75
76#
77# Use of Log::Agent is optional
78#
79
80eval "use Log::Agent";
81
530b72ba 82require Carp;
7a6a85bf 83
dd19458b
JH
84#
85# They might miss :flock in Fcntl
86#
87
88BEGIN {
596596d5 89 if (eval { require Fcntl; 1 } && exists $Fcntl::EXPORT_TAGS{'flock'}) {
dd19458b
JH
90 Fcntl->import(':flock');
91 } else {
92 eval q{
93 sub LOCK_SH () {1}
94 sub LOCK_EX () {2}
95 };
96 }
97}
98
b8778c7c 99# Can't Autoload cleanly as this clashes 8.3 with &retrieve
9e21b3d0 100sub retrieve_fd { &fd_retrieve } # Backward compatibility
cb3d9de5 101
530b72ba
NC
102# By default restricted hashes are downgraded on earlier perls.
103
104$Storable::downgrade_restricted = 1;
b8778c7c
NC
105bootstrap Storable;
1061;
107__END__
530b72ba
NC
108#
109# Use of Log::Agent is optional. If it hasn't imported these subs then
110# Autoloader will kindly supply our fallback implementation.
111#
112
113sub logcroak {
114 Carp::croak(@_);
115}
116
117sub logcarp {
118 Carp::carp(@_);
119}
b8778c7c 120
862382c7
JH
121#
122# Determine whether locking is possible, but only when needed.
123#
124
530b72ba 125sub CAN_FLOCK; my $CAN_FLOCK; sub CAN_FLOCK {
862382c7
JH
126 return $CAN_FLOCK if defined $CAN_FLOCK;
127 require Config; import Config;
128 return $CAN_FLOCK =
129 $Config{'d_flock'} ||
130 $Config{'d_fcntl_can_lock'} ||
131 $Config{'d_lockf'};
132}
133
0a0da639
JH
134sub show_file_magic {
135 print <<EOM;
136#
137# To recognize the data files of the Perl module Storable,
138# the following lines need to be added to the local magic(5) file,
139# usually either /usr/share/misc/magic or /etc/magic.
0a0da639
JH
140#
1410 string perl-store perl Storable(v0.6) data
8b793558
JH
142>4 byte >0 (net-order %d)
143>>4 byte &01 (network-ordered)
144>>4 byte =3 (major 1)
145>>4 byte =2 (major 1)
146
0a0da639 1470 string pst0 perl Storable(v0.7) data
8b793558
JH
148>4 byte >0
149>>4 byte &01 (network-ordered)
150>>4 byte =5 (major 2)
151>>4 byte =4 (major 2)
152>>5 byte >0 (minor %d)
0a0da639
JH
153EOM
154}
155
b8778c7c
NC
156sub read_magic {
157 my $header = shift;
158 return unless defined $header and length $header > 11;
159 my $result;
160 if ($header =~ s/^perl-store//) {
161 die "Can't deal with version 0 headers";
162 } elsif ($header =~ s/^pst0//) {
163 $result->{file} = 1;
164 }
165 # Assume it's a string.
166 my ($major, $minor, $bytelen) = unpack "C3", $header;
167
168 my $net_order = $major & 1;
169 $major >>= 1;
170 @$result{qw(major minor netorder)} = ($major, $minor, $net_order);
171
172 return $result if $net_order;
173
174 # I assume that it is rare to find v1 files, so this is an intentionally
175 # inefficient way of doing it, to make the rest of the code constant.
176 if ($major < 2) {
177 delete $result->{minor};
178 $header = '.' . $header;
179 $bytelen = $minor;
180 }
181
182 @$result{qw(byteorder intsize longsize ptrsize)} =
183 unpack "x3 A$bytelen C3", $header;
184
185 if ($major >= 2 and $minor >= 2) {
186 $result->{nvsize} = unpack "x6 x$bytelen C", $header;
187 }
188 $result;
189}
7a6a85bf
RG
190
191#
192# store
193#
194# Store target object hierarchy, identified by a reference to its root.
195# The stored object tree may later be retrieved to memory via retrieve.
196# Returns undef if an I/O error occurred, in which case the file is
197# removed.
198#
199sub store {
dd19458b 200 return _store(\&pstore, @_, 0);
7a6a85bf
RG
201}
202
203#
204# nstore
205#
206# Same as store, but in network order.
207#
208sub nstore {
dd19458b
JH
209 return _store(\&net_pstore, @_, 0);
210}
211
212#
213# lock_store
214#
215# Same as store, but flock the file first (advisory locking).
216#
217sub lock_store {
218 return _store(\&pstore, @_, 1);
219}
220
221#
222# lock_nstore
223#
224# Same as nstore, but flock the file first (advisory locking).
225#
226sub lock_nstore {
227 return _store(\&net_pstore, @_, 1);
7a6a85bf
RG
228}
229
230# Internal store to file routine
231sub _store {
232 my $xsptr = shift;
233 my $self = shift;
dd19458b 234 my ($file, $use_locking) = @_;
7a6a85bf 235 logcroak "not a reference" unless ref($self);
b12202d0 236 logcroak "wrong argument number" unless @_ == 2; # No @foo in arglist
7a6a85bf 237 local *FILE;
dd19458b 238 if ($use_locking) {
6e0ac6f5 239 open(FILE, ">>$file") || logcroak "can't write into $file: $!";
862382c7 240 unless (&CAN_FLOCK) {
b29b780f
RM
241 logcarp "Storable::lock_store: fcntl/flock emulation broken on $^O";
242 return undef;
f567092b 243 }
dd19458b
JH
244 flock(FILE, LOCK_EX) ||
245 logcroak "can't get exclusive lock on $file: $!";
246 truncate FILE, 0;
247 # Unlocking will happen when FILE is closed
6e0ac6f5
JH
248 } else {
249 open(FILE, ">$file") || logcroak "can't create $file: $!";
dd19458b 250 }
6e0ac6f5 251 binmode FILE; # Archaic systems...
7a6a85bf
RG
252 my $da = $@; # Don't mess if called from exception handler
253 my $ret;
254 # Call C routine nstore or pstore, depending on network order
255 eval { $ret = &$xsptr(*FILE, $self) };
256 close(FILE) or $ret = undef;
257 unlink($file) or warn "Can't unlink $file: $!\n" if $@ || !defined $ret;
258 logcroak $@ if $@ =~ s/\.?\n$/,/;
259 $@ = $da;
260 return $ret ? $ret : undef;
261}
262
263#
264# store_fd
265#
266# Same as store, but perform on an already opened file descriptor instead.
267# Returns undef if an I/O error occurred.
268#
269sub store_fd {
270 return _store_fd(\&pstore, @_);
271}
272
273#
274# nstore_fd
275#
276# Same as store_fd, but in network order.
277#
278sub nstore_fd {
279 my ($self, $file) = @_;
280 return _store_fd(\&net_pstore, @_);
281}
282
283# Internal store routine on opened file descriptor
284sub _store_fd {
285 my $xsptr = shift;
286 my $self = shift;
287 my ($file) = @_;
288 logcroak "not a reference" unless ref($self);
289 logcroak "too many arguments" unless @_ == 1; # No @foo in arglist
290 my $fd = fileno($file);
291 logcroak "not a valid file descriptor" unless defined $fd;
292 my $da = $@; # Don't mess if called from exception handler
293 my $ret;
294 # Call C routine nstore or pstore, depending on network order
295 eval { $ret = &$xsptr($file, $self) };
296 logcroak $@ if $@ =~ s/\.?\n$/,/;
596596d5 297 local $\; print $file ''; # Autoflush the file if wanted
7a6a85bf
RG
298 $@ = $da;
299 return $ret ? $ret : undef;
300}
301
302#
303# freeze
304#
305# Store oject and its hierarchy in memory and return a scalar
306# containing the result.
307#
308sub freeze {
309 _freeze(\&mstore, @_);
310}
311
312#
313# nfreeze
314#
315# Same as freeze but in network order.
316#
317sub nfreeze {
318 _freeze(\&net_mstore, @_);
319}
320
321# Internal freeze routine
322sub _freeze {
323 my $xsptr = shift;
324 my $self = shift;
325 logcroak "not a reference" unless ref($self);
326 logcroak "too many arguments" unless @_ == 0; # No @foo in arglist
327 my $da = $@; # Don't mess if called from exception handler
328 my $ret;
329 # Call C routine mstore or net_mstore, depending on network order
330 eval { $ret = &$xsptr($self) };
331 logcroak $@ if $@ =~ s/\.?\n$/,/;
332 $@ = $da;
333 return $ret ? $ret : undef;
334}
335
336#
337# retrieve
338#
339# Retrieve object hierarchy from disk, returning a reference to the root
340# object of that tree.
341#
342sub retrieve {
dd19458b
JH
343 _retrieve($_[0], 0);
344}
345
346#
347# lock_retrieve
348#
349# Same as retrieve, but with advisory locking.
350#
351sub lock_retrieve {
352 _retrieve($_[0], 1);
353}
354
355# Internal retrieve routine
356sub _retrieve {
357 my ($file, $use_locking) = @_;
7a6a85bf 358 local *FILE;
dd19458b 359 open(FILE, $file) || logcroak "can't open $file: $!";
7a6a85bf
RG
360 binmode FILE; # Archaic systems...
361 my $self;
362 my $da = $@; # Could be from exception handler
dd19458b 363 if ($use_locking) {
862382c7 364 unless (&CAN_FLOCK) {
8be2b38b 365 logcarp "Storable::lock_store: fcntl/flock emulation broken on $^O";
b29b780f
RM
366 return undef;
367 }
8be2b38b 368 flock(FILE, LOCK_SH) || logcroak "can't get shared lock on $file: $!";
dd19458b
JH
369 # Unlocking will happen when FILE is closed
370 }
7a6a85bf
RG
371 eval { $self = pretrieve(*FILE) }; # Call C routine
372 close(FILE);
373 logcroak $@ if $@ =~ s/\.?\n$/,/;
374 $@ = $da;
375 return $self;
376}
377
378#
9e21b3d0 379# fd_retrieve
7a6a85bf
RG
380#
381# Same as retrieve, but perform from an already opened file descriptor instead.
382#
9e21b3d0 383sub fd_retrieve {
7a6a85bf
RG
384 my ($file) = @_;
385 my $fd = fileno($file);
386 logcroak "not a valid file descriptor" unless defined $fd;
387 my $self;
388 my $da = $@; # Could be from exception handler
389 eval { $self = pretrieve($file) }; # Call C routine
390 logcroak $@ if $@ =~ s/\.?\n$/,/;
391 $@ = $da;
392 return $self;
393}
394
395#
396# thaw
397#
398# Recreate objects in memory from an existing frozen image created
399# by freeze. If the frozen image passed is undef, return undef.
400#
401sub thaw {
402 my ($frozen) = @_;
403 return undef unless defined $frozen;
404 my $self;
405 my $da = $@; # Could be from exception handler
406 eval { $self = mretrieve($frozen) }; # Call C routine
407 logcroak $@ if $@ =~ s/\.?\n$/,/;
408 $@ = $da;
409 return $self;
410}
411
412=head1 NAME
413
414Storable - persistency for perl data structures
415
416=head1 SYNOPSIS
417
418 use Storable;
419 store \%table, 'file';
420 $hashref = retrieve('file');
421
422 use Storable qw(nstore store_fd nstore_fd freeze thaw dclone);
423
424 # Network order
425 nstore \%table, 'file';
426 $hashref = retrieve('file'); # There is NO nretrieve()
427
428 # Storing to and retrieving from an already opened file
429 store_fd \@array, \*STDOUT;
430 nstore_fd \%table, \*STDOUT;
9e21b3d0
JH
431 $aryref = fd_retrieve(\*SOCKET);
432 $hashref = fd_retrieve(\*SOCKET);
7a6a85bf
RG
433
434 # Serializing to memory
435 $serialized = freeze \%table;
436 %table_clone = %{ thaw($serialized) };
437
438 # Deep (recursive) cloning
439 $cloneref = dclone($ref);
440
dd19458b
JH
441 # Advisory locking
442 use Storable qw(lock_store lock_nstore lock_retrieve)
443 lock_store \%table, 'file';
444 lock_nstore \%table, 'file';
445 $hashref = lock_retrieve('file');
446
7a6a85bf
RG
447=head1 DESCRIPTION
448
c261f00e 449The Storable package brings persistence to your perl data structures
7a6a85bf 450containing SCALAR, ARRAY, HASH or REF objects, i.e. anything that can be
c261f00e 451conveniently stored to disk and retrieved at a later time.
7a6a85bf
RG
452
453It can be used in the regular procedural way by calling C<store> with
454a reference to the object to be stored, along with the file name where
455the image should be written.
456The routine returns C<undef> for I/O problems or other internal error,
457a true value otherwise. Serious errors are propagated as a C<die> exception.
458
459To retrieve data stored to disk, use C<retrieve> with a file name,
460and the objects stored into that file are recreated into memory for you,
461a I<reference> to the root object being returned. In case an I/O error
462occurs while reading, C<undef> is returned instead. Other serious
463errors are propagated via C<die>.
464
465Since storage is performed recursively, you might want to stuff references
466to objects that share a lot of common data into a single array or hash
467table, and then store that object. That way, when you retrieve back the
468whole thing, the objects will continue to share what they originally shared.
469
470At the cost of a slight header overhead, you may store to an already
471opened file descriptor using the C<store_fd> routine, and retrieve
9e21b3d0 472from a file via C<fd_retrieve>. Those names aren't imported by default,
c261f00e 473so you will have to do that explicitly if you need those routines.
7a6a85bf
RG
474The file descriptor you supply must be already opened, for read
475if you're going to retrieve and for write if you wish to store.
476
477 store_fd(\%table, *STDOUT) || die "can't store to stdout\n";
9e21b3d0 478 $hashref = fd_retrieve(*STDIN);
7a6a85bf
RG
479
480You can also store data in network order to allow easy sharing across
481multiple platforms, or when storing on a socket known to be remotely
482connected. The routines to call have an initial C<n> prefix for I<network>,
483as in C<nstore> and C<nstore_fd>. At retrieval time, your data will be
484correctly restored so you don't have to know whether you're restoring
dd19458b
JH
485from native or network ordered data. Double values are stored stringified
486to ensure portability as well, at the slight risk of loosing some precision
487in the last decimals.
7a6a85bf 488
9e21b3d0 489When using C<fd_retrieve>, objects are retrieved in sequence, one
7a6a85bf
RG
490object (i.e. one recursive tree) per associated C<store_fd>.
491
492If you're more from the object-oriented camp, you can inherit from
493Storable and directly store your objects by invoking C<store> as
494a method. The fact that the root of the to-be-stored tree is a
495blessed reference (i.e. an object) is special-cased so that the
496retrieve does not provide a reference to that object but rather the
497blessed object reference itself. (Otherwise, you'd get a reference
498to that blessed object).
499
500=head1 MEMORY STORE
501
502The Storable engine can also store data into a Perl scalar instead, to
503later retrieve them. This is mainly used to freeze a complex structure in
504some safe compact memory place (where it can possibly be sent to another
505process via some IPC, since freezing the structure also serializes it in
506effect). Later on, and maybe somewhere else, you can thaw the Perl scalar
507out and recreate the original complex structure in memory.
508
509Surprisingly, the routines to be called are named C<freeze> and C<thaw>.
510If you wish to send out the frozen scalar to another machine, use
511C<nfreeze> instead to get a portable image.
512
513Note that freezing an object structure and immediately thawing it
514actually achieves a deep cloning of that structure:
515
516 dclone(.) = thaw(freeze(.))
517
518Storable provides you with a C<dclone> interface which does not create
519that intermediary scalar but instead freezes the structure in some
c261f00e 520internal memory space and then immediately thaws it out.
7a6a85bf 521
dd19458b
JH
522=head1 ADVISORY LOCKING
523
524The C<lock_store> and C<lock_nstore> routine are equivalent to C<store>
525and C<nstore>, only they get an exclusive lock on the file before
526writing. Likewise, C<lock_retrieve> performs as C<retrieve>, but also
527gets a shared lock on the file before reading.
528
529Like with any advisory locking scheme, the protection only works if
530you systematically use C<lock_store> and C<lock_retrieve>. If one
531side of your application uses C<store> whilst the other uses C<lock_retrieve>,
532you will get no protection at all.
533
534The internal advisory locking is implemented using Perl's flock() routine.
535If your system does not support any form of flock(), or if you share
536your files across NFS, you might wish to use other forms of locking by
537using modules like LockFile::Simple which lock a file using a filesystem
538entry, instead of locking the file descriptor.
539
7a6a85bf
RG
540=head1 SPEED
541
542The heart of Storable is written in C for decent speed. Extra low-level
4d3295e3
PN
543optimizations have been made when manipulating perl internals, to
544sacrifice encapsulation for the benefit of greater speed.
7a6a85bf
RG
545
546=head1 CANONICAL REPRESENTATION
547
548Normally Storable stores elements of hashes in the order they are
549stored internally by Perl, i.e. pseudo-randomly. If you set
550C<$Storable::canonical> to some C<TRUE> value, Storable will store
551hashes with the elements sorted by their key. This allows you to
552compare data structures by comparing their frozen representations (or
553even the compressed frozen representations), which can be useful for
554creating lookup tables for complicated queries.
555
556Canonical order does not imply network order, those are two orthogonal
557settings.
558
c261f00e
NC
559=head1 FORWARD COMPATIBILITY
560
561This release of Storable can be used on a newer version of Perl to
562serialize data which is not supported by earlier Perls. By default
563Storable will attempt to do the right thing, by C<croak()>ing if it
564encounters data that it cannot deserialize. However, the defaults can be
565changed as follows
566
567=over 4
568
569=item utf8 data
570
571Perl 5.6 added support for Unicode characters with code points > 255,
572and Perl 5.8 has full support for Unicode characters in hash keys.
573Perl internally encodes strings with these characters using utf8, and
574Storable serializes them as utf8. By default, if an older version of
575Perl encounters a utf8 value it cannot represent, it will C<croak()>.
576To change this behaviour so that Storable deserializes utf8 encoded
577values as the string of bytes (effectively dropping the I<is_utf8> flag)
578set C<$Storable::drop_utf8> to some C<TRUE> value. This is a form of
579data loss, because with C<$drop_utf8> true, it becomes impossible to tell
580whether the original data was the Unicode string, or a series of bytes
581that happen to be valid utf8.
582
583=item restricted hashes
584
585Perl 5.8 adds support for restricted hashes, which have keys restricted to
586a given set, and can have values locked to be read only. By default
587when Storable encounters a restricted hash on a perl that doesn't support
588them, it will deserialize it as a normal hash, silently discarding any
589placeholder keys and leaving the keys and all values unlocked. To make
590Storable C<croak()> instead, set C<$Storable::downgrade_restricted> to
591a false value. To restore the default set it back to some C<TRUE> value.
592
593=back
594
595Both these variables have no effect on a newer Perl which supports the
596relevant feature.
597
7a6a85bf
RG
598=head1 ERROR REPORTING
599
600Storable uses the "exception" paradigm, in that it does not try to workaround
601failures: if something bad happens, an exception is generated from the
602caller's perspective (see L<Carp> and C<croak()>). Use eval {} to trap
603those exceptions.
604
605When Storable croaks, it tries to report the error via the C<logcroak()>
606routine from the C<Log::Agent> package, if it is available.
607
212e9bde
JH
608Normal errors are reported by having store() or retrieve() return C<undef>.
609Such errors are usually I/O errors (or truncated stream errors at retrieval).
610
7a6a85bf
RG
611=head1 WIZARDS ONLY
612
613=head2 Hooks
614
615Any class may define hooks that will be called during the serialization
616and deserialization process on objects that are instances of that class.
617Those hooks can redefine the way serialization is performed (and therefore,
c261f00e 618how the symmetrical deserialization should be conducted).
7a6a85bf
RG
619
620Since we said earlier:
621
622 dclone(.) = thaw(freeze(.))
623
624everything we say about hooks should also hold for deep cloning. However,
625hooks get to know whether the operation is a mere serialization, or a cloning.
626
627Therefore, when serializing hooks are involved,
628
629 dclone(.) <> thaw(freeze(.))
630
631Well, you could keep them in sync, but there's no guarantee it will always
632hold on classes somebody else wrote. Besides, there is little to gain in
633doing so: a serializing hook could only keep one attribute of an object,
634which is probably not what should happen during a deep cloning of that
635same object.
636
637Here is the hooking interface:
638
bbc7dcd2 639=over 4
7a6a85bf
RG
640
641=item C<STORABLE_freeze> I<obj>, I<cloning>
642
643The serializing hook, called on the object during serialization. It can be
644inherited, or defined in the class itself, like any other method.
645
646Arguments: I<obj> is the object to serialize, I<cloning> is a flag indicating
647whether we're in a dclone() or a regular serialization via store() or freeze().
648
649Returned value: A LIST C<($serialized, $ref1, $ref2, ...)> where $serialized
650is the serialized form to be used, and the optional $ref1, $ref2, etc... are
651extra references that you wish to let the Storable engine serialize.
652
653At deserialization time, you will be given back the same LIST, but all the
654extra references will be pointing into the deserialized structure.
655
656The B<first time> the hook is hit in a serialization flow, you may have it
657return an empty list. That will signal the Storable engine to further
658discard that hook for this class and to therefore revert to the default
659serialization of the underlying Perl data. The hook will again be normally
660processed in the next serialization.
661
662Unless you know better, serializing hook should always say:
663
664 sub STORABLE_freeze {
665 my ($self, $cloning) = @_;
666 return if $cloning; # Regular default serialization
667 ....
668 }
669
670in order to keep reasonable dclone() semantics.
671
672=item C<STORABLE_thaw> I<obj>, I<cloning>, I<serialized>, ...
673
674The deserializing hook called on the object during deserialization.
675But wait. If we're deserializing, there's no object yet... right?
676
677Wrong: the Storable engine creates an empty one for you. If you know Eiffel,
678you can view C<STORABLE_thaw> as an alternate creation routine.
679
680This means the hook can be inherited like any other method, and that
681I<obj> is your blessed reference for this particular instance.
682
683The other arguments should look familiar if you know C<STORABLE_freeze>:
684I<cloning> is true when we're part of a deep clone operation, I<serialized>
685is the serialized string you returned to the engine in C<STORABLE_freeze>,
686and there may be an optional list of references, in the same order you gave
687them at serialization time, pointing to the deserialized objects (which
688have been processed courtesy of the Storable engine).
689
212e9bde
JH
690When the Storable engine does not find any C<STORABLE_thaw> hook routine,
691it tries to load the class by requiring the package dynamically (using
692the blessed package name), and then re-attempts the lookup. If at that
693time the hook cannot be located, the engine croaks. Note that this mechanism
c261f00e 694will fail if you define several classes in the same file, but L<perlmod>
212e9bde
JH
695warned you.
696
7a6a85bf
RG
697It is up to you to use these information to populate I<obj> the way you want.
698
699Returned value: none.
700
701=back
702
703=head2 Predicates
704
c261f00e 705Predicates are not exportable. They must be called by explicitly prefixing
7a6a85bf
RG
706them with the Storable package name.
707
bbc7dcd2 708=over 4
7a6a85bf
RG
709
710=item C<Storable::last_op_in_netorder>
711
712The C<Storable::last_op_in_netorder()> predicate will tell you whether
713network order was used in the last store or retrieve operation. If you
714don't know how to use this, just forget about it.
715
716=item C<Storable::is_storing>
717
718Returns true if within a store operation (via STORABLE_freeze hook).
719
720=item C<Storable::is_retrieving>
721
722Returns true if within a retrieve operation, (via STORABLE_thaw hook).
723
724=back
725
726=head2 Recursion
727
728With hooks comes the ability to recurse back to the Storable engine. Indeed,
729hooks are regular Perl code, and Storable is convenient when it comes to
730serialize and deserialize things, so why not use it to handle the
731serialization string?
732
733There are a few things you need to know however:
734
bbc7dcd2 735=over 4
7a6a85bf
RG
736
737=item *
738
739You can create endless loops if the things you serialize via freeze()
740(for instance) point back to the object we're trying to serialize in the hook.
741
742=item *
743
744Shared references among objects will not stay shared: if we're serializing
745the list of object [A, C] where both object A and C refer to the SAME object
746B, and if there is a serializing hook in A that says freeze(B), then when
747deserializing, we'll get [A', C'] where A' refers to B', but C' refers to D,
748a deep clone of B'. The topology was not preserved.
749
750=back
751
752That's why C<STORABLE_freeze> lets you provide a list of references
753to serialize. The engine guarantees that those will be serialized in the
754same context as the other objects, and therefore that shared objects will
755stay shared.
756
757In the above [A, C] example, the C<STORABLE_freeze> hook could return:
758
759 ("something", $self->{B})
760
761and the B part would be serialized by the engine. In C<STORABLE_thaw>, you
762would get back the reference to the B' object, deserialized for you.
763
764Therefore, recursion should normally be avoided, but is nonetheless supported.
765
766=head2 Deep Cloning
767
768There is a new Clone module available on CPAN which implements deep cloning
769natively, i.e. without freezing to memory and thawing the result. It is
770aimed to replace Storable's dclone() some day. However, it does not currently
771support Storable hooks to redefine the way deep cloning is performed.
772
0a0da639
JH
773=head1 Storable magic
774
775Yes, there's a lot of that :-) But more precisely, in UNIX systems
776there's a utility called C<file>, which recognizes data files based on
777their contents (usually their first few bytes). For this to work,
8b793558 778a certain file called F<magic> needs to taught about the I<signature>
0a0da639
JH
779of the data. Where that configuration file lives depends on the UNIX
780flavour, often it's something like F</usr/share/misc/magic> or
8b793558
JH
781F</etc/magic>. Your system administrator needs to do the updating of
782the F<magic> file. The necessary signature information is output to
c261f00e 783STDOUT by invoking Storable::show_file_magic(). Note that the open
8b793558
JH
784source implementation of the C<file> utility 3.38 (or later)
785is expected to contain the support for recognising Storable files,
786in addition to other kinds of Perl files.
0a0da639 787
7a6a85bf
RG
788=head1 EXAMPLES
789
790Here are some code samples showing a possible usage of Storable:
791
792 use Storable qw(store retrieve freeze thaw dclone);
793
794 %color = ('Blue' => 0.1, 'Red' => 0.8, 'Black' => 0, 'White' => 1);
795
796 store(\%color, '/tmp/colors') or die "Can't store %a in /tmp/colors!\n";
797
798 $colref = retrieve('/tmp/colors');
799 die "Unable to retrieve from /tmp/colors!\n" unless defined $colref;
800 printf "Blue is still %lf\n", $colref->{'Blue'};
801
802 $colref2 = dclone(\%color);
803
804 $str = freeze(\%color);
805 printf "Serialization of %%color is %d bytes long.\n", length($str);
806 $colref3 = thaw($str);
807
808which prints (on my machine):
809
810 Blue is still 0.100000
811 Serialization of %color is 102 bytes long.
812
813=head1 WARNING
814
815If you're using references as keys within your hash tables, you're bound
c261f00e 816to disappointment when retrieving your data. Indeed, Perl stringifies
7a6a85bf
RG
817references used as hash table keys. If you later wish to access the
818items via another reference stringification (i.e. using the same
819reference that was used for the key originally to record the value into
820the hash table), it will work because both references stringify to the
821same string.
822
823It won't work across a C<store> and C<retrieve> operations however, because
824the addresses in the retrieved objects, which are part of the stringified
825references, will probably differ from the original addresses. The
826topology of your structure is preserved, but not hidden semantics
827like those.
828
829On platforms where it matters, be sure to call C<binmode()> on the
830descriptors that you pass to Storable functions.
831
832Storing data canonically that contains large hashes can be
833significantly slower than storing the same data normally, as
c261f00e 834temporary arrays to hold the keys for each hash have to be allocated,
7a6a85bf
RG
835populated, sorted and freed. Some tests have shown a halving of the
836speed of storing -- the exact penalty will depend on the complexity of
837your data. There is no slowdown on retrieval.
838
839=head1 BUGS
840
841You can't store GLOB, CODE, FORMLINE, etc... If you can define
842semantics for those operations, feel free to enhance Storable so that
843it can deal with them.
844
845The store functions will C<croak> if they run into such references
846unless you set C<$Storable::forgive_me> to some C<TRUE> value. In that
847case, the fatal message is turned in a warning and some
848meaningless string is stored instead.
849
850Setting C<$Storable::canonical> may not yield frozen strings that
851compare equal due to possible stringification of numbers. When the
852string version of a scalar exists, it is the form stored, therefore
853if you happen to use your numbers as strings between two freezing
854operations on the same data structures, you will get different
855results.
856
dd19458b
JH
857When storing doubles in network order, their value is stored as text.
858However, you should also not expect non-numeric floating-point values
859such as infinity and "not a number" to pass successfully through a
860nstore()/retrieve() pair.
861
862As Storable neither knows nor cares about character sets (although it
863does know that characters may be more than eight bits wide), any difference
864in the interpretation of character codes between a host and a target
865system is your problem. In particular, if host and target use different
866code points to represent the characters used in the text representation
867of floating-point numbers, you will not be able be able to exchange
868floating-point data, even with nstore().
869
c261f00e
NC
870C<Storable::drop_utf8> is a blunt tool. There is no facility either to
871return B<all> strings as utf8 sequences, or to attempt to convert utf8
872data back to 8 bit and C<croak()> if the conversion fails.
873
874Future compatibility does not yet extend to having the option of loading
875serialized data with higher than current minor version numbers. This
876ought to be fixed pronto.
877
7a6a85bf
RG
878=head1 CREDITS
879
880Thank you to (in chronological order):
881
882 Jarkko Hietaniemi <jhi@iki.fi>
883 Ulrich Pfeifer <pfeifer@charly.informatik.uni-dortmund.de>
884 Benjamin A. Holzman <bah@ecnvantage.com>
885 Andrew Ford <A.Ford@ford-mason.co.uk>
886 Gisle Aas <gisle@aas.no>
887 Jeff Gresham <gresham_jeffrey@jpmorgan.com>
888 Murray Nesbitt <murray@activestate.com>
889 Marc Lehmann <pcg@opengroup.org>
9e21b3d0
JH
890 Justin Banks <justinb@wamnet.com>
891 Jarkko Hietaniemi <jhi@iki.fi> (AGAIN, as perl 5.7.0 Pumpkin!)
dd19458b
JH
892 Salvador Ortiz Garcia <sog@msg.com.mx>
893 Dominic Dunlop <domo@computer.org>
894 Erik Haugan <erik@solbors.no>
7a6a85bf
RG
895
896for their bug reports, suggestions and contributions.
897
898Benjamin Holzman contributed the tied variable support, Andrew Ford
899contributed the canonical order for hashes, and Gisle Aas fixed
900a few misunderstandings of mine regarding the Perl internals,
901and optimized the emission of "tags" in the output streams by
902simply counting the objects instead of tagging them (leading to
903a binary incompatibility for the Storable image starting at version
9040.6--older images are of course still properly understood).
905Murray Nesbitt made Storable thread-safe. Marc Lehmann added overloading
906and reference to tied items support.
907
908=head1 TRANSLATIONS
909
910There is a Japanese translation of this man page available at
911http://member.nifty.ne.jp/hippo2000/perltips/storable.htm ,
912courtesy of Kawai, Takanori <kawai@nippon-rad.co.jp>.
913
914=head1 AUTHOR
915
916Raphael Manfredi F<E<lt>Raphael_Manfredi@pobox.comE<gt>>
917
918=head1 SEE ALSO
919
c261f00e 920L<Clone>.
7a6a85bf
RG
921
922=cut
923