storable.html

来自「perl教程」· HTML 代码 · 共 740 行 · 第 1/3 页

<?xml version="1.0" ?>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<!-- saved from url=(0017)http://localhost/ -->
<script language="JavaScript" src="../displayToc.js"></script>
<script language="JavaScript" src="../tocParas.js"></script>
<script language="JavaScript" src="../tocTab.js"></script>
<link rel="stylesheet" type="text/css" href="../scineplex.css">
<title>Storable - persistence for Perl data structures</title>
<link rel="stylesheet" href="../Active.css" type="text/css" />
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<link rev="made" href="mailto:" />
</head>

<body>

<script>writelinks('__top__',1);</script>
<h1><a>Storable - persistence for Perl data structures</a></h1>
<p><a name="__index__"></a></p>

<!-- INDEX BEGIN -->

<ul>

	<li><a href="#name">NAME</a></li>
	<li><a href="#synopsis">SYNOPSIS</a></li>
	<li><a href="#description">DESCRIPTION</a></li>
	<li><a href="#memory_store">MEMORY STORE</a></li>
	<li><a href="#advisory_locking">ADVISORY LOCKING</a></li>
	<li><a href="#speed">SPEED</a></li>
	<li><a href="#canonical_representation">CANONICAL REPRESENTATION</a></li>
	<li><a href="#code_references">CODE REFERENCES</a></li>
	<li><a href="#forward_compatibility">FORWARD COMPATIBILITY</a></li>
	<li><a href="#error_reporting">ERROR REPORTING</a></li>
	<li><a href="#wizards_only">WIZARDS ONLY</a></li>
	<ul>

		<li><a href="#hooks">Hooks</a></li>
		<li><a href="#predicates">Predicates</a></li>
		<li><a href="#recursion">Recursion</a></li>
		<li><a href="#deep_cloning">Deep Cloning</a></li>
	</ul>

	<li><a href="#storable_magic">Storable magic</a></li>
	<li><a href="#examples">EXAMPLES</a></li>
	<li><a href="#warning">WARNING</a></li>
	<li><a href="#bugs">BUGS</a></li>
	<ul>

		<li><a href="#64_bit_data_in_perl_5_6_0_and_5_6_1">64 bit data in perl 5.6.0 and 5.6.1</a></li>
	</ul>

	<li><a href="#credits">CREDITS</a></li>
	<li><a href="#author">AUTHOR</a></li>
	<li><a href="#see_also">SEE ALSO</a></li>
</ul>
<!-- INDEX END -->

<hr />
<p>
</p>
<h1><a name="name">NAME</a></h1>
<p>Storable - persistence for Perl data structures</p>
<p>
</p>
<hr />
<h1><a name="synopsis">SYNOPSIS</a></h1>
<pre>
 <span class="keyword">use</span> <span class="variable">Storable</span><span class="operator">;</span>
 <span class="variable">store</span> <span class="operator">\</span><span class="variable">%table</span><span class="operator">,</span> <span class="string">'file'</span><span class="operator">;</span>
 <span class="variable">$hashref</span> <span class="operator">=</span> <span class="variable">retrieve</span><span class="operator">(</span><span class="string">'file'</span><span class="operator">);</span>
</pre>
<pre>
 <span class="keyword">use</span> <span class="variable">Storable</span> <span class="string">qw(nstore store_fd nstore_fd freeze thaw dclone)</span><span class="operator">;</span>
</pre>
<pre>
 <span class="comment"># Network order</span>
 <span class="variable">nstore</span> <span class="operator">\</span><span class="variable">%table</span><span class="operator">,</span> <span class="string">'file'</span><span class="operator">;</span>
 <span class="variable">$hashref</span> <span class="operator">=</span> <span class="variable">retrieve</span><span class="operator">(</span><span class="string">'file'</span><span class="operator">);</span>   <span class="comment"># There is NO nretrieve()</span>
</pre>
<pre>
 <span class="comment"># Storing to and retrieving from an already opened file</span>
 <span class="variable">store_fd</span> <span class="operator">\</span><span class="variable">@array</span><span class="operator">,</span> <span class="operator">\</span><span class="variable">*STDOUT</span><span class="operator">;</span>
 <span class="variable">nstore_fd</span> <span class="operator">\</span><span class="variable">%table</span><span class="operator">,</span> <span class="operator">\</span><span class="variable">*STDOUT</span><span class="operator">;</span>
 <span class="variable">$aryref</span> <span class="operator">=</span> <span class="variable">fd_retrieve</span><span class="operator">(\</span><span class="variable">*SOCKET</span><span class="operator">);</span>
 <span class="variable">$hashref</span> <span class="operator">=</span> <span class="variable">fd_retrieve</span><span class="operator">(\</span><span class="variable">*SOCKET</span><span class="operator">);</span>
