447 lines
18 KiB
HTML
447 lines
18 KiB
HTML
<!doctype HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
|
<html>
|
|
<!--
|
|
(C) Copyright 2002-4 Robert Ramey - http://www.rrsd.com .
|
|
Use, modification and distribution is subject to 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)
|
|
-->
|
|
<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 - Code Structure</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">Code Structure</h2>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<hr>
|
|
|
|
<dl class="page-index">
|
|
<dt><a href="#userincludes">Files Included by User Programs</a>
|
|
<dl class="page-index">
|
|
<dt><a href="#archiveimplementations">Archive Implementations</a>
|
|
<dt><a href="#serializationdeclarations">Serialization Declarations</a>
|
|
<dt><a href="#serializationimplementations">Serialization Implementations</a>
|
|
</dl>
|
|
<dt><a href="#libraryimplementation">Files Which Implement the Library</a>
|
|
<dl class="page-index">
|
|
<dt><a href="#archivedevelopment">Archive Development</a>
|
|
<dt><a href="#archiveinternals">Archive Internals</a>
|
|
<dt><a href="#codemodules">Archive Library Code Modules</a>
|
|
<dt><a href="#dataflowiterators">Dataflow Iterators</a>
|
|
</dl>
|
|
</dl>
|
|
|
|
This library includes a large number of files. They are organized and classified
|
|
according to the purposes listed in the above index.
|
|
<p>
|
|
<code style="white-space: normal">namespace</code> of classes and templates is synchronized
|
|
with the directory in which the file is found. For example, the class declaration
|
|
<pre><code>
|
|
boost::archive::text_oarchive
|
|
</code></pre>
|
|
is included with the following declaration
|
|
<pre><code>
|
|
#include <boost/archive/text_oarchive.hpp>
|
|
</code></pre>
|
|
|
|
<a name="userincludes">
|
|
<h3>Files Included by User Programs</h3>
|
|
Using this library entails including headers listed in this section.
|
|
It should not be necessary to explictly include any other header files.
|
|
|
|
<a name="archiveimplementations">
|
|
<h4>Archive Implementations</h4>
|
|
These header files contain declarations used to save and restore data to each type
|
|
of archive. Include the archives according to the facilities the code module requires.
|
|
|
|
<dl>
|
|
|
|
<dt><a target="archive_exception" href="../../../boost/archive/archive_exception.hpp">
|
|
boost/archive/archive_exception.hpp
|
|
</a>
|
|
<dd>Exceptions which might be invoked by the library.</dd>
|
|
|
|
<dt><a target="binary_iarchive" href="../../../boost/archive/binary_iarchive.hpp">
|
|
boost/archive/binary_iarchive.hpp
|
|
</a>
|
|
<dd>native binary input archive used for loading.</dd>
|
|
|
|
<dt><a target="binary_oarchive" href="../../../boost/archive/binary_oarchive.hpp">
|
|
boost/archive/binary_oarchive.hpp
|
|
</a>
|
|
<dd>native binary output archive used for saving.</dd>
|
|
|
|
<dt><a target="text_iarchive" href="../../../boost/archive/text_iarchive.hpp">
|
|
boost/archive/text_iarchive.hpp
|
|
</a>
|
|
<dd>text input archive used for loading.</dd>
|
|
|
|
<dt><a target="text_oarchive" href="../../../boost/archive/text_oarchive.hpp">
|
|
boost/archive/text_oarchive.hpp
|
|
</a>
|
|
<dd>text output archive used for saving.</dd>
|
|
|
|
<dt><a target="text_wiarchive" href="../../../boost/archive/text_wiarchive.hpp">
|
|
boost/archive/text_wiarchive.hpp
|
|
</a>
|
|
<dd>wide character text input archive used for loading.</dd>
|
|
|
|
<dt><a target="text_woarchive" href="../../../boost/archive/text_woarchive.hpp">
|
|
boost/archive/text_woarchive.hpp
|
|
</a>
|
|
<dd>wide character text input archive used for saving.</dd>
|
|
|
|
<dt><a target="xml_iarchive" href="../../../boost/archive/xml_iarchive.hpp">
|
|
boost/archive/xml_iarchive.hpp
|
|
</a>
|
|
<dd>xml input archive used for loading.</dd>
|
|
|
|
<dt><a target="text_oarchive" href="../../../boost/archive/xml_oarchive.hpp">
|
|
boost/archive/xml_oarchive.hpp
|
|
</a>
|
|
<dd>xml output archive used for saving.</dd>
|
|
|
|
<dt><a target="text_wiarchive" href="../../../boost/archive/xml_wiarchive.hpp">
|
|
boost/archive/xml_wiarchive.hpp
|
|
</a>
|
|
<dd>wide character xml input archive used for loading.</dd>
|
|
|
|
<dt><a target="text_woarchive" href="../../../boost/archive/xml_woarchive.hpp">
|
|
boost/archive/xml_woarchive.hpp
|
|
</a>
|
|
<dd>wide character xml output archive used for saving.</dd>
|
|
|
|
</dl>
|
|
|
|
<a name="serializationdeclarations">
|
|
<h4>Serialization Declarations</h4>
|
|
To specify how a type is serialized, one codes templates for serialization functions.
|
|
In the simplest cases, this does not require the inclusion of any header files for this purpose.
|
|
In most cases one or more of the following header files will have to be included in order
|
|
to complete or refine the description of the serializaition implementation for a given class.
|
|
|
|
<dl>
|
|
|
|
<dt><a target="base_object" href="../../../boost/serialization/base_object.hpp">
|
|
boost/serialization/base_object.hpp
|
|
</a>
|
|
<dd>For serialization of base classes.</dd>
|
|
|
|
<dt><a target="nvp" href="../../../boost/serialization/nvp.hpp">
|
|
boost/serialization/nvp.hpp
|
|
</a>
|
|
<dd>To associate a name tag with a serializable object. This is necessary to
|
|
properly render an xml archive which includes the object name.</dd>
|
|
|
|
<dt><a target="split_free" href="../../../boost/serialization/split_free.hpp">
|
|
boost/serialization/split_free.hpp
|
|
</a>
|
|
<dd>To divide implementation of <em>non-intrusive</em> serialization into separate
|
|
save and load functions.</dd>
|
|
|
|
<dt><a target="split_member" href="../../../boost/serialization/split_member.hpp">
|
|
boost/serialization/split_member.hpp
|
|
</a>
|
|
<dd>To divide implementation of <em>intrusive</em> serialization into separate
|
|
save and load functions.</dd>
|
|
|
|
<dt><a target="export" href="../../../boost/serialization/export.hpp">
|
|
boost/serialization/export.hpp
|
|
</a>
|
|
<dd>For serialization of pointers to derived classes via key export.</dd>
|
|
|
|
<dt><a target="assume_abstract" href="../../../boost/serialization/assume_abstract.hpp">
|
|
boost/serialization/assume_abstract.hpp
|
|
</a>
|
|
<dd>This is just a thin wrapper which permits one to explicitly specify that a
|
|
particular type is an abstract base class. It is necessary to use this
|
|
for compilers which don't support the boost type traits implementation of
|
|
is_abstact.
|
|
</dd>
|
|
|
|
</dl>
|
|
|
|
This group will be required less frequently. The are used to override aspects of
|
|
the default implementation of the serialization process for specified types.
|
|
|
|
<dl>
|
|
|
|
<dt><a target="version" href="../../../boost/serialization/version.hpp">
|
|
boost/serialization/version.hpp
|
|
</a>
|
|
<dd>To override the default version index (0) assigned to a class.</dd>
|
|
|
|
<dt><a target="level" href="../../../boost/serialization/level.hpp">
|
|
boost/serialization/level.hpp
|
|
</a>
|
|
<dd>To override the default implementaton level trait for a type.</dd>
|
|
|
|
<dt><a target="tracking" href="../../../boost/serialization/tracking.hpp">
|
|
boost/serialization/tracking.hpp
|
|
</a>
|
|
<dd>To override the default tracking trait for a type.</dd>
|
|
|
|
<dt><a target="type_info_implementation" href="../../../boost/serialization/type_info_implementation.hpp">
|
|
boost/serialization/type_info_implementation.hpp
|
|
</a>
|
|
<dd>By default, the library uses RTTI, to identify types at runtime. In some cases, E.G.
|
|
such as a platform which doesn't implement RTTI, this header can be included to permit
|
|
the override of the default runtime type identification system.</dd>
|
|
|
|
</dl>
|
|
|
|
<a name="serializationimplementations">
|
|
<h4>Serialization Implementations</h4>
|
|
This group of headers includes templates which implement serialization for Standard
|
|
Library or Boost Library templates. Any program which uses these templates can
|
|
invoke serialization of objects of these types just by including the corresponding header.
|
|
<p>
|
|
By convention these header files are named:
|
|
|
|
boost/serialization/xxx.hpp
|
|
|
|
where xxx is the name of the header file which contains the type to be serialized.
|
|
For example, the declaration
|
|
<pre><code>
|
|
#include <boost/serialization/list.hpp>
|
|
</code></pre>
|
|
|
|
includes the code to implement serialization of the STL
|
|
<code style="white-space: normal">std::list</code> type. While
|
|
|
|
<pre><code>
|
|
#include <boost/serialization/shared_ptr.hpp>
|
|
</code></pre>
|
|
|
|
includes code to implement serialization of the BOOST <code style="white-space: normal">boost::shared_ptr</code> type.
|
|
|
|
Note that including the serialization header for a type automatically includes the
|
|
appropriate header of the type to be serialized.
|
|
|
|
As of this writing, the library includes templates of all STL library templates as well
|
|
as templates for <code style="white-space: normal">boost::optional</code>,
|
|
<code style="white-space: normal">boost::shared_ptr</code>, and
|
|
<code style="white-space: normal">boost::scoped_ptr</code>.
|
|
Presumably, this list will expand with the passage of time.
|
|
|
|
<a name="libraryimplementation">
|
|
<h3>Files Which Implement the Library</h3>
|
|
|
|
<a name="archivedevelopment">
|
|
<h4>Archive Development</h4>
|
|
These header files contain declarations for basic types used to create
|
|
concrete archive types that are made available to users above. Users wishing
|
|
to make their own type of archive may want to examine these headers to
|
|
see how the archives included with the libary have been constructed.
|
|
|
|
<dl>
|
|
|
|
<dt><a target="basic_archive" href="../../../boost/archive/basic_archive.hpp">
|
|
boost/archive/basic_archive.hpp
|
|
</a>
|
|
</dt>
|
|
<dd>
|
|
This file includes declarations for certain types that have to be accounted
|
|
for in all archive implementations. The serialization system relies on
|
|
certain special types such as <code style="white-space: normal">class_id_type</code> and others to
|
|
record information in archives that is required to reconstruct the original
|
|
data structure. These are handled exactly as any other serializable type.
|
|
That is, they can be handled as simple primitives such as they are in simple
|
|
text files, or with special code as they are in xml archives.
|
|
</dd>
|
|
|
|
<dt><a target="basic_text_oprimitive" href="../../../boost/archive/basic_text_oprimitive.hpp">
|
|
boost/archive/basic_text_oprimitive.hpp
|
|
</a>
|
|
<dt><a target="basic_text_iprimitive" href="../../../boost/archive/basic_text_iprimitive.hpp">
|
|
boost/archive/basic_text_iprimitive.hpp
|
|
</a>
|
|
</dt>
|
|
<dd>
|
|
Implementation of serialization of primitive types in terms of character
|
|
or wide character text streams. This is used in the implementation of text and
|
|
xml archives. Presumably this would be useful for implementations of other variations
|
|
of text archives such as user friendly text or windows ini files.
|
|
</dd>
|
|
|
|
<dt><a target="basic_binary_oprimitive" href="../../../boost/archive/basic_binary_oprimitive.hpp">
|
|
boost/archive/basic_binary_oprimitive.hpp
|
|
</a>
|
|
<dt><a target="basic_binary_iprimitive" href="../../../boost/archive/basic_binary_iprimitive.hpp">
|
|
boost/archive/basic_binary_iprimitive.hpp
|
|
</a>
|
|
</dt>
|
|
<dd>
|
|
Implementation of serialization of primitive types in terms of character
|
|
or wide character binary streams.
|
|
</dd>
|
|
|
|
<dt><a target="basic_binary_oarchive" href="../../../boost/archive/basic_binary_oarchive.hpp">
|
|
boost/archive/basic_binary_oarchive.hpp
|
|
</a>
|
|
<dt><a target="basic_binary_iarchive" href="../../../boost/archive/basic_binary_iarchive.hpp">
|
|
boost/archive/basic_binary_iarchive.hpp
|
|
</a>
|
|
<dd>
|
|
Implementation of serialization of all types in terms of character
|
|
or wide character binary streams. This is factored out separately from the
|
|
implementation of binary primitives above. This may facilitate the creation of
|
|
other types of binary archives in the future. It also preserves analogy and symmetry with
|
|
the rest of the library which aids in understanding.
|
|
</dd>
|
|
<dt><a target="basic_text_oarchive" href="../../../boost/archive/basic_text_oarchive.hpp">
|
|
boost/archive/basic_text_oarchive.hpp
|
|
</a>
|
|
<dt><a target="basic_te't_iarchive" href="../../../boost/archive/basic_text_iarchive.hpp">
|
|
boost/archive/basic_text_iarchive.hpp
|
|
</a>
|
|
</dt>
|
|
<dt><a target="basic_xml_oarchive" href="../../../boost/archive/basic_xml_oarchive.hpp">
|
|
boost/archive/basic_xml_oarchive.hpp
|
|
</a>
|
|
<dt><a target="basic_xml_iarchive" href="../../../boost/archive/basic_xml_iarchive.hpp">
|
|
boost/archive/basic_xml_iarchive.hpp
|
|
</a>
|
|
</dt>
|
|
<dd>
|
|
Implementation of serialization of all types in terms of character
|
|
or wide character text streams. These classes specify archive type specific
|
|
behavior on a type by type basis. For example, <code style="white-space: normal">basic_xml_oarchive.hpp</code>
|
|
includes code to guarantee that any object not attached to a name will
|
|
trap during compile time. On the other hand, <code style="white-space: normal">basic_text_oarchive.hpp</code>
|
|
contains code to strip out and ingore any names attached to objects.
|
|
<p>
|
|
<dt><a target="common_iarchive" href="../../../boost/archive/detail/common_iarchive.hpp">
|
|
boost/archive/detail/common_iarchive.hpp
|
|
</a>
|
|
<dt><a target="common_oarchive" href="../../../boost/archive/detail/common_oarchive.hpp">
|
|
boost/archive/detail/common_oarchive.hpp
|
|
</a>
|
|
<dd>
|
|
All archive implementations are derived from these header files. They provide
|
|
the interface to the internal implementation details of the library.
|
|
</dd>
|
|
|
|
</dl>
|
|
|
|
<a name="archiveinternals">
|
|
<h4>Archive Internals</h4>
|
|
|
|
The interface (see <a target="detail" href="archives.html">Archive Concepts</a>)
|
|
and implementation are factored out into separate classes to minimize code duplication.
|
|
|
|
These files are found in the directory
|
|
<a target="boost_archive_detail" href="../../../boost/archive/detail">boost/archive/detail</a>.
|
|
These are included as necessary by the archive class implemenations listed above.
|
|
This has the unfortunate side effect of making the implementation less transparent.
|
|
Users should never find it necessary to change these files.
|
|
<p>
|
|
The following discussion is based on the
|
|
<a target="class_diagram" href="class_diagram.html">class diagram</a>.
|
|
<p>
|
|
<dt><a target="interface_iarchive" href="../../../boost/archive/detail/interface_iarchive.hpp">
|
|
boost/archive/detail/interface_iarchive.hpp</a>
|
|
<dt><a target="interface_iarchive" href="../../../boost/archive/detail/interface_iarchive.hpp">
|
|
boost/archive/detail/interface_iarchive.hpp</a>
|
|
<dd>
|
|
Here are the declarations and definitions for the
|
|
<a href="archives.html">archive_concept</a>. This class redirects calls to the
|
|
archive interface to a function named <code>save_override</code> in the most derived
|
|
archive class.
|
|
</dd>
|
|
<code>save_override</code> is declared and implemented in each class in
|
|
the archive hierarchy.
|
|
|
|
<pre><code>
|
|
template<class T>
|
|
void save_override(T & t, BOOST_PFTO int){
|
|
// All for otherwise unhandled types are forwarded to the base class.
|
|
// This emulates behavior for function overloading.
|
|
this->base::save_override(t, 0);
|
|
}
|
|
void save_override(const some_type & t, int){
|
|
// any special handling for some type
|
|
// this will usually entail forwarding some other operation
|
|
// in the most derived class.
|
|
this->This()->...
|
|
// or in one of its parents basic_text_oprimitive
|
|
this->This()->save(static_cast<int>(t));
|
|
}
|
|
... // other special type handling
|
|
</code></pre>
|
|
|
|
Note the usage of
|
|
<a target="detail" href="implementation.html#functiontemplateordering">Partial Function Template Ordering</a>
|
|
to permit the correct save implementation to be selected.
|
|
</dd>
|
|
|
|
<a name="codemodules">
|
|
<h4>Archive Library Code Modules</h4>
|
|
Parts of the library are implemented as library code. All of this code is to be found in
|
|
<a target="src" href="../../../libs/serialization/src">libs/serialization/src</a>.
|
|
in the form of *.cpp. The directory
|
|
<a target="src" href="../../../boost/archive/impl">boost/archive/impl</a>
|
|
contains *.ipp files which implement templates. These templates are instantiated
|
|
only by archive implementation so are generally not included in user code modules.
|
|
<p>
|
|
The trade offs related to library implementation via pre-compiled code and templated
|
|
headers are well known. This library uses both. It uses templated headers
|
|
to generate code to serialize user and primitive types and it uses pre-compiled
|
|
library code for that part of the code which only depends upon the archive type.
|
|
Building of the library generates and compiles code for all archives implemented.
|
|
|
|
<ul>
|
|
<li>Serialization of user and primitive types runs at top speed. This is a noticeable
|
|
difference with a previous version of the library which did not use templates for archives.
|
|
<li>Library implementation code that never changes need only be compiled once
|
|
rather than each time a user's program is recompiled. This can save much
|
|
development time.
|
|
<li>Headers which solely related to implementation need only be included
|
|
in the library code modules. This prevents a user program from accidently
|
|
depending on an implementation feature of the serialization library.
|
|
<li>In building the library I came to the conclusions that there can arise
|
|
situations regarding static code/data instantiation that could not be
|
|
satisfactorily addressed without a code module. Unfortunately, I've forgotten
|
|
the circumstances which led me to this conclusion.
|
|
</ul>
|
|
An example of this is the usage of the spirit library in the library.
|
|
It takes a long time to compile and includes lots of other files. Having this
|
|
only in the library is much more convenient that having to include it in every
|
|
program which uses xml serialization.
|
|
|
|
<a name="dataflowiterators">
|
|
<h4>Dataflow Iterators</h4>
|
|
In the course of developing this library, it became convenient to make a set
|
|
of composable iterator adaptors for handling archive text. Applications include
|
|
escaping and unescaping xml text and implementing to/from base64 conversion among
|
|
others.
|
|
<p>
|
|
This is a ripe topic in itself. It's touched upon by the
|
|
<a href="../../../libs/iterator/doc/index.html">boost iterator</a> libraries,
|
|
<a href="http://www.zib.de/weiser/vtl/index.html">View Template Library</a>, and others.
|
|
<p>
|
|
The code for these iterators is really independent of this library. But since it
|
|
hasn't been and probably won't be reviewed outside of this context. I've left it in a directory
|
|
local to the serialization library:
|
|
<a target="archiveiterators" href="../../../boost/archive/iterators">boost/archive/iterators</a>.
|
|
These iterators are described in
|
|
<a href="dataflow.html">Dataflow Iterators</a>.
|
|
<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>
|