archives.html 19.4 KB

Edit Raw Blame History

<!doctype HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<link rel="stylesheet" type="text/css" href="../../../boost.css">
<link rel="stylesheet" type="text/css" href="style.css">
<title>Serialization - Archives</title>
</head>
<body link="#0000ff" vlink="#800080">
<table border="0" cellpadding="7" cellspacing="0" width="100%" summary="header">
  <tr>
    <td valign="top" width="300">
      <h3><a href="../../../index.htm"><img height="86" width="277" alt="C++ Boost" src="../../../boost.png" border="0"></a></h3>
    </td>
    <td valign="top">
      <h1 align="center">Serialization</h1>
      <h2 align="center">Archive Concepts</h2>
    </td>
  </tr>
</table>
<hr>
<dl class="page-index">
  <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>
<h4>Notation</h4>
In the following descriptions
<ul>
  <li><code>SA</code> is an type modeling the <a href="#saving_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><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><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
corresponding 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 that is equivalent to the original.
The notion of equivalence is defined by the implementations of the pair of archives and the
way the data are rendered <a href="serialization.html">serializable</a>.
<p>
<h4>Valid Expressions</h4>
<dl>
  <dt><h4><code>
    SA::is_saving
  </code></h4></dt>
  <dd>
    Returns the Boost MPL Integral Constant type boost::mpl::bool_&lt;true&gt;
  </dd>
  <dt><h4><code>
    SA::is_loading
  </code></h4></dt>
  <dd>
    Returns the Boost MPL Integral Constant type boost::mpl::bool_&lt;false&gt;
  </dd>
  <dt><h4><code>
    sa &lt;&lt; x
    <br>
    sa &amp; x
  </code></h4></dt>
  <dd>
    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>
    sa.save_binary(u, count)
  </code></h4></dt>
  <dd>
    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>
    sa.get_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>
  <dt><h4><code>
    sa.get_helper&lt;Helper&gt;(void * const helper_instance_id = 0)
  </code></h4></dt>
  <dd>
    See <code>la.get_helper&lt;Helper&gt;(void * const helper_instance_id = 0)</code>
    below.
  </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.get_library_version()
  </code></h4></dt>
  <dd>
    Returns an unsigned integer containing the version number of the serialization
    library that created the archive. 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>
  <dt><h4><code>
    la.get_helper&lt;Helper&gt;(void * const helper_instance_id)
  </code></h4></dt>
  <dd>
    Some otherwise unserializable types can be made serializable by inclusion of
    a helper object.  The iconic example of this is shared_ptr which needs this
    helper object to keep track of previously loaded shared_ptr instances so they
    can be "matched up" with subsequently loaded ones.
    The first time <code  style="white-space: normal">la.get_helper&lt;Helper&gt;(void * const helper_instance_id)</code>
    is invoked for a given helper_instance_id, <code  style="white-space: normal">Helper</code>, a default-constructed
    <code style="white-space: normal">Helper</code> object is created, attached to
    <code  style="white-space: normal">la</code> and a reference to it is returned. Subsequent
    invocations of <code style="white-space: normal">la.get_helper&lt;Helper&gt;(void * const helper_instance_id)</code> with the same id value return
    a reference to the formerly constructed object. All objects created in this manner are
    destroyed  upon <code style="white-space: normal">la</code> destruction time. The purpose
    of helper objects is discussed in
    <a href="special.html#helpersupport">Special Considerations - Helper Support</a>.
  </dd>
  <dt><h4><code>
    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>
    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 permits 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>
    la.delete_created_pointers()
  </code></h4></dt>
  <dd>
    Deletes all objects created by the loading of pointers.  This can be used to
    avoid memory leaks that might otherwise occur if pointers are being loaded
    and the archive load encounters an exception.
  </dd>
</dl>

There are archives based on text, binary and XML file
formats but all have the above interface.  Given that all archives present
the same public interface, specifcation of serialization is exactly the same
for all archives.  Archive classes have other members not mentioned here.
However they are related to the internal functioning of the library and
are not meant to be called by users of an archive.  Implementation of new
archives is discussed in
<a href="archive_reference.html#implementation">New Archives - Implementation</a>.

<p>
The existence of the <code style="white-space: normal">&lt;&lt;</code>
and <code style="white-space: normal">&gt;&gt;</code> suggests
a relationship between archives and C++ i/o streams. <strong>Archives are not
C++ i/o streams</strong>. All the archives included with this system take a stream
as an argument in the constructor and that stream is used for output or input.
However, this is not a requirement of the serialization functions or the
archive interface. It just turns out that the archives written so far have
found it useful to base their implementation on streams.

<h3><a name="archive_models">Archive Models</a></h3>
This library includes various implementations 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.
An archive is defined by two complementary classes. One is for saving data while the other is for loading it.

To invoke serialization using one of
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</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</a> // saving
<a href="../../../boost/archive/text_wiarchive.hpp">boost::archive::text_wiarchive</a> // loading

// a portable XML archive</a>
<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</a> // saving
<a href="../../../boost/archive/xml_wiarchive.hpp" target="xml_wiarchive_cpp">boost::archive::xml_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</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</a> // saving
<a href="../../../boost/archive/binary_wiarchive.hpp">boost::archive::binary_wiarchive</a> // loading
-->

</code></pre>

