boost/serialization
2
0
Fork 0
mirror of https://github.com/boostorg/serialization.git synced 2026-01-28 07:32:10 +00:00
Code Issues Projects Releases Wiki Activity

improved archive concept

Browse Source 
[SVN r31086]
This commit is contained in:
Robert Ramey
2005-09-23 06:13:57 +00:00
parent 142db7e716
commit 2afb64b2e6
2 changed files with 147 additions and 126 deletions
Download Patch File Download Diff File Expand all files Collapse all files

267
doc/archives.html
View File

@@ -14,79 +14,165 @@
</td>
<td valign="top">
<h1 align="center">Serialization</h1>
<h2 align="center">Archive Concept</h2>
<h2 align="center">Archive Concepts</h2>
</td>
</tr>
</table>
<hr>
<dl class="page-index">
<dt><a href="#saving_interface">Saving</a>
<dt><a href="#loading_interface">Loading</a>
<dt><a href="#saving_interface">Saving Archive Concept</a>
<dt><a href="#loading_interface">Loading Archive Concept</a>
<dt><a href="#archive_models">Models</a>
<dt><a href="#exceptions">Exceptions</a>
<dt><a href="#charactersets">Character Sets</a>
</dl>
There are two Archive concepts. Given a set of C++ data structures consisting
of <a href="serialization.html"><strong>Serializable</strong></a> types</li>, a
Saving Archive will create a sequence of bytes. Given a sequence of bytes
created by a Saving Archive, a Loading Archive will reconstitute the orginal
configuration of C++ data structures.
Both Archive concepts are derived from the more basic concept of Archive.
<p>
<h4>Notation</h4>
In the following descriptions, it is assumed that:
In the following descriptions
<ul>
<li><code>A</code> is an Archive type</li>
<li><code>T</code> is an <a href="serialization.html"><strong>Serializable</strong></a> Type</li>
<li><code>ar</code> is an instance of type A.
<li><code>x</code> is an instance of type T.
<li><code>u</code> is an address.
<li><code>SA</code> is an type modeling the <a href="#loading_interface">Saving Archive Concept</a>
<li><code>sa</code> is an instance of type SA.
<li><code>LA</code> is an type modeling the <a href="#loading_interface">Loading Archive Concept</a>
<li><code>la</code> is an instance of type LA.
<li><code>T</code> is an <a href="serialization.html"><strong>Serializable</strong></a> Type
<li><code>x</code> is an instance of type T Type</li>.
<li><code>u,v</code> is a pointer to a an instance of type T
<li><code>count</code> is an instance of a type that can be converted to <code>std::size_t</code>.
</ul>
<h4>Common Type Definitions in all Archives</h4>
<h4><a name="saving_interface">Saving Archive Concept</a></h4>
<h4>Associated Types</h4>
Intuitively, a type modeling this concept will generate a sequence of bytes
correpsonding to an arbitrary set of C++ data structures. Each type modeling the
Saving Archive concept (SA) may be associated with another type modeling the
<a href="#loading_interface">Loading Archive Concept</a>(LA).
This associated type will perform the inverse operation.
That is, given a sequence of bytes generated by SA, it will generate a set of
C++ data structures the is equivalent to the original.
The notion of equivalence is defined by the implementations of the pair of archives and the
way the data is are rendered <a href="serialization.html">serializable</a>.
<p>
<h4>Valid Expressions</h4>
<dl>
<dt><h4><code>
A::is_saving
SA::is_saving
</code></h4></dt>
<dd>
An integral constant of type <a href="../libs/mpl/doc/refmanual/bool.html">boost::mpl::bool_</a>.
Value is boost::mpl::bool_&lt;true&gt; if the Archive is a Saving Archive (see below)
and boost::mpl::bool_&lt;false&gt; otherwise.
Returns the Boost MPL Integral Constant type boost::mpl::bool_&lt;true&gt;
</dd>
<dt><h4><code>
A::is_loading
SA::is_loading
</code></h4></dt>
<dd>
An integral constant of type <a href="../libs/mpl/doc/refmanual/bool.html">boost::mpl::bool_</a>.
Value is boost::mpl::bool_&lt;true&gt; if the Archive is a Loading Archive (see below)
and boost::mpl::bool_&lt;false&gt; otherwise.
Returns the Boost MPL Integral Constant type boost::mpl::bool_&lt;false&gt;
</dd>
</dl>
<h4>Common Member Functions in all Archives</h4>
<dl>
<dt><h4><code>
ar &amp; x
sa &lt;&lt; x
<br>
sa &amp; x
</code></h4></dt>
<dd>
Returns a reference to <code>ar</code>.
Appends the value of <code>x</code> along with other information to <code>ar</code>.
These expressions must perform exactly the same function. They append the
value of <code style="white-space: normal">x</code> along with other information to <code>sa</code>.
This other information is defined by the implementation of the archive.
Typically this information is that which is required by a corresponding
Loading Archive type to properly restore the value of <code>x</code>.
<p>
Returns a reference to <code>sa</code>.
</dd>
<dt><h4><code>
ar.template register_type&lt;T&gt;();<br>
ar.register_type(u);
sa.save_binary(u, count)
</code></h4></dt>
<dd>
Append information about class T to the archive. This information is used to
construct the correct class when a derived pointer is loaded.
Appends to the archive <code style="white-space: normal">size_t(count)</code> bytes found at
<code style="white-space: normal">u</code>.
</dd>
<dt><h4><code>
sa.register_type&lt;T&gt;()
<br>
sa.register_type(u)
</code></h4></dt>
<dd>
Appends information about class T to the archive. This information is used to
construct the correct class when a derived pointer is loaded by a corresponding
Loading Archive type.
Invocation of this member function is referred to as "class registration".
This is explained in detail in
<a href="special.html#derivedpointers">Special Considerations - Derived Pointers</a>.
The second syntax is included to permit this function to be called on non-conforming
compilers when <code style="white-space: normal">sa</code> is a template argument.
For more information, see <a target="detail" href="implementation.html#tempatesyntax">Template Invocation syntax</a>
</dd>
<dt><h4><code>
ar.library_version()
sa.library_version()
</code></h4></dt>
<dd>
Returns an unsigned integer containing the current version number of the serialization
library. This number will be incremented each time the library is altered in such a
way that serialization could be altered for some type. For example, suppose the type
used for a count of collection members is changed. The code that loads collections
might be conditioned on the library version to make sure that libraries created by
previous versions of the library can still be read.
</dd>
</dl>
<h4><a name="loading_interface">Loading Archive Concept</a></h4>
<h4>Associated Types</h4>
Each model of this concept presumes the
existence of a corresponding type modeling the
<a href="#saving_interface">Saving Archive Concept</a>.
The purpose of an instance of this concept is to convert a sequence of bytes
generated by this corresponding type to a set of C++ data structures
equivalent to the original.
<h4>Valid Expressions</h4>
<dl>
<dt><h4><code>
LA::is_saving
</code></h4></dt>
<dd>
Returns the Boost MPL Integral Constant type boost::mpl::bool_&lt;false&gt;
</dd>
<dt><h4><code>
LA::is_loading
</code></h4></dt>
<dd>
Returns the Boost MPL Integral Constant type boost::mpl::bool_&lt;true&gt;
</dd>
<dt><h4><code>
la &gt;&gt; x
<br>
la &amp; x
</code></h4></dt>
<dd>
These expressions must perform exactly the same function.
Sets <code>x</code> to a value retrieved from <code>la</code>.
<p>
Returns a reference to <code>la</code>.
</dd>
<dt><h4><code>
la.load_binary(u, count)
</code></h4></dt>
<dd>
Retrieves from <code style="white-space: normal">la</code> <code style="white-space: normal">size_t(count)</code> bytes and stores
them in memory starting at <code style="white-space: normal">u</code>.
</dd>
<dt>
<dt><h4><code>
la.register_type&lt;T&gt;()
<br>
la.register_type(u)
</code></h4></dt>
<dd>
Retrieves information about class T from the archive. This information is used to
construct the correct class when loading a pointer to a derived class not
otherwise referred to in the program by name.
Invocation of this member function is referred to as "class registration".
This is explained in detail in
<a href="special.html#derivedpointers">Special Considerations - Derived Pointers</a>.
The second syntax is included to permit this function to be called on non-conforming
compilers when <code style="white-space: normal">la</code> is a template argument.
For more information, see <a target="detail" href="implementation.html#tempatesyntax">Template Invocation syntax</a>
</dd>
<dt><h4><code>
la.library_version()
</code></h4></dt>
<dd>
Returns an unsigned integer containing the version number of the serialization
@@ -96,84 +182,20 @@ In the following descriptions, it is assumed that:
The code that loads collections might be conditioned on the library version to make
sure that libraries created by previous versions of the library can still be read.
</dd>
</dl>
<h4><a name="saving_interface">Saving Archive</a></h4>
A Saving Archive is a refinement of the Archive Concept.
<h4>Notation</h4>
In the following descriptions, it is assumed that:
<ul>
<li><code>ar</code> is an instance of a Saving Archive.
<li><code>x</code> is an instance of a <a href="serialization.html"><strong>Serializable</strong></a> Type</li>.
<li><code>u</code> is an address.
<li><code>count</code> is an integer that can be converted to <code>std::size_t</code>.
</ul>
<h4>Common Member Functions</h4>
<dl>
<dt><h4><code>
ar &lt;&lt; x
</code></h4></dt>
<dd>
Returns a reference to <code>ar</code>.
Appends the value of <code>x</code> along with other information to <code>ar</code>.
</dd>
<dt><h4><code>
ar.save_binary(u, count)
</code></h4></dt>
<dd>
Appends to the archive <code style="white-space: normal">count</code> bytes found at
<code style="white-space: normal">address</code>.
</dd>
</dl>
<h4><a name="loading_interface">Loading Archive</a></h4>
<h4>Notation</h4>
In the following descriptions, it is assumed that:
<ul>
<li><code>ar</code> is an instance of a Loading Archive.
<li><code>x</code> is an instance of a <a href="serialization.html"><strong>Serializable</strong></a> Type</li>.
<li><code>u, v</code> are pointers to any type.
<li><code>count</code> is an integer that can be converted to <code>std::size_t</code>.
</ul>
<h4>Common Member Functions in all Archives</h4>
<dl>
<dt><h4><code>
ar &gt;&gt; x
</code></h4></dt>
<dd>
Returns a reference to <code>ar</code>.
Sets <code>x</code> with a value retrieved from the <code>ar</code>.
</dd>
<dt><h4><code>
ar.load_binary(u, count)
</code></h4></dt>
<dd>
Retrieves from the archive <code style="white-space: normal">count</code> bytes and stores
them in memory starting at <code style="white-space: normal">address</code>.
</dd>
<dt>
<dt><h4><code>
ar.reset_object_address(v, u)
la.reset_object_address(v, u)
</code></h4></dt>
<dd>
Communicates to the archive that the object originally at address u has been
moved to address v.
<p>
In order to facilitate loading of objects through a pointer
and to elminate redundant loading of objects, this system implements object address tracking.
Normally this is done automatically with no action required on the part of the user. However,
there are cases when an object must be de-serialized to a temporary location then
moved to its final destination. This is common in loading collections.
<p>
In such cases, reset_object_address should be invoked to communicate the final address
of the last item loaded. This permits the internal tables to be correctly maintained
in these special cases.
When an object is loaded to a temporary variable and later moved to another location,
This function must be called in order communicate this fact. This is permits the
the archive to properly implement object tracking. Object tracking is required in order
to correctly implement serialization of pointers to instances of derived classes.
</dd>
<dt><h4><code>
ar.delete_created_pointers()
la.delete_created_pointers()
</code></h4></dt>
<dd>
Deletes all objects created by the loading of pointers. This can be used to
@@ -207,7 +229,6 @@ This library includes a various implementation of the Archive concept.
An archive is defined by two complementary classes. One is for saving data while
the other is for loading it.
This library includes a number of archive implementations that are "ready to go" for the
most common requirements. These classes implement the archive concept for differing data formats.
They can be used "as is" or as a basis for developing one's own particular type of archive.
@@ -218,28 +239,28 @@ these archives, one or more of the following header files must be
included in the code module containing the serialization code.
<pre><code>
// a portable text archive</a>
<a href="../../../boost/archive/text_oarchive.hpp" target="text_oarchive_cpp">boost::archive::text_oarchive(ostream &s)</a> // saving
<a href="../../../boost/archive/text_iarchive.hpp" target="text_iarchive_cpp">boost::archive::text_iarchive(istream &s)</a> // loading
<a href="../../../boost/archive/text_oarchive.hpp" target="text_oarchive_cpp">boost::archive::text_oarchive</a> // saving
<a href="../../../boost/archive/text_iarchive.hpp" target="text_iarchive_cpp">boost::archive::text_iarchive</a> // loading
// a portable text archive using a wide character stream</a>
<a href="../../../boost/archive/text_woarchive.hpp">boost::archive::text_woarchive(wostream &s)</a> // saving
<a href="../../../boost/archive/text_wiarchive.hpp">boost::archive::text_wiarchive(wistream &s)</a> // loading
<a href="../../../boost/archive/text_woarchive.hpp">boost::archive::text_woarchive</a> // saving
<a href="../../../boost/archive/text_wiarchive.hpp">boost::archive::text_wiarchive</a> // loading
// a non-portable native binary archive</a>
<a href="../../../boost/archive/binary_oarchive.hpp" target="binary_oarchive_cpp">boost::archive::binary_oarchive(ostream &s)</a> // saving
<a href="../../../boost/archive/binary_iarchive.hpp" target="binary_iarchive_cpp">boost::archive::binary_iarchive(istream &s)</a> // loading
<a href="../../../boost/archive/binary_oarchive.hpp" target="binary_oarchive_cpp">boost::archive::binary_oarchive</a> // saving
<a href="../../../boost/archive/binary_iarchive.hpp" target="binary_iarchive_cpp">boost::archive::binary_iarchive</a> // loading
<!--
// a non-portable native binary archive which use wide character streams
<a href="../../../boost/archive/binary_woarchive.hpp">boost::archive::binary_woarchive(wostream &s)</a> // saving
<a href="../../../boost/archive/binary_wiarchive.hpp">boost::archive::binary_wiarchive(wistream &s)</a> // loading
<a href="../../../boost/archive/binary_woarchive.hpp">boost::archive::binary_woarchive</a> // saving
<a href="../../../boost/archive/binary_wiarchive.hpp">boost::archive::binary_wiarchive</a> // loading
-->
// a portable XML archive</a>
<a href="../../../boost/archive/xml_oarchive.hpp" target="xml_oarchive_cpp">boost::archive::xml_oarchive(ostream &s)</a> // saving
<a href="../../../boost/archive/xml_iarchive.hpp" target="xml_iarchive_cpp">boost::archive::xml_iarchive(istream &s)</a> // loading
<a href="../../../boost/archive/xml_oarchive.hpp" target="xml_oarchive_cpp">boost::archive::xml_oarchive</a> // saving
<a href="../../../boost/archive/xml_iarchive.hpp" target="xml_iarchive_cpp">boost::archive::xml_iarchive</a> // loading
// a portable XML archive which uses wide characters - use for utf-8 output</a>
<a href="../../../boost/archive/xml_woarchive.hpp" target="xml_woarchive_cpp">boost::archive::xml_woarchive(wostream &s)</a> // saving
<a href="../../../boost/archive/xml_wiarchive.hpp" target="xml_wiarchive_cpp">boost::archive::xml_wiarchive(wistream &s)</a> // loading
<a href="../../../boost/archive/xml_woarchive.hpp" target="xml_woarchive_cpp">boost::archive::xml_woarchive</a> // saving
<a href="../../../boost/archive/xml_wiarchive.hpp" target="xml_wiarchive_cpp">boost::archive::xml_wiarchive</a> // loading
</code></pre>
All of these archives implement the same inteface. Hence, it should suffice to describe only one

