| File | /usr/local/lib/perl5/5.10.1/darwin-2level/Storable.pm |
| Statements Executed | 28 |
| Statement Execution Time | 483µs |
| Calls | P | F | Exclusive Time |
Inclusive Time |
Subroutine |
|---|---|---|---|---|---|
| 1 | 1 | 1 | 1.25ms | 11.7ms | Storable::BEGIN@23 |
| 3 | 1 | 2 | 297µs | 297µs | Storable::dclone (xsub) |
| 1 | 1 | 2 | 85µs | 85µs | Storable::bootstrap (xsub) |
| 1 | 1 | 1 | 28µs | 960µs | Storable::BEGIN@22 |
| 1 | 1 | 1 | 8µs | 121µs | Storable::BEGIN@44 |
| 1 | 1 | 1 | 7µs | 47µs | Storable::BEGIN@24 |
| 0 | 0 | 0 | 0s | 0s | Storable::CLONE |
| 0 | 0 | 0 | 0s | 0s | Storable::retrieve_fd |
| 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 # 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 # 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 # 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 | ||||
| 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 | |||||
# 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 |