123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458 |
- <!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_<true>
- </dd>
- <dt><h4><code>
- SA::is_loading
- </code></h4></dt>
- <dd>
- Returns the Boost MPL Integral Constant type boost::mpl::bool_<false>
- </dd>
- <dt><h4><code>
- sa << x
- <br>
- sa & 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<T>()
- <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<Helper>(void * const helper_instance_id = 0)
- </code></h4></dt>
- <dd>
- See <code>la.get_helper<Helper>(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_<false>
- </dd>
- <dt><h4><code>
- LA::is_loading
- </code></h4></dt>
- <dd>
- Returns the Boost MPL Integral Constant type boost::mpl::bool_<true>
- </dd>
- <dt><h4><code>
- la >> x
- <br>
- la & 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<T>()
- <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<Helper>(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<Helper>(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<Helper>(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"><<</code>
- and <code style="white-space: normal">>></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>© 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>
|