6
doc/contents.html
View File

@@ -113,10 +113,10 @@ function initialize() {
<dt><img style="display:none" src="plus.gif" id="reference"><a target="detail" href="archives.html">Reference</a></dt>
<dd><div id="reference_detail"><dl class="page-index">
<dt><img style="display:none" src="plus.gif" id="archive_concept"><a target="detail" href="archives.html">Archive Concept</a>
<dt><img style="display:none" src="plus.gif" id="archive_concept"><a target="detail" href="archives.html">Archive Concepts</a>
<dd><div id="archive_concept_detail"><dl class="page-index">
<dt><img style="display:none" src="dot.gif"><a target="detail" href="archives.html#saving_interface">Saving</a>
<dt><img style="display:none" src="dot.gif"><a target="detail" href="archives.html#loading_interface">Loading</a>
<dt><img style="display:none" src="dot.gif"><a target="detail" href="archives.html#saving_interface">Saving Archive Concept</a>
<dt><img style="display:none" src="dot.gif"><a target="detail" href="archives.html#loading_interface">Loading Archive Concept</a>
<dt><img style="display:none" src="dot.gif"><a target="detail" href="archives.html#archive_models">Archive Models</a>
<dt><img style="display:none" src="dot.gif"><a target="detail" href="archives.html#exceptions">Exceptions</a>
<dt><img style="display:none" src="dot.gif"><a target="detail" href="archives.html#charactersets">Character Sets</a>