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