All of these archives implement the same interface. Hence, it should suffice to describe only one
of them in detail.  For this purpose we will use the text archive.


<pre><code>
namespace boost {
namespace archive {

enum archive_flags {
    no_header = 1,          // suppress archive header info
    no_codecvt = 2,         // suppress alteration of codecvt facet
    no_xml_tag_checking = 4 // suppress checking of xml tags - igored on saving
};

} // archive
} // boost
</code></pre>

<pre><code>
namespace boost {
namespace archive {

class text_oarchive : ...
{
    ...
public:
    ... // implementation of the <strong>Saving Archive</strong> concept
    text_oarchive(std::ostream & os, unsigned int flags = 0);
    ~text_oarchive();
};

} // archive
} // boost
</code></pre>

<dl>

<dt><h4><code>
text_oarchive(std::ostream & os, unsigned int flags = 0);
</code></h4></dt>
<dd>
Constructs an archive given an open <code style="white-space: normal">stream</code> as
an argument and optional flags. For most applications there will be no need to use flags.
Flags are defined by <code style="white-space: normal">enum archive_flags</code> enumerator.
Multiple flags can be combined with the <code style="white-space: normal">|</code> operator.

By default, archives prepend
output with initial data which helps identify them as archives produced by this system.
This permits a more graceful handling of the case where an attempt is made to load an archive
from an invalid file format. In addition to this, each type of archive might have
its own information.  For example, native binary archives include information about
sizes of native types and endianess to gracefully handle the case where it has been
erroneously assumed that such an archive is portable across platforms.  In some cases,
where this extra overhead might be considered objectionable, it can be suppressed with the
<code style="white-space: normal">no_header</code> flag.
<p>
In some cases, an archive may alter (and later restore)
the codecvt facet of the stream locale.  To suppress this action,
include the <code style="white-space: normal">no_codecvt</code> flag.
<p>
XML archives contain nested tags signifying the start and end of data fields.
These tags are normally checked for agreement with the object name when
data is loaded.  If a mismatch occurs an exception is thrown.  It's possible
that this may not be desired behavior.  To suppress this checking of XML
tags, use <code style="white-space: normal">no_xml_tag_checking</code> flag.
</dd>

<dt><h4><code>
~text_oarchive();
</code></h4></dt>
<dd>
Destructor for an archive.  This should be called before the stream is
closed.  It restores any altered stream facets to their state before the
archive was opened.
</dd>

</dl>

<pre><code>
namespace boost {
namespace archive {

class text_iarchive : ...
{
    ...
public:
    ... // implementation of the <strong>Loading Archive</strong> concept
    text_iarchive(std::istream & is, unsigned int flags = 0);
    ~text_iarchive();
};

} //namespace archive
) //namespace boost

</code></pre>

<dl>

<dt><h4><code>
text_iarchive(std::istream & is, unsigned int flags = 0);
</code></h4></dt>
<dd>
Contructs an archive given an open <code style="white-space: normal">stream</code> as
an argument and optional flags. If flags are used, they should be the same
as those used when the archive was created. Function and usage of flags is described
above.
</dd>

<dt><h4><code>
~text_iarchive();
</code></h4></dt>
<dd>
Destructor for an archive.  This should be called before the stream is
closed.  It restores any altered stream facets to their state before the
the archive was opened.
</dd>
</dl>
<p>
The <code style="white-space: normal">binary_oarchive</code> and
<code style="white-space: normal">binary_iarchive</code> classes are
implemented in terms of the more basic
<code style="white-space: normal">std::streambuf</code>.  So, in addition
to the common class interface described above, they include the following
constructors:
<dl>
<dt><h4><code>
binary_oarchive(std::streambuf & bsb, unsigned int flags = 0);
</code></h4></dt>
and
<dt><h4><code>
binary_iarchive(std::streambuf & bsb, unsigned int flags = 0);
</code></h4></dt>
</dl>

<h3><a name="exceptions">Exceptions</h3>
All of the archive classes included may throw exceptions.  The list of exceptions that might
be thrown can be found in section <a target="detail" href="exceptions.html">Archive Exceptions</a>
of this documentation.

<h3><a name="charactersets">Character Sets</h3>
This library includes two archive classes for XML. The wide character
version (<code style="white-space: normal">xml_w?archive</code>) renders its output as UTF-8 which can
handle any wide character without loss of information.
<code style="white-space: normal">std::string</code> data is converted from multi-byte format to wide
character format using the current <code style="white-space: normal">
locale</code>.  Hence this version should give a fair rendering of all
C++ data for all cases.  This could result in some unexpected behavior.
Suppose an <code style="white-space: normal">std::string</code>
is created with the <code style="white-space: normal">locale</code> character
set to hebrew characters.  On output this is converted to wide characters.
On input however, there could be a problem if the <code style="white-space: normal">locale</code> is
not set the same as when the archive is created.
<p>
The normal character version (<code style="white-space: normal">xml_?archive</code>) renders
<code style="white-space: normal">std::string</code> output without any conversion.  Though this may work
fine for serialization,  it may create difficulties if the XML archive is used
for some other purpose.
<hr>
<p><i>&copy; Copyright <a href="http://www.rrsd.com">Robert Ramey</a> 2002-2004.
Distributed under the Boost Software License, Version 1.0. (See
accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
</i></p>
</body>
</html>