</pre>
<pre>
 <span class="comment"># Serializing to memory</span>
 <span class="variable">$serialized</span> <span class="operator">=</span> <span class="variable">freeze</span> <span class="operator">\</span><span class="variable">%table</span><span class="operator">;</span>
 <span class="variable">%table_clone</span> <span class="operator">=</span> <span class="variable">%</span><span class="operator">{</span> <span class="variable">thaw</span><span class="operator">(</span><span class="variable">$serialized</span><span class="operator">)</span> <span class="operator">}</span><span class="operator">;</span>
</pre>
<pre>
 <span class="comment"># Deep (recursive) cloning</span>
 <span class="variable">$cloneref</span> <span class="operator">=</span> <span class="variable">dclone</span><span class="operator">(</span><span class="variable">$ref</span><span class="operator">);</span>
</pre>
<pre>
 <span class="comment"># Advisory locking</span>
 <span class="keyword">use</span> <span class="variable">Storable</span> <span class="string">qw(lock_store lock_nstore lock_retrieve)</span>
 <span class="variable">lock_store</span> <span class="operator">\</span><span class="variable">%table</span><span class="operator">,</span> <span class="string">'file'</span><span class="operator">;</span>
 <span class="variable">lock_nstore</span> <span class="operator">\</span><span class="variable">%table</span><span class="operator">,</span> <span class="string">'file'</span><span class="operator">;</span>
 <span class="variable">$hashref</span> <span class="operator">=</span> <span class="variable">lock_retrieve</span><span class="operator">(</span><span class="string">'file'</span><span class="operator">);</span>
</pre>
<p>
</p>
<hr />
<h1><a name="description">DESCRIPTION</a></h1>
<p>The Storable package brings persistence to your Perl data structures
containing SCALAR, ARRAY, HASH or REF objects, i.e. anything that can be
conveniently stored to disk and retrieved at a later time.</p>
<p>It can be used in the regular procedural way by calling <code>store</code> with
a reference to the object to be stored, along with the file name where
the image should be written.</p>
<p>The routine returns <a href="../lib/Pod/perlfunc.html#item_undef"><code>undef</code></a> for I/O problems or other internal error,
a true value otherwise. Serious errors are propagated as a <a href="../lib/Pod/perlfunc.html#item_die"><code>die</code></a> exception.</p>
<p>To retrieve data stored to disk, use <code>retrieve</code> with a file name.
The objects stored into that file are recreated into memory for you,
and a <em>reference</em> to the root object is returned. In case an I/O error
occurs while reading, <a href="../lib/Pod/perlfunc.html#item_undef"><code>undef</code></a> is returned instead. Other serious
errors are propagated via <a href="../lib/Pod/perlfunc.html#item_die"><code>die</code></a>.</p>
<p>Since storage is performed recursively, you might want to stuff references
to objects that share a lot of common data into a single array or hash
table, and then store that object. That way, when you retrieve back the
whole thing, the objects will continue to share what they originally shared.</p>
<p>At the cost of a slight header overhead, you may store to an already
opened file descriptor using the <code>store_fd</code> routine, and retrieve
from a file via <code>fd_retrieve</code>. Those names aren't imported by default,
so you will have to do that explicitly if you need those routines.
The file descriptor you supply must be already opened, for read
if you're going to retrieve and for write if you wish to store.</p>
<pre>
        <span class="variable">store_fd</span><span class="operator">(\</span><span class="variable">%table</span><span class="operator">,</span> <span class="variable">*STDOUT</span><span class="operator">)</span> <span class="operator">||</span> <span class="keyword">die</span> <span class="string">"can't store to stdout\n"</span><span class="operator">;</span>
        <span class="variable">$hashref</span> <span class="operator">=</span> <span class="variable">fd_retrieve</span><span class="operator">(</span><span class="variable">*STDIN</span><span class="operator">);</span>
</pre>
<p>You can also store data in network order to allow easy sharing across
multiple platforms, or when storing on a socket known to be remotely
connected. The routines to call have an initial <a href="../lib/Pod/perlguts.html#item_n"><code>n</code></a> prefix for <em>network</em>,
as in <code>nstore</code> and <code>nstore_fd</code>. At retrieval time, your data will be
correctly restored so you don't have to know whether you're restoring
from native or network ordered data.  Double values are stored stringified
to ensure portability as well, at the slight risk of loosing some precision
in the last decimals.</p>
<p>When using <code>fd_retrieve</code>, objects are retrieved in sequence, one
object (i.e. one recursive tree) per associated <code>store_fd</code>.</p>
<p>If you're more from the object-oriented camp, you can inherit from
Storable and directly store your objects by invoking <code>store</code> as
a method. The fact that the root of the to-be-stored tree is a
blessed reference (i.e. an object) is special-cased so that the
retrieve does not provide a reference to that object but rather the
blessed object reference itself. (Otherwise, you'd get a reference
to that blessed object).</p>
<p>
</p>
<hr />
<h1><a name="memory_store">MEMORY STORE</a></h1>
<p>The Storable engine can also store data into a Perl scalar instead, to
later retrieve them. This is mainly used to freeze a complex structure in
some safe compact memory place (where it can possibly be sent to another
process via some IPC, since freezing the structure also serializes it in
effect). Later on, and maybe somewhere else, you can thaw the Perl scalar
out and recreate the original complex structure in memory.</p>
<p>Surprisingly, the routines to be called are named <code>freeze</code> and <code>thaw</code>.
If you wish to send out the frozen scalar to another machine, use
<code>nfreeze</code> instead to get a portable image.</p>
<p>Note that freezing an object structure and immediately thawing it
actually achieves a deep cloning of that structure:</p>
<pre>
    dclone(.) = thaw(freeze(.))</pre>
