Profile of /usr/local/lib/perl5/5.10.1/darwin-2level/Storable.pm

← Index
NYTProf Performance Profile «block view•line view•sub view»
For 01.HTTP.t
Run on Tue May 4 15:25:55 2010
Reported on Tue May 4 15:26:24 2010

File | /usr/local/lib/perl5/5.10.1/darwin-2level/Storable.pm
Statements Executed | 28
Statement Execution Time | 483µs

Subroutines — ordered by exclusive time
Calls | P | F | Exclusive Time | Inclusive Time | Subroutine
--- | --- | --- | --- | --- | ---
1 | 1 | 1 | 1.25ms | 11.7ms | Storable::::BEGIN@23Storable::BEGIN@23
3 | 1 | 2 | 297µs | 297µs | Storable::::dcloneStorable::dclone (xsub)
1 | 1 | 2 | 85µs | 85µs | Storable::::bootstrapStorable::bootstrap (xsub)
1 | 1 | 1 | 28µs | 960µs | Storable::::BEGIN@22Storable::BEGIN@22
1 | 1 | 1 | 8µs | 121µs | Storable::::BEGIN@44Storable::BEGIN@44
1 | 1 | 1 | 7µs | 47µs | Storable::::BEGIN@24Storable::BEGIN@24
0 | 0 | 0 | 0s | 0s | Storable::::CLONEStorable::CLONE
0 | 0 | 0 | 0s | 0s | Storable::::retrieve_fdStorable::retrieve_fd

Call graph for these subroutines as a Graphviz dot language file.

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