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