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