Commit | Line | Data |
596596d5 |
1 | ;# $Id: Storable.pm,v 1.0.1.13 2001/12/01 13:34:49 ram Exp $ |
7a6a85bf |
2 | ;# |
3 | ;# Copyright (c) 1995-2000, Raphael Manfredi |
4 | ;# |
9e21b3d0 |
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 |
7 | ;# |
8 | ;# $Log: Storable.pm,v $ |
596596d5 |
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 |
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 |
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 |
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 |
26 | ;# Revision 1.0.1.8 2001/02/17 12:24:37 ram |
27 | ;# patch8: fixed incorrect error message |
28 | ;# |
862382c7 |
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 |
32 | ;# Revision 1.0.1.6 2000/11/05 17:20:25 ram |
33 | ;# patch6: increased version number |
34 | ;# |
212e9bde |
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 |
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 |
53 | ;# Revision 1.0 2000/09/01 19:40:41 ram |
54 | ;# Baseline for first official release. |
7a6a85bf |
55 | ;# |
56 | |
57 | require DynaLoader; |
58 | require Exporter; |
59 | package 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 |
64 | freeze nfreeze thaw |
65 | dclone |
9e21b3d0 |
66 | retrieve_fd |
dd19458b |
67 | lock_store lock_nstore lock_retrieve |
7a6a85bf |
68 | ); |
69 | |
70 | use AutoLoader; |
71 | use vars qw($forgive_me $VERSION); |
72 | |
0a0da639 |
73 | $VERSION = '1.015'; |
7a6a85bf |
74 | *AUTOLOAD = \&AutoLoader::AUTOLOAD; # Grrr... |
75 | |
76 | # |
77 | # Use of Log::Agent is optional |
78 | # |
79 | |
80 | eval "use Log::Agent"; |
81 | |
82 | unless (defined @Log::Agent::EXPORT) { |
83 | eval q{ |
84 | sub logcroak { |
85 | require Carp; |
86 | Carp::croak(@_); |
87 | } |
b29b780f |
88 | sub logcarp { |
89 | require Carp; |
90 | Carp::carp(@_); |
91 | } |
7a6a85bf |
92 | }; |
93 | } |
94 | |
dd19458b |
95 | # |
96 | # They might miss :flock in Fcntl |
97 | # |
98 | |
99 | BEGIN { |
596596d5 |
100 | if (eval { require Fcntl; 1 } && exists $Fcntl::EXPORT_TAGS{'flock'}) { |
dd19458b |
101 | Fcntl->import(':flock'); |
102 | } else { |
103 | eval q{ |
104 | sub LOCK_SH () {1} |
105 | sub LOCK_EX () {2} |
106 | }; |
107 | } |
108 | } |
109 | |
7a6a85bf |
110 | sub logcroak; |
b29b780f |
111 | sub logcarp; |
7a6a85bf |
112 | |
9e21b3d0 |
113 | sub retrieve_fd { &fd_retrieve } # Backward compatibility |
cb3d9de5 |
114 | |
862382c7 |
115 | # |
116 | # Determine whether locking is possible, but only when needed. |
117 | # |
118 | |
119 | my $CAN_FLOCK; |
120 | |
121 | sub 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 |
130 | sub 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 | # |
139 | 0 string perl-store perl Storable(v0.6) data |
140 | >1 byte &01 (network-ordered) |
141 | 0 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) |
152 | EOM |
153 | } |
154 | |
7a6a85bf |
155 | bootstrap Storable; |
156 | 1; |
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 | # |
167 | sub store { |
dd19458b |
168 | return _store(\&pstore, @_, 0); |
7a6a85bf |
169 | } |
170 | |
171 | # |
172 | # nstore |
173 | # |
174 | # Same as store, but in network order. |
175 | # |
176 | sub nstore { |
dd19458b |
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 | # |
185 | sub 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 | # |
194 | sub lock_nstore { |
195 | return _store(\&net_pstore, @_, 1); |
7a6a85bf |
196 | } |
197 | |
198 | # Internal store to file routine |
199 | sub _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 |
209 | logcarp "Storable::lock_store: fcntl/flock emulation broken on $^O"; |
210 | return undef; |
f567092b |
211 | } |
dd19458b |
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 |
216 | } else { |
217 | open(FILE, ">$file") || logcroak "can't create $file: $!"; |
dd19458b |
218 | } |
6e0ac6f5 |
219 | binmode FILE; # Archaic systems... |
7a6a85bf |
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 | # |
237 | sub store_fd { |
238 | return _store_fd(\&pstore, @_); |
239 | } |
240 | |
241 | # |
242 | # nstore_fd |
243 | # |
244 | # Same as store_fd, but in network order. |
245 | # |
246 | sub nstore_fd { |
247 | my ($self, $file) = @_; |
248 | return _store_fd(\&net_pstore, @_); |
249 | } |
250 | |
251 | # Internal store routine on opened file descriptor |
252 | sub _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 |
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 | # |
276 | sub freeze { |
277 | _freeze(\&mstore, @_); |
278 | } |
279 | |
280 | # |
281 | # nfreeze |
282 | # |
283 | # Same as freeze but in network order. |
284 | # |
285 | sub nfreeze { |
286 | _freeze(\&net_mstore, @_); |
287 | } |
288 | |
289 | # Internal freeze routine |
290 | sub _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 | # |
310 | sub retrieve { |
dd19458b |
311 | _retrieve($_[0], 0); |
312 | } |
313 | |
314 | # |
315 | # lock_retrieve |
316 | # |
317 | # Same as retrieve, but with advisory locking. |
318 | # |
319 | sub lock_retrieve { |
320 | _retrieve($_[0], 1); |
321 | } |
322 | |
323 | # Internal retrieve routine |
324 | sub _retrieve { |
325 | my ($file, $use_locking) = @_; |
7a6a85bf |
326 | local *FILE; |
dd19458b |
327 | open(FILE, $file) || logcroak "can't open $file: $!"; |
7a6a85bf |
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 |
334 | return undef; |
335 | } |
8be2b38b |
336 | flock(FILE, LOCK_SH) || logcroak "can't get shared lock on $file: $!"; |
dd19458b |
337 | # Unlocking will happen when FILE is closed |
338 | } |
7a6a85bf |
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 |
348 | # |
349 | # Same as retrieve, but perform from an already opened file descriptor instead. |
350 | # |
9e21b3d0 |
351 | sub fd_retrieve { |
7a6a85bf |
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 | # |
369 | sub 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 | |
382 | Storable - 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 |
399 | $aryref = fd_retrieve(\*SOCKET); |
400 | $hashref = fd_retrieve(\*SOCKET); |
7a6a85bf |
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 |
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 |
415 | =head1 DESCRIPTION |
416 | |
417 | The Storable package brings persistency to your perl data structures |
418 | containing SCALAR, ARRAY, HASH or REF objects, i.e. anything that can be |
419 | convenientely stored to disk and retrieved at a later time. |
420 | |
421 | It can be used in the regular procedural way by calling C<store> with |
422 | a reference to the object to be stored, along with the file name where |
423 | the image should be written. |
424 | The routine returns C<undef> for I/O problems or other internal error, |
425 | a true value otherwise. Serious errors are propagated as a C<die> exception. |
426 | |
427 | To retrieve data stored to disk, use C<retrieve> with a file name, |
428 | and the objects stored into that file are recreated into memory for you, |
429 | a I<reference> to the root object being returned. In case an I/O error |
430 | occurs while reading, C<undef> is returned instead. Other serious |
431 | errors are propagated via C<die>. |
432 | |
433 | Since storage is performed recursively, you might want to stuff references |
434 | to objects that share a lot of common data into a single array or hash |
435 | table, and then store that object. That way, when you retrieve back the |
436 | whole thing, the objects will continue to share what they originally shared. |
437 | |
438 | At the cost of a slight header overhead, you may store to an already |
439 | opened file descriptor using the C<store_fd> routine, and retrieve |
9e21b3d0 |
440 | from a file via C<fd_retrieve>. Those names aren't imported by default, |
7a6a85bf |
441 | so you will have to do that explicitely if you need those routines. |
442 | The file descriptor you supply must be already opened, for read |
443 | if 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 |
447 | |
448 | You can also store data in network order to allow easy sharing across |
449 | multiple platforms, or when storing on a socket known to be remotely |
450 | connected. The routines to call have an initial C<n> prefix for I<network>, |
451 | as in C<nstore> and C<nstore_fd>. At retrieval time, your data will be |
452 | correctly restored so you don't have to know whether you're restoring |
dd19458b |
453 | from native or network ordered data. Double values are stored stringified |
454 | to ensure portability as well, at the slight risk of loosing some precision |
455 | in the last decimals. |
7a6a85bf |
456 | |
9e21b3d0 |
457 | When using C<fd_retrieve>, objects are retrieved in sequence, one |
7a6a85bf |
458 | object (i.e. one recursive tree) per associated C<store_fd>. |
459 | |
460 | If you're more from the object-oriented camp, you can inherit from |
461 | Storable and directly store your objects by invoking C<store> as |
462 | a method. The fact that the root of the to-be-stored tree is a |
463 | blessed reference (i.e. an object) is special-cased so that the |
464 | retrieve does not provide a reference to that object but rather the |
465 | blessed object reference itself. (Otherwise, you'd get a reference |
466 | to that blessed object). |
467 | |
468 | =head1 MEMORY STORE |
469 | |
470 | The Storable engine can also store data into a Perl scalar instead, to |
471 | later retrieve them. This is mainly used to freeze a complex structure in |
472 | some safe compact memory place (where it can possibly be sent to another |
473 | process via some IPC, since freezing the structure also serializes it in |
474 | effect). Later on, and maybe somewhere else, you can thaw the Perl scalar |
475 | out and recreate the original complex structure in memory. |
476 | |
477 | Surprisingly, the routines to be called are named C<freeze> and C<thaw>. |
478 | If you wish to send out the frozen scalar to another machine, use |
479 | C<nfreeze> instead to get a portable image. |
480 | |
481 | Note that freezing an object structure and immediately thawing it |
482 | actually achieves a deep cloning of that structure: |
483 | |
484 | dclone(.) = thaw(freeze(.)) |
485 | |
486 | Storable provides you with a C<dclone> interface which does not create |
487 | that intermediary scalar but instead freezes the structure in some |
488 | internal memory space and then immediatly thaws it out. |
489 | |
dd19458b |
490 | =head1 ADVISORY LOCKING |
491 | |
492 | The C<lock_store> and C<lock_nstore> routine are equivalent to C<store> |
493 | and C<nstore>, only they get an exclusive lock on the file before |
494 | writing. Likewise, C<lock_retrieve> performs as C<retrieve>, but also |
495 | gets a shared lock on the file before reading. |
496 | |
497 | Like with any advisory locking scheme, the protection only works if |
498 | you systematically use C<lock_store> and C<lock_retrieve>. If one |
499 | side of your application uses C<store> whilst the other uses C<lock_retrieve>, |
500 | you will get no protection at all. |
501 | |
502 | The internal advisory locking is implemented using Perl's flock() routine. |
503 | If your system does not support any form of flock(), or if you share |
504 | your files across NFS, you might wish to use other forms of locking by |
505 | using modules like LockFile::Simple which lock a file using a filesystem |
506 | entry, instead of locking the file descriptor. |
507 | |
7a6a85bf |
508 | =head1 SPEED |
509 | |
510 | The heart of Storable is written in C for decent speed. Extra low-level |
511 | optimization have been made when manipulating perl internals, to |
512 | sacrifice encapsulation for the benefit of a greater speed. |
513 | |
514 | =head1 CANONICAL REPRESENTATION |
515 | |
516 | Normally Storable stores elements of hashes in the order they are |
517 | stored internally by Perl, i.e. pseudo-randomly. If you set |
518 | C<$Storable::canonical> to some C<TRUE> value, Storable will store |
519 | hashes with the elements sorted by their key. This allows you to |
520 | compare data structures by comparing their frozen representations (or |
521 | even the compressed frozen representations), which can be useful for |
522 | creating lookup tables for complicated queries. |
523 | |
524 | Canonical order does not imply network order, those are two orthogonal |
525 | settings. |
526 | |
527 | =head1 ERROR REPORTING |
528 | |
529 | Storable uses the "exception" paradigm, in that it does not try to workaround |
530 | failures: if something bad happens, an exception is generated from the |
531 | caller's perspective (see L<Carp> and C<croak()>). Use eval {} to trap |
532 | those exceptions. |
533 | |
534 | When Storable croaks, it tries to report the error via the C<logcroak()> |
535 | routine from the C<Log::Agent> package, if it is available. |
536 | |
212e9bde |
537 | Normal errors are reported by having store() or retrieve() return C<undef>. |
538 | Such errors are usually I/O errors (or truncated stream errors at retrieval). |
539 | |
7a6a85bf |
540 | =head1 WIZARDS ONLY |
541 | |
542 | =head2 Hooks |
543 | |
544 | Any class may define hooks that will be called during the serialization |
545 | and deserialization process on objects that are instances of that class. |
546 | Those hooks can redefine the way serialization is performed (and therefore, |
547 | how the symetrical deserialization should be conducted). |
548 | |
549 | Since we said earlier: |
550 | |
551 | dclone(.) = thaw(freeze(.)) |
552 | |
553 | everything we say about hooks should also hold for deep cloning. However, |
554 | hooks get to know whether the operation is a mere serialization, or a cloning. |
555 | |
556 | Therefore, when serializing hooks are involved, |
557 | |
558 | dclone(.) <> thaw(freeze(.)) |
559 | |
560 | Well, you could keep them in sync, but there's no guarantee it will always |
561 | hold on classes somebody else wrote. Besides, there is little to gain in |
562 | doing so: a serializing hook could only keep one attribute of an object, |
563 | which is probably not what should happen during a deep cloning of that |
564 | same object. |
565 | |
566 | Here is the hooking interface: |
567 | |
bbc7dcd2 |
568 | =over 4 |
7a6a85bf |
569 | |
570 | =item C<STORABLE_freeze> I<obj>, I<cloning> |
571 | |
572 | The serializing hook, called on the object during serialization. It can be |
573 | inherited, or defined in the class itself, like any other method. |
574 | |
575 | Arguments: I<obj> is the object to serialize, I<cloning> is a flag indicating |
576 | whether we're in a dclone() or a regular serialization via store() or freeze(). |
577 | |
578 | Returned value: A LIST C<($serialized, $ref1, $ref2, ...)> where $serialized |
579 | is the serialized form to be used, and the optional $ref1, $ref2, etc... are |
580 | extra references that you wish to let the Storable engine serialize. |
581 | |
582 | At deserialization time, you will be given back the same LIST, but all the |
583 | extra references will be pointing into the deserialized structure. |
584 | |
585 | The B<first time> the hook is hit in a serialization flow, you may have it |
586 | return an empty list. That will signal the Storable engine to further |
587 | discard that hook for this class and to therefore revert to the default |
588 | serialization of the underlying Perl data. The hook will again be normally |
589 | processed in the next serialization. |
590 | |
591 | Unless 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 | |
599 | in order to keep reasonable dclone() semantics. |
600 | |
601 | =item C<STORABLE_thaw> I<obj>, I<cloning>, I<serialized>, ... |
602 | |
603 | The deserializing hook called on the object during deserialization. |
604 | But wait. If we're deserializing, there's no object yet... right? |
605 | |
606 | Wrong: the Storable engine creates an empty one for you. If you know Eiffel, |
607 | you can view C<STORABLE_thaw> as an alternate creation routine. |
608 | |
609 | This means the hook can be inherited like any other method, and that |
610 | I<obj> is your blessed reference for this particular instance. |
611 | |
612 | The other arguments should look familiar if you know C<STORABLE_freeze>: |
613 | I<cloning> is true when we're part of a deep clone operation, I<serialized> |
614 | is the serialized string you returned to the engine in C<STORABLE_freeze>, |
615 | and there may be an optional list of references, in the same order you gave |
616 | them at serialization time, pointing to the deserialized objects (which |
617 | have been processed courtesy of the Storable engine). |
618 | |
212e9bde |
619 | When the Storable engine does not find any C<STORABLE_thaw> hook routine, |
620 | it tries to load the class by requiring the package dynamically (using |
621 | the blessed package name), and then re-attempts the lookup. If at that |
622 | time the hook cannot be located, the engine croaks. Note that this mechanism |
623 | will fail if you define several classes in the same file, but perlmod(1) |
624 | warned you. |
625 | |
7a6a85bf |
626 | It is up to you to use these information to populate I<obj> the way you want. |
627 | |
628 | Returned value: none. |
629 | |
630 | =back |
631 | |
632 | =head2 Predicates |
633 | |
634 | Predicates are not exportable. They must be called by explicitely prefixing |
635 | them with the Storable package name. |
636 | |
bbc7dcd2 |
637 | =over 4 |
7a6a85bf |
638 | |
639 | =item C<Storable::last_op_in_netorder> |
640 | |
641 | The C<Storable::last_op_in_netorder()> predicate will tell you whether |
642 | network order was used in the last store or retrieve operation. If you |
643 | don't know how to use this, just forget about it. |
644 | |
645 | =item C<Storable::is_storing> |
646 | |
647 | Returns true if within a store operation (via STORABLE_freeze hook). |
648 | |
649 | =item C<Storable::is_retrieving> |
650 | |
651 | Returns true if within a retrieve operation, (via STORABLE_thaw hook). |
652 | |
653 | =back |
654 | |
655 | =head2 Recursion |
656 | |
657 | With hooks comes the ability to recurse back to the Storable engine. Indeed, |
658 | hooks are regular Perl code, and Storable is convenient when it comes to |
659 | serialize and deserialize things, so why not use it to handle the |
660 | serialization string? |
661 | |
662 | There are a few things you need to know however: |
663 | |
bbc7dcd2 |
664 | =over 4 |
7a6a85bf |
665 | |
666 | =item * |
667 | |
668 | You 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 | |
673 | Shared references among objects will not stay shared: if we're serializing |
674 | the list of object [A, C] where both object A and C refer to the SAME object |
675 | B, and if there is a serializing hook in A that says freeze(B), then when |
676 | deserializing, we'll get [A', C'] where A' refers to B', but C' refers to D, |
677 | a deep clone of B'. The topology was not preserved. |
678 | |
679 | =back |
680 | |
681 | That's why C<STORABLE_freeze> lets you provide a list of references |
682 | to serialize. The engine guarantees that those will be serialized in the |
683 | same context as the other objects, and therefore that shared objects will |
684 | stay shared. |
685 | |
686 | In the above [A, C] example, the C<STORABLE_freeze> hook could return: |
687 | |
688 | ("something", $self->{B}) |
689 | |
690 | and the B part would be serialized by the engine. In C<STORABLE_thaw>, you |
691 | would get back the reference to the B' object, deserialized for you. |
692 | |
693 | Therefore, recursion should normally be avoided, but is nonetheless supported. |
694 | |
695 | =head2 Deep Cloning |
696 | |
697 | There is a new Clone module available on CPAN which implements deep cloning |
698 | natively, i.e. without freezing to memory and thawing the result. It is |
699 | aimed to replace Storable's dclone() some day. However, it does not currently |
700 | support Storable hooks to redefine the way deep cloning is performed. |
701 | |
0a0da639 |
702 | =head1 Storable magic |
703 | |
704 | Yes, there's a lot of that :-) But more precisely, in UNIX systems |
705 | there's a utility called C<file>, which recognizes data files based on |
706 | their contents (usually their first few bytes). For this to work, |
707 | a certain file called "magic" needs to taught about the "signature" |
708 | of the data. Where that configuration file lives depends on the UNIX |
709 | flavour, often it's something like F</usr/share/misc/magic> or |
710 | F</etc/magic>. Your system administrator needs to do the updating. |
711 | The necessary signature information is output to stdout by |
712 | invoking Storable::show_file_magic(). |
713 | |
7a6a85bf |
714 | =head1 EXAMPLES |
715 | |
716 | Here 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 | |
734 | which prints (on my machine): |
735 | |
736 | Blue is still 0.100000 |
737 | Serialization of %color is 102 bytes long. |
738 | |
739 | =head1 WARNING |
740 | |
741 | If you're using references as keys within your hash tables, you're bound |
742 | to disapointment when retrieving your data. Indeed, Perl stringifies |
743 | references used as hash table keys. If you later wish to access the |
744 | items via another reference stringification (i.e. using the same |
745 | reference that was used for the key originally to record the value into |
746 | the hash table), it will work because both references stringify to the |
747 | same string. |
748 | |
749 | It won't work across a C<store> and C<retrieve> operations however, because |
750 | the addresses in the retrieved objects, which are part of the stringified |
751 | references, will probably differ from the original addresses. The |
752 | topology of your structure is preserved, but not hidden semantics |
753 | like those. |
754 | |
755 | On platforms where it matters, be sure to call C<binmode()> on the |
756 | descriptors that you pass to Storable functions. |
757 | |
758 | Storing data canonically that contains large hashes can be |
759 | significantly slower than storing the same data normally, as |
760 | temprorary arrays to hold the keys for each hash have to be allocated, |
761 | populated, sorted and freed. Some tests have shown a halving of the |
762 | speed of storing -- the exact penalty will depend on the complexity of |
763 | your data. There is no slowdown on retrieval. |
764 | |
765 | =head1 BUGS |
766 | |
767 | You can't store GLOB, CODE, FORMLINE, etc... If you can define |
768 | semantics for those operations, feel free to enhance Storable so that |
769 | it can deal with them. |
770 | |
771 | The store functions will C<croak> if they run into such references |
772 | unless you set C<$Storable::forgive_me> to some C<TRUE> value. In that |
773 | case, the fatal message is turned in a warning and some |
774 | meaningless string is stored instead. |
775 | |
776 | Setting C<$Storable::canonical> may not yield frozen strings that |
777 | compare equal due to possible stringification of numbers. When the |
778 | string version of a scalar exists, it is the form stored, therefore |
779 | if you happen to use your numbers as strings between two freezing |
780 | operations on the same data structures, you will get different |
781 | results. |
782 | |
dd19458b |
783 | When storing doubles in network order, their value is stored as text. |
784 | However, you should also not expect non-numeric floating-point values |
785 | such as infinity and "not a number" to pass successfully through a |
786 | nstore()/retrieve() pair. |
787 | |
788 | As Storable neither knows nor cares about character sets (although it |
789 | does know that characters may be more than eight bits wide), any difference |
790 | in the interpretation of character codes between a host and a target |
791 | system is your problem. In particular, if host and target use different |
792 | code points to represent the characters used in the text representation |
793 | of floating-point numbers, you will not be able be able to exchange |
794 | floating-point data, even with nstore(). |
795 | |
7a6a85bf |
796 | =head1 CREDITS |
797 | |
798 | Thank 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 |
808 | Justin Banks <justinb@wamnet.com> |
809 | Jarkko Hietaniemi <jhi@iki.fi> (AGAIN, as perl 5.7.0 Pumpkin!) |
dd19458b |
810 | Salvador Ortiz Garcia <sog@msg.com.mx> |
811 | Dominic Dunlop <domo@computer.org> |
812 | Erik Haugan <erik@solbors.no> |
7a6a85bf |
813 | |
814 | for their bug reports, suggestions and contributions. |
815 | |
816 | Benjamin Holzman contributed the tied variable support, Andrew Ford |
817 | contributed the canonical order for hashes, and Gisle Aas fixed |
818 | a few misunderstandings of mine regarding the Perl internals, |
819 | and optimized the emission of "tags" in the output streams by |
820 | simply counting the objects instead of tagging them (leading to |
821 | a binary incompatibility for the Storable image starting at version |
822 | 0.6--older images are of course still properly understood). |
823 | Murray Nesbitt made Storable thread-safe. Marc Lehmann added overloading |
824 | and reference to tied items support. |
825 | |
826 | =head1 TRANSLATIONS |
827 | |
828 | There is a Japanese translation of this man page available at |
829 | http://member.nifty.ne.jp/hippo2000/perltips/storable.htm , |
830 | courtesy of Kawai, Takanori <kawai@nippon-rad.co.jp>. |
831 | |
832 | =head1 AUTHOR |
833 | |
834 | Raphael Manfredi F<E<lt>Raphael_Manfredi@pobox.comE<gt>> |
835 | |
836 | =head1 SEE ALSO |
837 | |
838 | Clone(3). |
839 | |
840 | =cut |
841 | |