MAN page from Mandrake Other perl-Storable-0.6@3-bin-1-MacOS-1.i386.rpm

Storable

Section: User Contributed Perl Documentation (3)
Updated: perl 5.004, patch 04
Index

NAME

Storable - persistency for perl data structures

SYNOPSIS

 use Storable; store \%table, 'file'; $hashref = retrieve('file');

 use Storable qw(nstore store_fd nstore_fd freeze thaw dclone);

 # Network order nstore \%table, 'file'; $hashref = retrieve('file');   # There is NO nretrieve()

 # Storing to and retrieving from an already opened file store_fd \@array, \*STDOUT; nstore_fd \%table, \*STDOUT; $aryref = retrieve_fd(\*SOCKET); $hashref = retrieve_fd(\*SOCKET);

 # Serializing to memory $serialized = freeze \%table; %table_clone = %{ thaw($serialized) };

 # Deep (recursive) cloning $cloneref = dclone($ref);

DESCRIPTION

The Storable package brings persistency to your perl data structurescontaining SCALAR, ARRAY, HASH or REF objects, i.e. anything that can beconvenientely stored to disk and retrieved at a later time.

It can be used in the regular procedural way by calling store witha reference to the object to be stored, along with the file name wherethe image should be written.The routine returns undef for I/O problems or other internal error,a true value otherwise. Serious errors are propagated as a die exception.

To retrieve data stored to disk, use retrieve with a file name,and the objects stored into that file are recreated into memory for you,a reference to the root object being returned. In case an I/O erroroccurs while reading, undef is returned instead. Other seriouserrors are propagated via die.

Since storage is performed recursively, you might want to stuff referencesto objects that share a lot of common data into a single array or hashtable, and then store that object. That way, when you retrieve back thewhole thing, the objects will continue to share what they originally shared.

At the cost of a slight header overhead, you may store to an alreadyopened file descriptor using the store_fd routine, and retrievefrom a file via retrieve_fd. Those names aren't imported by default,so you will have to do that explicitely if you need those routines.The file descriptor you supply must be already opened, for readif you're going to retrieve and for write if you wish to store.

        store_fd(\%table, *STDOUT) || die "can't store to stdout\n";        $hashref = retrieve_fd(*STDIN);

You can also store data in network order to allow easy sharing acrossmultiple platforms, or when storing on a socket known to be remotelyconnected. The routines to call have an initial n prefix for network,as in nstore and nstore_fd. At retrieval time, your data will becorrectly restored so you don't have to know whether you're restoringfrom native or network ordered data.

When using retrieve_fd, objects are retrieved in sequence, oneobject (i.e. one recursive tree) per associated store_fd.

If you're more from the object-oriented camp, you can inherit fromStorable and directly store your objects by invoking store asa method. The fact that the root of the to-be-stored tree is ablessed reference (i.e. an object) is special-cased so that theretrieve does not provide a reference to that object but rather theblessed object reference itself. (Otherwise, you'd get a referenceto that blessed object).

MEMORY STORE

The Storable engine can also store data into a Perl scalar instead, tolater retrieve them. This is mainly used to freeze a complex structure insome safe compact memory place (where it can possibly be sent to anotherprocess via some IPC, since freezing the structure also serializes it ineffect). Later on, and maybe somewhere else, you can thaw the Perl scalarout and recreate the original complex structure in memory.

Surprisingly, the routines to be called are named freeze and thaw.If you wish to send out the frozen scalar to another machine, usenfreeze instead to get a portable image.

Note that freezing an object structure and immediately thawing itactually achieves a deep cloning of that structure. Storable providesyou with a dclone interface which does not create that intermediaryscalar but instead freezes the structure in some internal memory spaceand then immediatly thaws it out.

SPEED

The heart of Storable is written in C for decent speed. Extra low-leveloptimization have been made when manipulating perl internals, tosacrifice encapsulation for the benefit of a greater speed.

Storage is now slightly slower than retrieval since the former has toalso store data in a hash table to keep track of which objectshave been stored already, whilst the latter uses an array instead ofa hash table.