<p>Storable provides you with a <code>dclone</code> interface which does not create
that intermediary scalar but instead freezes the structure in some
internal memory space and then immediately thaws it out.</p>
<p>
</p>
<hr />
<h1><a name="advisory_locking">ADVISORY LOCKING</a></h1>
<p>The <code>lock_store</code> and <code>lock_nstore</code> routine are equivalent to
<code>store</code> and <code>nstore</code>, except that they get an exclusive lock on
the file before writing.  Likewise, <code>lock_retrieve</code> does the same
as <code>retrieve</code>, but also gets a shared lock on the file before reading.</p>
<p>As with any advisory locking scheme, the protection only works if you
systematically use <code>lock_store</code> and <code>lock_retrieve</code>.  If one side of
your application uses <code>store</code> whilst the other uses <code>lock_retrieve</code>,
you will get no protection at all.</p>
<p>The internal advisory locking is implemented using Perl's <a href="../lib/Pod/perlfunc.html#item_flock"><code>flock()</code></a>
routine.  If your system does not support any form of flock(), or if
you share your files across NFS, you might wish to use other forms
of locking by using modules such as LockFile::Simple which lock a
file using a filesystem entry, instead of locking the file descriptor.</p>
<p>
</p>
<hr />
<h1><a name="speed">SPEED</a></h1>
<p>The heart of Storable is written in C for decent speed. Extra low-level
optimizations have been made when manipulating perl internals, to
sacrifice encapsulation for the benefit of greater speed.</p>
<p>
</p>
<hr />
<h1><a name="canonical_representation">CANONICAL REPRESENTATION</a></h1>
<p>Normally, Storable stores elements of hashes in the order they are
stored internally by Perl, i.e. pseudo-randomly.  If you set
<code>$Storable::canonical</code> to some <code>TRUE</code> value, Storable will store
hashes with the elements sorted by their key.  This allows you to
compare data structures by comparing their frozen representations (or
even the compressed frozen representations), which can be useful for
creating lookup tables for complicated queries.</p>
<p>Canonical order does not imply network order; those are two orthogonal
settings.</p>
<p>
</p>
<hr />
<h1><a name="code_references">CODE REFERENCES</a></h1>
<p>Since Storable version 2.05, CODE references may be serialized with
the help of <a href="../lib/B/Deparse.html">the B::Deparse manpage</a>. To enable this feature, set
<code>$Storable::Deparse</code> to a true value. To enable deserializazion,
<code>$Storable::Eval</code> should be set to a true value. Be aware that
deserialization is done through <a href="../lib/Pod/perlfunc.html#item_eval"><code>eval</code></a>, which is dangerous if the
Storable file contains malicious data. You can set <code>$Storable::Eval</code>
to a subroutine reference which would be used instead of <a href="../lib/Pod/perlfunc.html#item_eval"><code>eval</code></a>. See
below for an example using a <a href="../lib/Safe.html">the Safe manpage</a> compartment for deserialization
of CODE references.</p>
<p>If <code>$Storable::Deparse</code> and/or <code>$Storable::Eval</code> are set to false
values, then the value of <code>$Storable::forgive_me</code> (see below) is
respected while serializing and deserializing.</p>
<p>
</p>
<hr />
<h1><a name="forward_compatibility">FORWARD COMPATIBILITY</a></h1>
<p>This release of Storable can be used on a newer version of Perl to
serialize data which is not supported by earlier Perls.  By default,
Storable will attempt to do the right thing, by <code>croak()</code>ing if it
encounters data that it cannot deserialize.  However, the defaults
can be changed as follows:</p>
<dl>
<dt><strong><a name="item_utf8_data">utf8 data</a></strong>

<dd>
<p>Perl 5.6 added support for Unicode characters with code points &gt; 255,
and Perl 5.8 has full support for Unicode characters in hash keys.
Perl internally encodes strings with these characters using utf8, and
Storable serializes them as utf8.  By default, if an older version of
Perl encounters a utf8 value it cannot represent, it will <code>croak()</code>.
To change this behaviour so that Storable deserializes utf8 encoded
values as the string of bytes (effectively dropping the <em>is_utf8</em> flag)
set <code>$Storable::drop_utf8</code> to some <code>TRUE</code> value.  This is a form of
data loss, because with <code>$drop_utf8</code> true, it becomes impossible to tell