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