On my HP 9000/712 machine running HPUX 9.03 and with perl 5.004, I canstore 0.85 Mbyte/s and I can retrieve at 0.90 Mbytes/s, approximatively(CPU + system time).This was measured with Benchmark and the Magic: The Gatheringdatabase from Tom Christiansen (1.6 Mbytes on disk).

CANONICAL REPRESENTATION

Normally Storable stores elements of hashes in the order they arestored internally by Perl, i.e. pseudo-randomly. If you set$Storable::canonical to some TRUE value, Storable will storehashes with the elements sorted by their key. This allows you tocompare data structures by comparing their frozen representations (oreven the compressed frozen representations), which can be useful forcreating lookup tables for complicated queries.

Canonical order does not imply network order, those are two orthogonalsettings.

EXAMPLES

Here are some code samples showing a possible usage of Storable:

        use Storable qw(store retrieve freeze thaw dclone);

        %color = ('Blue' => 0.1, 'Red' => 0.8, 'Black' => 0, 'White' => 1);

        store(\%color, '/tmp/colors') or die "Can't store %a in /tmp/colors!\n";

        $colref = retrieve('/tmp/colors');        die "Unable to retrieve from /tmp/colors!\n" unless defined $colref;        printf "Blue is still %lf\n", $colref->{'Blue'};

        $colref2 = dclone(\%color);

        $str = freeze(\%color);        printf "Serialization of %%color is %d bytes long.\n", length($str);        $colref3 = thaw($str);

which prints (on my machine):

        Blue is still 0.100000        Serialization of %color is 102 bytes long.

WARNING

If you're using references as keys within your hash tables, you're boundto disapointment when retrieving your data. Indeed, Perl stringifiesreferences used as hash table keys. If you later wish to access theitems via another reference stringification (i.e. using the samereference that was used for the key originally to record the value intothe hash table), it will work because both references stringify to thesame string.

It won't work across a store and retrieve operations however, becausethe addresses in the retrieved objects, which are part of the stringifiedreferences, will probably differ from the original addresses. Thetopology of your structure is preserved, but not hidden semanticslike those.

On platforms where it matters, be sure to call binmode() on thedescriptors that you pass to Storable functions.

Storing data canonically that contains large hashes can besignificantly slower than storing the same data normally, astemprorary arrays to hold the keys for each hash have to be allocated,populated, sorted and freed. Some tests have shown a halving of thespeed of storing -- the exact penalty will depend on the complexity ofyour data. There is no slowdown on retrieval.

BUGS

You can't store GLOB, CODE, FORMLINE, etc... If you can definesemantics for those operations, feel free to enhance Storable so thatit can deal with them.

The store functions will croak if they run into such referencesunless you set $Storable::forgive_me to some TRUE value. In thatcase, the fatal message is turned in a warning and somemeaningless string is stored instead.

Setting $Storable::canonical may not yield frozen strings thatcompare equal due to possible stringification of numbers. When thestring version of a scalar exists, it is the form stored, thereforeif you happen to use your numbers as strings between two freezingoperations on the same data structures, you will get differentresults.

Due to the aforementionned optimizations, Storable is at the mercyof perl's internal redesign or structure changes. If that bothersyou, you can try convincing Larry that what is used in Storableshould be documented and consistently kept in future revisions.

CREDITS

Thank you to (in chronological order):

        Jarkko Hietaniemi <jhiAATTiki.fi>        Ulrich Pfeifer <pfeiferAATTcharly.informatik.uni-dortmund.de>        Benjamin A. Holzman <benjamin.a.holzmanAATTbender.com>        Andrew Ford <A.FordAATTford-mason.co.uk>        Gisle Aas <gisleAATTaas.no>        Jeff Gresham <gresham_jeffreyAATTjpmorgan.com>

for their bug reports, suggestions and contributions.

Benjamin Holzman contributed the tied variable support, Andrew Fordcontributed the canonical order for hashes, and Gisle Aas fixeda few misunderstandings of mine regarding the Perl internals,and optimized the emission of ``tags'' in the output streams bysimply counting the objects instead of tagging them (leading toa binary incompatibility for the Storable image starting at version0.6---older images are of course still properly understood).

AUTHOR

Raphael Manfredi <Raphael_ManfrediAATTgrenoble.hp.com>

This document was created byman2html,using the manual pages.