Commit | Line | Data |
25f64a11 |
1 | # |
2 | # Copyright (c) 1995-2000, Raphael Manfredi |
3 | # |
4 | # You may redistribute only under the same terms as Perl 5, as specified |
5 | # in the README file that comes with the distribution. |
6 | # |
7a6a85bf |
7 | |
8 | require DynaLoader; |
9 | require Exporter; |
10 | package Storable; @ISA = qw(Exporter DynaLoader); |
11 | |
12 | @EXPORT = qw(store retrieve); |
13 | @EXPORT_OK = qw( |
9e21b3d0 |
14 | nstore store_fd nstore_fd fd_retrieve |
7a6a85bf |
15 | freeze nfreeze thaw |
16 | dclone |
9e21b3d0 |
17 | retrieve_fd |
dd19458b |
18 | lock_store lock_nstore lock_retrieve |
d4b9b6e4 |
19 | file_magic read_magic |
7a6a85bf |
20 | ); |
21 | |
22 | use AutoLoader; |
01d7b99e |
23 | use vars qw($canonical $forgive_me $VERSION); |
7a6a85bf |
24 | |
2fc01f5f |
25 | $VERSION = '2.15_02'; |
7a6a85bf |
26 | *AUTOLOAD = \&AutoLoader::AUTOLOAD; # Grrr... |
27 | |
28 | # |
29 | # Use of Log::Agent is optional |
30 | # |
31 | |
bb65ef26 |
32 | { |
33 | local $SIG{__DIE__}; |
34 | eval "use Log::Agent"; |
35 | } |
7a6a85bf |
36 | |
530b72ba |
37 | require Carp; |
7a6a85bf |
38 | |
dd19458b |
39 | # |
40 | # They might miss :flock in Fcntl |
41 | # |
42 | |
43 | BEGIN { |
596596d5 |
44 | if (eval { require Fcntl; 1 } && exists $Fcntl::EXPORT_TAGS{'flock'}) { |
dd19458b |
45 | Fcntl->import(':flock'); |
46 | } else { |
47 | eval q{ |
48 | sub LOCK_SH () {1} |
49 | sub LOCK_EX () {2} |
50 | }; |
51 | } |
52 | } |
53 | |
a8b7ef86 |
54 | sub CLONE { |
55 | # clone context under threads |
56 | Storable::init_perinterp(); |
57 | } |
58 | |
b8778c7c |
59 | # Can't Autoload cleanly as this clashes 8.3 with &retrieve |
9e21b3d0 |
60 | sub retrieve_fd { &fd_retrieve } # Backward compatibility |
cb3d9de5 |
61 | |
530b72ba |
62 | # By default restricted hashes are downgraded on earlier perls. |
63 | |
64 | $Storable::downgrade_restricted = 1; |
e8189732 |
65 | $Storable::accept_future_minor = 1; |
b8778c7c |
66 | bootstrap Storable; |
67 | 1; |
68 | __END__ |
530b72ba |
69 | # |
70 | # Use of Log::Agent is optional. If it hasn't imported these subs then |
71 | # Autoloader will kindly supply our fallback implementation. |
72 | # |
73 | |
74 | sub logcroak { |
75 | Carp::croak(@_); |
76 | } |
77 | |
78 | sub logcarp { |
79 | Carp::carp(@_); |
80 | } |
b8778c7c |
81 | |
862382c7 |
82 | # |
83 | # Determine whether locking is possible, but only when needed. |
84 | # |
85 | |
530b72ba |
86 | sub CAN_FLOCK; my $CAN_FLOCK; sub CAN_FLOCK { |
862382c7 |
87 | return $CAN_FLOCK if defined $CAN_FLOCK; |
88 | require Config; import Config; |
89 | return $CAN_FLOCK = |
90 | $Config{'d_flock'} || |
91 | $Config{'d_fcntl_can_lock'} || |
92 | $Config{'d_lockf'}; |
93 | } |
94 | |
0a0da639 |
95 | sub show_file_magic { |
96 | print <<EOM; |
97 | # |
98 | # To recognize the data files of the Perl module Storable, |
99 | # the following lines need to be added to the local magic(5) file, |
100 | # usually either /usr/share/misc/magic or /etc/magic. |
0a0da639 |
101 | # |
102 | 0 string perl-store perl Storable(v0.6) data |
8b793558 |
103 | >4 byte >0 (net-order %d) |
104 | >>4 byte &01 (network-ordered) |
105 | >>4 byte =3 (major 1) |
106 | >>4 byte =2 (major 1) |
107 | |
0a0da639 |
108 | 0 string pst0 perl Storable(v0.7) data |
8b793558 |
109 | >4 byte >0 |
110 | >>4 byte &01 (network-ordered) |
111 | >>4 byte =5 (major 2) |
112 | >>4 byte =4 (major 2) |
113 | >>5 byte >0 (minor %d) |
0a0da639 |
114 | EOM |
115 | } |
116 | |
d4b9b6e4 |
117 | sub file_magic { |
118 | my $file = shift; |
119 | open(my $fh, "<", $file) || die "Can't open '$file': $!"; |
120 | binmode($fh); |
121 | defined(sysread($fh, my $buf, 32)) || die "Can't read from '$file': $!"; |
122 | close($fh); |
123 | |
124 | $file = "./$file" unless $file; # ensure TRUE value |
125 | |
126 | return read_magic($buf, $file); |
127 | } |
128 | |
b8778c7c |
129 | sub read_magic { |
d4b9b6e4 |
130 | my($buf, $file) = @_; |
131 | my %info; |
132 | |
133 | my $buflen = length($buf); |
134 | my $magic; |
135 | if ($buf =~ s/^(pst0|perl-store)//) { |
136 | $magic = $1; |
137 | $info{file} = $file || 1; |
138 | } |
139 | else { |
140 | return undef if $file; |
141 | $magic = ""; |
142 | } |
143 | |
144 | return undef unless length($buf); |
145 | |
146 | my $net_order; |
147 | if ($magic eq "perl-store" && ord(substr($buf, 0, 1)) > 1) { |
148 | $info{version} = -1; |
149 | $net_order = 0; |
150 | } |
151 | else { |
152 | $net_order = ord(substr($buf, 0, 1, "")); |
153 | my $major = $net_order >> 1; |
154 | return undef if $major > 4; # sanity (assuming we never go that high) |
155 | $info{major} = $major; |
156 | $net_order &= 0x01; |
157 | if ($major > 1) { |
158 | return undef unless length($buf); |
159 | my $minor = ord(substr($buf, 0, 1, "")); |
160 | $info{minor} = $minor; |
161 | $info{version} = "$major.$minor"; |
162 | $info{version_nv} = sprintf "%d.%03d", $major, $minor; |
163 | } |
164 | else { |
165 | $info{version} = $major; |
166 | } |
167 | } |
168 | $info{version_nv} ||= $info{version}; |
169 | $info{netorder} = $net_order; |
170 | |
171 | unless ($net_order) { |
172 | return undef unless length($buf); |
173 | my $len = ord(substr($buf, 0, 1, "")); |
174 | return undef unless length($buf) >= $len; |
175 | return undef unless $len == 4 || $len == 8; # sanity |
176 | $info{byteorder} = substr($buf, 0, $len, ""); |
177 | $info{intsize} = ord(substr($buf, 0, 1, "")); |
178 | $info{longsize} = ord(substr($buf, 0, 1, "")); |
179 | $info{ptrsize} = ord(substr($buf, 0, 1, "")); |
180 | if ($info{version_nv} >= 2.002) { |
181 | return undef unless length($buf); |
182 | $info{nvsize} = ord(substr($buf, 0, 1, "")); |
183 | } |
184 | } |
185 | $info{hdrsize} = $buflen - length($buf); |
186 | |
187 | return \%info; |
188 | } |
189 | |
190 | sub BIN_VERSION_NV { |
191 | sprintf "%d.%03d", BIN_MAJOR(), BIN_MINOR(); |
192 | } |
193 | |
194 | sub BIN_WRITE_VERSION_NV { |
195 | sprintf "%d.%03d", BIN_MAJOR(), BIN_WRITE_MINOR(); |
b8778c7c |
196 | } |
7a6a85bf |
197 | |
198 | # |
199 | # store |
200 | # |
201 | # Store target object hierarchy, identified by a reference to its root. |
202 | # The stored object tree may later be retrieved to memory via retrieve. |
203 | # Returns undef if an I/O error occurred, in which case the file is |
204 | # removed. |
205 | # |
206 | sub store { |
dd19458b |
207 | return _store(\&pstore, @_, 0); |
7a6a85bf |
208 | } |
209 | |
210 | # |
211 | # nstore |
212 | # |
213 | # Same as store, but in network order. |
214 | # |
215 | sub nstore { |
dd19458b |
216 | return _store(\&net_pstore, @_, 0); |
217 | } |
218 | |
219 | # |
220 | # lock_store |
221 | # |
222 | # Same as store, but flock the file first (advisory locking). |
223 | # |
224 | sub lock_store { |
225 | return _store(\&pstore, @_, 1); |
226 | } |
227 | |
228 | # |
229 | # lock_nstore |
230 | # |
231 | # Same as nstore, but flock the file first (advisory locking). |
232 | # |
233 | sub lock_nstore { |
234 | return _store(\&net_pstore, @_, 1); |
7a6a85bf |
235 | } |
236 | |
237 | # Internal store to file routine |
238 | sub _store { |
239 | my $xsptr = shift; |
240 | my $self = shift; |
dd19458b |
241 | my ($file, $use_locking) = @_; |
7a6a85bf |
242 | logcroak "not a reference" unless ref($self); |
b12202d0 |
243 | logcroak "wrong argument number" unless @_ == 2; # No @foo in arglist |
7a6a85bf |
244 | local *FILE; |
dd19458b |
245 | if ($use_locking) { |
6e0ac6f5 |
246 | open(FILE, ">>$file") || logcroak "can't write into $file: $!"; |
862382c7 |
247 | unless (&CAN_FLOCK) { |
b29b780f |
248 | logcarp "Storable::lock_store: fcntl/flock emulation broken on $^O"; |
249 | return undef; |
f567092b |
250 | } |
dd19458b |
251 | flock(FILE, LOCK_EX) || |
252 | logcroak "can't get exclusive lock on $file: $!"; |
253 | truncate FILE, 0; |
254 | # Unlocking will happen when FILE is closed |
6e0ac6f5 |
255 | } else { |
256 | open(FILE, ">$file") || logcroak "can't create $file: $!"; |
dd19458b |
257 | } |
6e0ac6f5 |
258 | binmode FILE; # Archaic systems... |
7a6a85bf |
259 | my $da = $@; # Don't mess if called from exception handler |
260 | my $ret; |
261 | # Call C routine nstore or pstore, depending on network order |
262 | eval { $ret = &$xsptr(*FILE, $self) }; |
263 | close(FILE) or $ret = undef; |
264 | unlink($file) or warn "Can't unlink $file: $!\n" if $@ || !defined $ret; |
265 | logcroak $@ if $@ =~ s/\.?\n$/,/; |
266 | $@ = $da; |
267 | return $ret ? $ret : undef; |
268 | } |
269 | |
270 | # |
271 | # store_fd |
272 | # |
273 | # Same as store, but perform on an already opened file descriptor instead. |
274 | # Returns undef if an I/O error occurred. |
275 | # |
276 | sub store_fd { |
277 | return _store_fd(\&pstore, @_); |
278 | } |
279 | |
280 | # |
281 | # nstore_fd |
282 | # |
283 | # Same as store_fd, but in network order. |
284 | # |
285 | sub nstore_fd { |
286 | my ($self, $file) = @_; |
287 | return _store_fd(\&net_pstore, @_); |
288 | } |
289 | |
290 | # Internal store routine on opened file descriptor |
291 | sub _store_fd { |
292 | my $xsptr = shift; |
293 | my $self = shift; |
294 | my ($file) = @_; |
295 | logcroak "not a reference" unless ref($self); |
296 | logcroak "too many arguments" unless @_ == 1; # No @foo in arglist |
297 | my $fd = fileno($file); |
298 | logcroak "not a valid file descriptor" unless defined $fd; |
299 | my $da = $@; # Don't mess if called from exception handler |
300 | my $ret; |
301 | # Call C routine nstore or pstore, depending on network order |
302 | eval { $ret = &$xsptr($file, $self) }; |
303 | logcroak $@ if $@ =~ s/\.?\n$/,/; |
596596d5 |
304 | local $\; print $file ''; # Autoflush the file if wanted |
7a6a85bf |
305 | $@ = $da; |
306 | return $ret ? $ret : undef; |
307 | } |
308 | |
309 | # |
310 | # freeze |
311 | # |
312 | # Store oject and its hierarchy in memory and return a scalar |
313 | # containing the result. |
314 | # |
315 | sub freeze { |
316 | _freeze(\&mstore, @_); |
317 | } |
318 | |
319 | # |
320 | # nfreeze |
321 | # |
322 | # Same as freeze but in network order. |
323 | # |
324 | sub nfreeze { |
325 | _freeze(\&net_mstore, @_); |
326 | } |
327 | |
328 | # Internal freeze routine |
329 | sub _freeze { |
330 | my $xsptr = shift; |
331 | my $self = shift; |
332 | logcroak "not a reference" unless ref($self); |
333 | logcroak "too many arguments" unless @_ == 0; # No @foo in arglist |
334 | my $da = $@; # Don't mess if called from exception handler |
335 | my $ret; |
336 | # Call C routine mstore or net_mstore, depending on network order |
337 | eval { $ret = &$xsptr($self) }; |
338 | logcroak $@ if $@ =~ s/\.?\n$/,/; |
339 | $@ = $da; |
340 | return $ret ? $ret : undef; |
341 | } |
342 | |
343 | # |
344 | # retrieve |
345 | # |
346 | # Retrieve object hierarchy from disk, returning a reference to the root |
347 | # object of that tree. |
348 | # |
349 | sub retrieve { |
dd19458b |
350 | _retrieve($_[0], 0); |
351 | } |
352 | |
353 | # |
354 | # lock_retrieve |
355 | # |
356 | # Same as retrieve, but with advisory locking. |
357 | # |
358 | sub lock_retrieve { |
359 | _retrieve($_[0], 1); |
360 | } |
361 | |
362 | # Internal retrieve routine |
363 | sub _retrieve { |
364 | my ($file, $use_locking) = @_; |
7a6a85bf |
365 | local *FILE; |
dd19458b |
366 | open(FILE, $file) || logcroak "can't open $file: $!"; |
7a6a85bf |
367 | binmode FILE; # Archaic systems... |
368 | my $self; |
369 | my $da = $@; # Could be from exception handler |
dd19458b |
370 | if ($use_locking) { |
862382c7 |
371 | unless (&CAN_FLOCK) { |
8be2b38b |
372 | logcarp "Storable::lock_store: fcntl/flock emulation broken on $^O"; |
b29b780f |
373 | return undef; |
374 | } |
8be2b38b |
375 | flock(FILE, LOCK_SH) || logcroak "can't get shared lock on $file: $!"; |
dd19458b |
376 | # Unlocking will happen when FILE is closed |
377 | } |
7a6a85bf |
378 | eval { $self = pretrieve(*FILE) }; # Call C routine |
379 | close(FILE); |
380 | logcroak $@ if $@ =~ s/\.?\n$/,/; |
381 | $@ = $da; |
382 | return $self; |
383 | } |
384 | |
385 | # |
9e21b3d0 |
386 | # fd_retrieve |
7a6a85bf |
387 | # |
388 | # Same as retrieve, but perform from an already opened file descriptor instead. |
389 | # |
9e21b3d0 |
390 | sub fd_retrieve { |
7a6a85bf |
391 | my ($file) = @_; |
392 | my $fd = fileno($file); |
393 | logcroak "not a valid file descriptor" unless defined $fd; |
394 | my $self; |
395 | my $da = $@; # Could be from exception handler |
396 | eval { $self = pretrieve($file) }; # Call C routine |
397 | logcroak $@ if $@ =~ s/\.?\n$/,/; |
398 | $@ = $da; |
399 | return $self; |
400 | } |
401 | |
402 | # |
403 | # thaw |
404 | # |
405 | # Recreate objects in memory from an existing frozen image created |
406 | # by freeze. If the frozen image passed is undef, return undef. |
407 | # |
408 | sub thaw { |
409 | my ($frozen) = @_; |
410 | return undef unless defined $frozen; |
411 | my $self; |
412 | my $da = $@; # Could be from exception handler |
413 | eval { $self = mretrieve($frozen) }; # Call C routine |
414 | logcroak $@ if $@ =~ s/\.?\n$/,/; |
415 | $@ = $da; |
416 | return $self; |
417 | } |
418 | |
a2307be4 |
419 | 1; |
420 | __END__ |
421 | |
7a6a85bf |
422 | =head1 NAME |
423 | |
f062ea6c |
424 | Storable - persistence for Perl data structures |
7a6a85bf |
425 | |
426 | =head1 SYNOPSIS |
427 | |
428 | use Storable; |
429 | store \%table, 'file'; |
430 | $hashref = retrieve('file'); |
431 | |
432 | use Storable qw(nstore store_fd nstore_fd freeze thaw dclone); |
433 | |
434 | # Network order |
435 | nstore \%table, 'file'; |
436 | $hashref = retrieve('file'); # There is NO nretrieve() |
437 | |
438 | # Storing to and retrieving from an already opened file |
439 | store_fd \@array, \*STDOUT; |
440 | nstore_fd \%table, \*STDOUT; |
9e21b3d0 |
441 | $aryref = fd_retrieve(\*SOCKET); |
442 | $hashref = fd_retrieve(\*SOCKET); |
7a6a85bf |
443 | |
444 | # Serializing to memory |
445 | $serialized = freeze \%table; |
446 | %table_clone = %{ thaw($serialized) }; |
447 | |
448 | # Deep (recursive) cloning |
449 | $cloneref = dclone($ref); |
450 | |
dd19458b |
451 | # Advisory locking |
452 | use Storable qw(lock_store lock_nstore lock_retrieve) |
453 | lock_store \%table, 'file'; |
454 | lock_nstore \%table, 'file'; |
455 | $hashref = lock_retrieve('file'); |
456 | |
7a6a85bf |
457 | =head1 DESCRIPTION |
458 | |
f062ea6c |
459 | The Storable package brings persistence to your Perl data structures |
7a6a85bf |
460 | containing SCALAR, ARRAY, HASH or REF objects, i.e. anything that can be |
c261f00e |
461 | conveniently stored to disk and retrieved at a later time. |
7a6a85bf |
462 | |
463 | It can be used in the regular procedural way by calling C<store> with |
464 | a reference to the object to be stored, along with the file name where |
465 | the image should be written. |
775ecd75 |
466 | |
7a6a85bf |
467 | The routine returns C<undef> for I/O problems or other internal error, |
468 | a true value otherwise. Serious errors are propagated as a C<die> exception. |
469 | |
f062ea6c |
470 | To retrieve data stored to disk, use C<retrieve> with a file name. |
471 | The objects stored into that file are recreated into memory for you, |
472 | and a I<reference> to the root object is returned. In case an I/O error |
7a6a85bf |
473 | occurs while reading, C<undef> is returned instead. Other serious |
474 | errors are propagated via C<die>. |
475 | |
476 | Since storage is performed recursively, you might want to stuff references |
477 | to objects that share a lot of common data into a single array or hash |
478 | table, and then store that object. That way, when you retrieve back the |
479 | whole thing, the objects will continue to share what they originally shared. |
480 | |
481 | At the cost of a slight header overhead, you may store to an already |
482 | opened file descriptor using the C<store_fd> routine, and retrieve |
9e21b3d0 |
483 | from a file via C<fd_retrieve>. Those names aren't imported by default, |
c261f00e |
484 | so you will have to do that explicitly if you need those routines. |
7a6a85bf |
485 | The file descriptor you supply must be already opened, for read |
486 | if you're going to retrieve and for write if you wish to store. |
487 | |
488 | store_fd(\%table, *STDOUT) || die "can't store to stdout\n"; |
9e21b3d0 |
489 | $hashref = fd_retrieve(*STDIN); |
7a6a85bf |
490 | |
491 | You can also store data in network order to allow easy sharing across |
492 | multiple platforms, or when storing on a socket known to be remotely |
493 | connected. The routines to call have an initial C<n> prefix for I<network>, |
494 | as in C<nstore> and C<nstore_fd>. At retrieval time, your data will be |
495 | correctly restored so you don't have to know whether you're restoring |
dd19458b |
496 | from native or network ordered data. Double values are stored stringified |
497 | to ensure portability as well, at the slight risk of loosing some precision |
498 | in the last decimals. |
7a6a85bf |
499 | |
9e21b3d0 |
500 | When using C<fd_retrieve>, objects are retrieved in sequence, one |
7a6a85bf |
501 | object (i.e. one recursive tree) per associated C<store_fd>. |
502 | |
503 | If you're more from the object-oriented camp, you can inherit from |
504 | Storable and directly store your objects by invoking C<store> as |
505 | a method. The fact that the root of the to-be-stored tree is a |
506 | blessed reference (i.e. an object) is special-cased so that the |
507 | retrieve does not provide a reference to that object but rather the |
508 | blessed object reference itself. (Otherwise, you'd get a reference |
509 | to that blessed object). |
510 | |
511 | =head1 MEMORY STORE |
512 | |
513 | The Storable engine can also store data into a Perl scalar instead, to |
514 | later retrieve them. This is mainly used to freeze a complex structure in |
515 | some safe compact memory place (where it can possibly be sent to another |
516 | process via some IPC, since freezing the structure also serializes it in |
517 | effect). Later on, and maybe somewhere else, you can thaw the Perl scalar |
518 | out and recreate the original complex structure in memory. |
519 | |
520 | Surprisingly, the routines to be called are named C<freeze> and C<thaw>. |
521 | If you wish to send out the frozen scalar to another machine, use |
522 | C<nfreeze> instead to get a portable image. |
523 | |
524 | Note that freezing an object structure and immediately thawing it |
525 | actually achieves a deep cloning of that structure: |
526 | |
527 | dclone(.) = thaw(freeze(.)) |
528 | |
529 | Storable provides you with a C<dclone> interface which does not create |
530 | that intermediary scalar but instead freezes the structure in some |
c261f00e |
531 | internal memory space and then immediately thaws it out. |
7a6a85bf |
532 | |
dd19458b |
533 | =head1 ADVISORY LOCKING |
534 | |
f062ea6c |
535 | The C<lock_store> and C<lock_nstore> routine are equivalent to |
536 | C<store> and C<nstore>, except that they get an exclusive lock on |
537 | the file before writing. Likewise, C<lock_retrieve> does the same |
538 | as C<retrieve>, but also gets a shared lock on the file before reading. |
dd19458b |
539 | |
f062ea6c |
540 | As with any advisory locking scheme, the protection only works if you |
541 | systematically use C<lock_store> and C<lock_retrieve>. If one side of |
542 | your application uses C<store> whilst the other uses C<lock_retrieve>, |
dd19458b |
543 | you will get no protection at all. |
544 | |
f062ea6c |
545 | The internal advisory locking is implemented using Perl's flock() |
546 | routine. If your system does not support any form of flock(), or if |
547 | you share your files across NFS, you might wish to use other forms |
548 | of locking by using modules such as LockFile::Simple which lock a |
549 | file using a filesystem entry, instead of locking the file descriptor. |
dd19458b |
550 | |
7a6a85bf |
551 | =head1 SPEED |
552 | |
553 | The heart of Storable is written in C for decent speed. Extra low-level |
4d3295e3 |
554 | optimizations have been made when manipulating perl internals, to |
555 | sacrifice encapsulation for the benefit of greater speed. |
7a6a85bf |
556 | |
557 | =head1 CANONICAL REPRESENTATION |
558 | |
f062ea6c |
559 | Normally, Storable stores elements of hashes in the order they are |
7a6a85bf |
560 | stored internally by Perl, i.e. pseudo-randomly. If you set |
561 | C<$Storable::canonical> to some C<TRUE> value, Storable will store |
562 | hashes with the elements sorted by their key. This allows you to |
563 | compare data structures by comparing their frozen representations (or |
564 | even the compressed frozen representations), which can be useful for |
565 | creating lookup tables for complicated queries. |
566 | |
f062ea6c |
567 | Canonical order does not imply network order; those are two orthogonal |
7a6a85bf |
568 | settings. |
569 | |
d2b96869 |
570 | =head1 CODE REFERENCES |
571 | |
572 | Since Storable version 2.05, CODE references may be serialized with |
573 | the help of L<B::Deparse>. To enable this feature, set |
3c4b39be |
574 | C<$Storable::Deparse> to a true value. To enable deserialization, |
d2b96869 |
575 | C<$Storable::Eval> should be set to a true value. Be aware that |
576 | deserialization is done through C<eval>, which is dangerous if the |
577 | Storable file contains malicious data. You can set C<$Storable::Eval> |
578 | to a subroutine reference which would be used instead of C<eval>. See |
579 | below for an example using a L<Safe> compartment for deserialization |
580 | of CODE references. |
581 | |
197b90bc |
582 | If C<$Storable::Deparse> and/or C<$Storable::Eval> are set to false |
583 | values, then the value of C<$Storable::forgive_me> (see below) is |
584 | respected while serializing and deserializing. |
585 | |
c261f00e |
586 | =head1 FORWARD COMPATIBILITY |
587 | |
588 | This release of Storable can be used on a newer version of Perl to |
f062ea6c |
589 | serialize data which is not supported by earlier Perls. By default, |
c261f00e |
590 | Storable will attempt to do the right thing, by C<croak()>ing if it |
775ecd75 |
591 | encounters data that it cannot deserialize. However, the defaults |
f062ea6c |
592 | can be changed as follows: |
c261f00e |
593 | |
594 | =over 4 |
595 | |
596 | =item utf8 data |
597 | |
598 | Perl 5.6 added support for Unicode characters with code points > 255, |
599 | and Perl 5.8 has full support for Unicode characters in hash keys. |
600 | Perl internally encodes strings with these characters using utf8, and |
601 | Storable serializes them as utf8. By default, if an older version of |
602 | Perl encounters a utf8 value it cannot represent, it will C<croak()>. |
603 | To change this behaviour so that Storable deserializes utf8 encoded |
604 | values as the string of bytes (effectively dropping the I<is_utf8> flag) |
605 | set C<$Storable::drop_utf8> to some C<TRUE> value. This is a form of |
606 | data loss, because with C<$drop_utf8> true, it becomes impossible to tell |
607 | whether the original data was the Unicode string, or a series of bytes |
608 | that happen to be valid utf8. |
609 | |
610 | =item restricted hashes |
611 | |
f062ea6c |
612 | Perl 5.8 adds support for restricted hashes, which have keys |
613 | restricted to a given set, and can have values locked to be read only. |
614 | By default, when Storable encounters a restricted hash on a perl |
615 | that doesn't support them, it will deserialize it as a normal hash, |
616 | silently discarding any placeholder keys and leaving the keys and |
617 | all values unlocked. To make Storable C<croak()> instead, set |
618 | C<$Storable::downgrade_restricted> to a C<FALSE> value. To restore |
619 | the default set it back to some C<TRUE> value. |
c261f00e |
620 | |
e8189732 |
621 | =item files from future versions of Storable |
622 | |
623 | Earlier versions of Storable would immediately croak if they encountered |
624 | a file with a higher internal version number than the reading Storable |
625 | knew about. Internal version numbers are increased each time new data |
626 | types (such as restricted hashes) are added to the vocabulary of the file |
627 | format. This meant that a newer Storable module had no way of writing a |
f062ea6c |
628 | file readable by an older Storable, even if the writer didn't store newer |
e8189732 |
629 | data types. |
630 | |
631 | This version of Storable will defer croaking until it encounters a data |
632 | type in the file that it does not recognize. This means that it will |
633 | continue to read files generated by newer Storable modules which are careful |
634 | in what they write out, making it easier to upgrade Storable modules in a |
635 | mixed environment. |
636 | |
637 | The old behaviour of immediate croaking can be re-instated by setting |
f062ea6c |
638 | C<$Storable::accept_future_minor> to some C<FALSE> value. |
e8189732 |
639 | |
c261f00e |
640 | =back |
641 | |
f062ea6c |
642 | All these variables have no effect on a newer Perl which supports the |
c261f00e |
643 | relevant feature. |
644 | |
7a6a85bf |
645 | =head1 ERROR REPORTING |
646 | |
647 | Storable uses the "exception" paradigm, in that it does not try to workaround |
648 | failures: if something bad happens, an exception is generated from the |
649 | caller's perspective (see L<Carp> and C<croak()>). Use eval {} to trap |
650 | those exceptions. |
651 | |
652 | When Storable croaks, it tries to report the error via the C<logcroak()> |
653 | routine from the C<Log::Agent> package, if it is available. |
654 | |
212e9bde |
655 | Normal errors are reported by having store() or retrieve() return C<undef>. |
656 | Such errors are usually I/O errors (or truncated stream errors at retrieval). |
657 | |
7a6a85bf |
658 | =head1 WIZARDS ONLY |
659 | |
660 | =head2 Hooks |
661 | |
662 | Any class may define hooks that will be called during the serialization |
663 | and deserialization process on objects that are instances of that class. |
664 | Those hooks can redefine the way serialization is performed (and therefore, |
c261f00e |
665 | how the symmetrical deserialization should be conducted). |
7a6a85bf |
666 | |
667 | Since we said earlier: |
668 | |
669 | dclone(.) = thaw(freeze(.)) |
670 | |
671 | everything we say about hooks should also hold for deep cloning. However, |
672 | hooks get to know whether the operation is a mere serialization, or a cloning. |
673 | |
674 | Therefore, when serializing hooks are involved, |
675 | |
676 | dclone(.) <> thaw(freeze(.)) |
677 | |
678 | Well, you could keep them in sync, but there's no guarantee it will always |
679 | hold on classes somebody else wrote. Besides, there is little to gain in |
f062ea6c |
680 | doing so: a serializing hook could keep only one attribute of an object, |
7a6a85bf |
681 | which is probably not what should happen during a deep cloning of that |
682 | same object. |
683 | |
684 | Here is the hooking interface: |
685 | |
bbc7dcd2 |
686 | =over 4 |
7a6a85bf |
687 | |
688 | =item C<STORABLE_freeze> I<obj>, I<cloning> |
689 | |
690 | The serializing hook, called on the object during serialization. It can be |
691 | inherited, or defined in the class itself, like any other method. |
692 | |
693 | Arguments: I<obj> is the object to serialize, I<cloning> is a flag indicating |
694 | whether we're in a dclone() or a regular serialization via store() or freeze(). |
695 | |
696 | Returned value: A LIST C<($serialized, $ref1, $ref2, ...)> where $serialized |
697 | is the serialized form to be used, and the optional $ref1, $ref2, etc... are |
698 | extra references that you wish to let the Storable engine serialize. |
699 | |
700 | At deserialization time, you will be given back the same LIST, but all the |
701 | extra references will be pointing into the deserialized structure. |
702 | |
703 | The B<first time> the hook is hit in a serialization flow, you may have it |
704 | return an empty list. That will signal the Storable engine to further |
705 | discard that hook for this class and to therefore revert to the default |
706 | serialization of the underlying Perl data. The hook will again be normally |
707 | processed in the next serialization. |
708 | |
709 | Unless you know better, serializing hook should always say: |
710 | |
711 | sub STORABLE_freeze { |
712 | my ($self, $cloning) = @_; |
713 | return if $cloning; # Regular default serialization |
714 | .... |
715 | } |
716 | |
717 | in order to keep reasonable dclone() semantics. |
718 | |
719 | =item C<STORABLE_thaw> I<obj>, I<cloning>, I<serialized>, ... |
720 | |
721 | The deserializing hook called on the object during deserialization. |
f062ea6c |
722 | But wait: if we're deserializing, there's no object yet... right? |
7a6a85bf |
723 | |
724 | Wrong: the Storable engine creates an empty one for you. If you know Eiffel, |
725 | you can view C<STORABLE_thaw> as an alternate creation routine. |
726 | |
727 | This means the hook can be inherited like any other method, and that |
728 | I<obj> is your blessed reference for this particular instance. |
729 | |
730 | The other arguments should look familiar if you know C<STORABLE_freeze>: |
731 | I<cloning> is true when we're part of a deep clone operation, I<serialized> |
732 | is the serialized string you returned to the engine in C<STORABLE_freeze>, |
733 | and there may be an optional list of references, in the same order you gave |
734 | them at serialization time, pointing to the deserialized objects (which |
735 | have been processed courtesy of the Storable engine). |
736 | |
212e9bde |
737 | When the Storable engine does not find any C<STORABLE_thaw> hook routine, |
738 | it tries to load the class by requiring the package dynamically (using |
739 | the blessed package name), and then re-attempts the lookup. If at that |
740 | time the hook cannot be located, the engine croaks. Note that this mechanism |
c261f00e |
741 | will fail if you define several classes in the same file, but L<perlmod> |
212e9bde |
742 | warned you. |
743 | |
f062ea6c |
744 | It is up to you to use this information to populate I<obj> the way you want. |
7a6a85bf |
745 | |
746 | Returned value: none. |
747 | |
2f796f32 |
748 | =item C<STORABLE_attach> I<class>, I<cloning>, I<serialized> |
749 | |
750 | While C<STORABLE_freeze> and C<STORABLE_thaw> are useful for classes where |
3c4b39be |
751 | each instance is independent, this mechanism has difficulty (or is |
2f796f32 |
752 | incompatible) with objects that exist as common process-level or |
753 | system-level resources, such as singleton objects, database pools, caches |
754 | or memoized objects. |
755 | |
756 | The alternative C<STORABLE_attach> method provides a solution for these |
1e2a0f0b |
757 | shared objects. Instead of C<STORABLE_freeze> --E<gt> C<STORABLE_thaw>, |
758 | you implement C<STORABLE_freeze> --E<gt> C<STORABLE_attach> instead. |
2f796f32 |
759 | |
760 | Arguments: I<class> is the class we are attaching to, I<cloning> is a flag |
761 | indicating whether we're in a dclone() or a regular de-serialization via |
762 | thaw(), and I<serialized> is the stored string for the resource object. |
763 | |
764 | Because these resource objects are considered to be owned by the entire |
765 | process/system, and not the "property" of whatever is being serialized, |
766 | no references underneath the object should be included in the serialized |
767 | string. Thus, in any class that implements C<STORABLE_attach>, the |
768 | C<STORABLE_freeze> method cannot return any references, and C<Storable> |
769 | will throw an error if C<STORABLE_freeze> tries to return references. |
770 | |
771 | All information required to "attach" back to the shared resource object |
772 | B<must> be contained B<only> in the C<STORABLE_freeze> return string. |
773 | Otherwise, C<STORABLE_freeze> behaves as normal for C<STORABLE_attach> |
774 | classes. |
775 | |
776 | Because C<STORABLE_attach> is passed the class (rather than an object), |
777 | it also returns the object directly, rather than modifying the passed |
778 | object. |
779 | |
780 | Returned value: object of type C<class> |
781 | |
7a6a85bf |
782 | =back |
783 | |
784 | =head2 Predicates |
785 | |
c261f00e |
786 | Predicates are not exportable. They must be called by explicitly prefixing |
7a6a85bf |
787 | them with the Storable package name. |
788 | |
bbc7dcd2 |
789 | =over 4 |
7a6a85bf |
790 | |
791 | =item C<Storable::last_op_in_netorder> |
792 | |
793 | The C<Storable::last_op_in_netorder()> predicate will tell you whether |
794 | network order was used in the last store or retrieve operation. If you |
795 | don't know how to use this, just forget about it. |
796 | |
797 | =item C<Storable::is_storing> |
798 | |
799 | Returns true if within a store operation (via STORABLE_freeze hook). |
800 | |
801 | =item C<Storable::is_retrieving> |
802 | |
f062ea6c |
803 | Returns true if within a retrieve operation (via STORABLE_thaw hook). |
7a6a85bf |
804 | |
805 | =back |
806 | |
807 | =head2 Recursion |
808 | |
f062ea6c |
809 | With hooks comes the ability to recurse back to the Storable engine. |
810 | Indeed, hooks are regular Perl code, and Storable is convenient when |
811 | it comes to serializing and deserializing things, so why not use it |
812 | to handle the serialization string? |
7a6a85bf |
813 | |
f062ea6c |
814 | There are a few things you need to know, however: |
7a6a85bf |
815 | |
bbc7dcd2 |
816 | =over 4 |
7a6a85bf |
817 | |
818 | =item * |
819 | |
820 | You can create endless loops if the things you serialize via freeze() |
f062ea6c |
821 | (for instance) point back to the object we're trying to serialize in |
822 | the hook. |
7a6a85bf |
823 | |
824 | =item * |
825 | |
826 | Shared references among objects will not stay shared: if we're serializing |
827 | the list of object [A, C] where both object A and C refer to the SAME object |
828 | B, and if there is a serializing hook in A that says freeze(B), then when |
829 | deserializing, we'll get [A', C'] where A' refers to B', but C' refers to D, |
830 | a deep clone of B'. The topology was not preserved. |
831 | |
832 | =back |
833 | |
834 | That's why C<STORABLE_freeze> lets you provide a list of references |
835 | to serialize. The engine guarantees that those will be serialized in the |
836 | same context as the other objects, and therefore that shared objects will |
837 | stay shared. |
838 | |
839 | In the above [A, C] example, the C<STORABLE_freeze> hook could return: |
840 | |
841 | ("something", $self->{B}) |
842 | |
843 | and the B part would be serialized by the engine. In C<STORABLE_thaw>, you |
844 | would get back the reference to the B' object, deserialized for you. |
845 | |
846 | Therefore, recursion should normally be avoided, but is nonetheless supported. |
847 | |
848 | =head2 Deep Cloning |
849 | |
f062ea6c |
850 | There is a Clone module available on CPAN which implements deep cloning |
7a6a85bf |
851 | natively, i.e. without freezing to memory and thawing the result. It is |
852 | aimed to replace Storable's dclone() some day. However, it does not currently |
853 | support Storable hooks to redefine the way deep cloning is performed. |
854 | |
0a0da639 |
855 | =head1 Storable magic |
856 | |
857 | Yes, there's a lot of that :-) But more precisely, in UNIX systems |
858 | there's a utility called C<file>, which recognizes data files based on |
859 | their contents (usually their first few bytes). For this to work, |
8b793558 |
860 | a certain file called F<magic> needs to taught about the I<signature> |
0a0da639 |
861 | of the data. Where that configuration file lives depends on the UNIX |
f062ea6c |
862 | flavour; often it's something like F</usr/share/misc/magic> or |
8b793558 |
863 | F</etc/magic>. Your system administrator needs to do the updating of |
864 | the F<magic> file. The necessary signature information is output to |
f062ea6c |
865 | STDOUT by invoking Storable::show_file_magic(). Note that the GNU |
866 | implementation of the C<file> utility, version 3.38 or later, |
867 | is expected to contain support for recognising Storable files |
868 | out-of-the-box, in addition to other kinds of Perl files. |
0a0da639 |
869 | |
d4b9b6e4 |
870 | You can also use the following functions to extract the file header |
871 | information from Storable images: |
872 | |
873 | =over |
874 | |
875 | =item $info = Storable::file_magic( $filename ) |
876 | |
877 | If the given file is a Storable image return a hash describing it. If |
878 | the file is readable, but not a Storable image return C<undef>. If |
879 | the file does not exist or is unreadable then croak. |
880 | |
881 | The hash returned has the following elements: |
882 | |
883 | =over |
884 | |
885 | =item C<version> |
886 | |
887 | This returns the file format version. It is a string like "2.7". |
888 | |
889 | Note that this version number is not the same as the version number of |
890 | the Storable module itself. For instance Storable v0.7 create files |
891 | in format v2.0 and Storable v2.15 create files in format v2.7. The |
892 | file format version number only increment when additional features |
893 | that would confuse older versions of the module are added. |
894 | |
895 | Files older than v2.0 will have the one of the version numbers "-1", |
896 | "0" or "1". No minor number was used at that time. |
897 | |
898 | =item C<version_nv> |
899 | |
900 | This returns the file format version as number. It is a string like |
901 | "2.007". This value is suitable for numeric comparisons. |
902 | |
903 | The constant function C<Storable::BIN_VERSION_NV> returns a comparable |
904 | number that represent the highest file version number that this |
905 | version of Storable fully support (but see discussion of |
906 | C<$Storable::accept_future_minor> above). The constant |
907 | C<Storable::BIN_WRITE_VERSION_NV> function returns what file version |
908 | is written and might be less than C<Storable::BIN_VERSION_NV> in some |
909 | configuations. |
910 | |
911 | =item C<major>, C<minor> |
912 | |
913 | This also returns the file format version. If the version is "2.7" |
914 | then major would be 2 and minor would be 7. The minor element is |
915 | missing for when major is less than 2. |
916 | |
917 | =item C<hdrsize> |
918 | |
919 | The is the number of bytes that the Storable header occupies. |
920 | |
921 | =item C<netorder> |
922 | |
923 | This is TRUE if the image store data in network order. This means |
924 | that it was created with nstore() or similar. |
925 | |
926 | =item C<byteorder> |
927 | |
928 | This is only present when C<netorder> is FALSE. It is the |
929 | $Config{byteorder} string of the perl that created this image. It is |
930 | a string like "1234" (32 bit little endian) or "87654321" (64 bit big |
931 | endian). This must match the current perl for the image to be |
932 | readable by Storable. |
933 | |
934 | =item C<intsize>, C<longsize>, C<ptrsize>, C<nvsize> |
935 | |
936 | These are only present when C<netorder> is FALSE. These are the sizes of |
937 | various C datatypes of the perl that created this image. These must |
938 | match the current perl for the image to be readable by Storable. |
939 | |
940 | The C<nvsize> element is only present for file format v2.2 and |
941 | higher. |
942 | |
943 | =item C<file> |
944 | |
945 | The name of the file. |
946 | |
947 | =back |
948 | |
949 | =item $info = Storable::read_magic( $buffer ) |
950 | |
951 | =item $info = Storable::read_magic( $buffer, $must_be_file ) |
952 | |
953 | The $buffer should be a Storable image or the first few bytes of it. |
954 | If $buffer starts with a Storable header, then a hash describing the |
955 | image is returned, otherwise C<undef> is returned. |
956 | |
957 | The hash has the same structure as the one returned by |
958 | Storable::file_magic(). The C<file> element is true if the image is a |
959 | file image. |
960 | |
961 | If the $must_be_file argument is provided and is TRUE, then return |
962 | C<undef> unless the image looks like it belongs to a file dump. |
963 | |
964 | The maximum size of a Storable header is currently 21 bytes. If the |
965 | provided $buffer is only the first part of a Storable image it should |
966 | at least be this long to ensure that read_magic() will recognize it as |
967 | such. |
968 | |
969 | =back |
970 | |
7a6a85bf |
971 | =head1 EXAMPLES |
972 | |
973 | Here are some code samples showing a possible usage of Storable: |
974 | |
975 | use Storable qw(store retrieve freeze thaw dclone); |
976 | |
977 | %color = ('Blue' => 0.1, 'Red' => 0.8, 'Black' => 0, 'White' => 1); |
978 | |
2359510d |
979 | store(\%color, 'mycolors') or die "Can't store %a in mycolors!\n"; |
7a6a85bf |
980 | |
2359510d |
981 | $colref = retrieve('mycolors'); |
982 | die "Unable to retrieve from mycolors!\n" unless defined $colref; |
7a6a85bf |
983 | printf "Blue is still %lf\n", $colref->{'Blue'}; |
984 | |
985 | $colref2 = dclone(\%color); |
986 | |
987 | $str = freeze(\%color); |
988 | printf "Serialization of %%color is %d bytes long.\n", length($str); |
989 | $colref3 = thaw($str); |
990 | |
991 | which prints (on my machine): |
992 | |
993 | Blue is still 0.100000 |
994 | Serialization of %color is 102 bytes long. |
995 | |
d2b96869 |
996 | Serialization of CODE references and deserialization in a safe |
997 | compartment: |
998 | |
197b90bc |
999 | =for example begin |
1000 | |
d2b96869 |
1001 | use Storable qw(freeze thaw); |
1002 | use Safe; |
1003 | use strict; |
1004 | my $safe = new Safe; |
197b90bc |
1005 | # because of opcodes used in "use strict": |
d1e2299c |
1006 | $safe->permit(qw(:default require)); |
d2b96869 |
1007 | local $Storable::Deparse = 1; |
1008 | local $Storable::Eval = sub { $safe->reval($_[0]) }; |
197b90bc |
1009 | my $serialized = freeze(sub { 42 }); |
d2b96869 |
1010 | my $code = thaw($serialized); |
197b90bc |
1011 | $code->() == 42; |
1012 | |
1013 | =for example end |
1014 | |
1015 | =for example_testing |
1016 | is( $code->(), 42 ); |
d2b96869 |
1017 | |
7a6a85bf |
1018 | =head1 WARNING |
1019 | |
1020 | If you're using references as keys within your hash tables, you're bound |
f062ea6c |
1021 | to be disappointed when retrieving your data. Indeed, Perl stringifies |
7a6a85bf |
1022 | references used as hash table keys. If you later wish to access the |
1023 | items via another reference stringification (i.e. using the same |
1024 | reference that was used for the key originally to record the value into |
1025 | the hash table), it will work because both references stringify to the |
1026 | same string. |
1027 | |
6fe6778b |
1028 | It won't work across a sequence of C<store> and C<retrieve> operations, |
1029 | however, because the addresses in the retrieved objects, which are |
1030 | part of the stringified references, will probably differ from the |
1031 | original addresses. The topology of your structure is preserved, |
1032 | but not hidden semantics like those. |
7a6a85bf |
1033 | |
1034 | On platforms where it matters, be sure to call C<binmode()> on the |
1035 | descriptors that you pass to Storable functions. |
1036 | |
1037 | Storing data canonically that contains large hashes can be |
1038 | significantly slower than storing the same data normally, as |
c261f00e |
1039 | temporary arrays to hold the keys for each hash have to be allocated, |
7a6a85bf |
1040 | populated, sorted and freed. Some tests have shown a halving of the |
1041 | speed of storing -- the exact penalty will depend on the complexity of |
1042 | your data. There is no slowdown on retrieval. |
1043 | |
1044 | =head1 BUGS |
1045 | |
197b90bc |
1046 | You can't store GLOB, FORMLINE, etc.... If you can define semantics |
1047 | for those operations, feel free to enhance Storable so that it can |
1048 | deal with them. |
7a6a85bf |
1049 | |
1050 | The store functions will C<croak> if they run into such references |
1051 | unless you set C<$Storable::forgive_me> to some C<TRUE> value. In that |
1052 | case, the fatal message is turned in a warning and some |
1053 | meaningless string is stored instead. |
1054 | |
1055 | Setting C<$Storable::canonical> may not yield frozen strings that |
1056 | compare equal due to possible stringification of numbers. When the |
f062ea6c |
1057 | string version of a scalar exists, it is the form stored; therefore, |
7a6a85bf |
1058 | if you happen to use your numbers as strings between two freezing |
1059 | operations on the same data structures, you will get different |
1060 | results. |
1061 | |
dd19458b |
1062 | When storing doubles in network order, their value is stored as text. |
1063 | However, you should also not expect non-numeric floating-point values |
1064 | such as infinity and "not a number" to pass successfully through a |
1065 | nstore()/retrieve() pair. |
1066 | |
1067 | As Storable neither knows nor cares about character sets (although it |
1068 | does know that characters may be more than eight bits wide), any difference |
1069 | in the interpretation of character codes between a host and a target |
1070 | system is your problem. In particular, if host and target use different |
1071 | code points to represent the characters used in the text representation |
1072 | of floating-point numbers, you will not be able be able to exchange |
1073 | floating-point data, even with nstore(). |
1074 | |
c261f00e |
1075 | C<Storable::drop_utf8> is a blunt tool. There is no facility either to |
1076 | return B<all> strings as utf8 sequences, or to attempt to convert utf8 |
1077 | data back to 8 bit and C<croak()> if the conversion fails. |
1078 | |
ee0f7aac |
1079 | Prior to Storable 2.01, no distinction was made between signed and |
1080 | unsigned integers on storing. By default Storable prefers to store a |
1081 | scalars string representation (if it has one) so this would only cause |
3c4b39be |
1082 | problems when storing large unsigned integers that had never been converted |
ee0f7aac |
1083 | to string or floating point. In other words values that had been generated |
1084 | by integer operations such as logic ops and then not used in any string or |
1085 | arithmetic context before storing. |
1086 | |
1087 | =head2 64 bit data in perl 5.6.0 and 5.6.1 |
1088 | |
1089 | This section only applies to you if you have existing data written out |
1090 | by Storable 2.02 or earlier on perl 5.6.0 or 5.6.1 on Unix or Linux which |
1091 | has been configured with 64 bit integer support (not the default) |
1092 | If you got a precompiled perl, rather than running Configure to build |
1093 | your own perl from source, then it almost certainly does not affect you, |
1094 | and you can stop reading now (unless you're curious). If you're using perl |
1095 | on Windows it does not affect you. |
1096 | |
1097 | Storable writes a file header which contains the sizes of various C |
1098 | language types for the C compiler that built Storable (when not writing in |
1099 | network order), and will refuse to load files written by a Storable not |
1100 | on the same (or compatible) architecture. This check and a check on |
1101 | machine byteorder is needed because the size of various fields in the file |
1102 | are given by the sizes of the C language types, and so files written on |
1103 | different architectures are incompatible. This is done for increased speed. |
1104 | (When writing in network order, all fields are written out as standard |
1105 | lengths, which allows full interworking, but takes longer to read and write) |
1106 | |
1107 | Perl 5.6.x introduced the ability to optional configure the perl interpreter |
1108 | to use C's C<long long> type to allow scalars to store 64 bit integers on 32 |
1109 | bit systems. However, due to the way the Perl configuration system |
1110 | generated the C configuration files on non-Windows platforms, and the way |
1111 | Storable generates its header, nothing in the Storable file header reflected |
1112 | whether the perl writing was using 32 or 64 bit integers, despite the fact |
1113 | that Storable was storing some data differently in the file. Hence Storable |
1114 | running on perl with 64 bit integers will read the header from a file |
1115 | written by a 32 bit perl, not realise that the data is actually in a subtly |
1116 | incompatible format, and then go horribly wrong (possibly crashing) if it |
1117 | encountered a stored integer. This is a design failure. |
1118 | |
1119 | Storable has now been changed to write out and read in a file header with |
1120 | information about the size of integers. It's impossible to detect whether |
1121 | an old file being read in was written with 32 or 64 bit integers (they have |
1122 | the same header) so it's impossible to automatically switch to a correct |
1123 | backwards compatibility mode. Hence this Storable defaults to the new, |
1124 | correct behaviour. |
1125 | |
1126 | What this means is that if you have data written by Storable 1.x running |
1127 | on perl 5.6.0 or 5.6.1 configured with 64 bit integers on Unix or Linux |
1128 | then by default this Storable will refuse to read it, giving the error |
1129 | I<Byte order is not compatible>. If you have such data then you you |
1130 | should set C<$Storable::interwork_56_64bit> to a true value to make this |
1131 | Storable read and write files with the old header. You should also |
1132 | migrate your data, or any older perl you are communicating with, to this |
1133 | current version of Storable. |
1134 | |
1135 | If you don't have data written with specific configuration of perl described |
1136 | above, then you do not and should not do anything. Don't set the flag - |
1137 | not only will Storable on an identically configured perl refuse to load them, |
1138 | but Storable a differently configured perl will load them believing them |
1139 | to be correct for it, and then may well fail or crash part way through |
1140 | reading them. |
1141 | |
7a6a85bf |
1142 | =head1 CREDITS |
1143 | |
1144 | Thank you to (in chronological order): |
1145 | |
1146 | Jarkko Hietaniemi <jhi@iki.fi> |
1147 | Ulrich Pfeifer <pfeifer@charly.informatik.uni-dortmund.de> |
1148 | Benjamin A. Holzman <bah@ecnvantage.com> |
1149 | Andrew Ford <A.Ford@ford-mason.co.uk> |
1150 | Gisle Aas <gisle@aas.no> |
1151 | Jeff Gresham <gresham_jeffrey@jpmorgan.com> |
1152 | Murray Nesbitt <murray@activestate.com> |
1153 | Marc Lehmann <pcg@opengroup.org> |
9e21b3d0 |
1154 | Justin Banks <justinb@wamnet.com> |
1155 | Jarkko Hietaniemi <jhi@iki.fi> (AGAIN, as perl 5.7.0 Pumpkin!) |
dd19458b |
1156 | Salvador Ortiz Garcia <sog@msg.com.mx> |
1157 | Dominic Dunlop <domo@computer.org> |
1158 | Erik Haugan <erik@solbors.no> |
7a6a85bf |
1159 | |
1160 | for their bug reports, suggestions and contributions. |
1161 | |
1162 | Benjamin Holzman contributed the tied variable support, Andrew Ford |
1163 | contributed the canonical order for hashes, and Gisle Aas fixed |
f062ea6c |
1164 | a few misunderstandings of mine regarding the perl internals, |
7a6a85bf |
1165 | and optimized the emission of "tags" in the output streams by |
1166 | simply counting the objects instead of tagging them (leading to |
1167 | a binary incompatibility for the Storable image starting at version |
f062ea6c |
1168 | 0.6--older images are, of course, still properly understood). |
7a6a85bf |
1169 | Murray Nesbitt made Storable thread-safe. Marc Lehmann added overloading |
f062ea6c |
1170 | and references to tied items support. |
7a6a85bf |
1171 | |
7a6a85bf |
1172 | =head1 AUTHOR |
1173 | |
0ba8809e |
1174 | Storable was written by Raphael Manfredi F<E<lt>Raphael_Manfredi@pobox.comE<gt>> |
775ecd75 |
1175 | Maintenance is now done by the perl5-porters F<E<lt>perl5-porters@perl.orgE<gt>> |
0ba8809e |
1176 | |
1177 | Please e-mail us with problems, bug fixes, comments and complaints, |
1178 | although if you have complements you should send them to Raphael. |
1179 | Please don't e-mail Raphael with problems, as he no longer works on |
1180 | Storable, and your message will be delayed while he forwards it to us. |
7a6a85bf |
1181 | |
1182 | =head1 SEE ALSO |
1183 | |
c261f00e |
1184 | L<Clone>. |
7a6a85bf |
1185 | |
1186 | =cut |