[ceph.git] / ceph / src / boost / libs / serialization / doc / headers.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 &lt;boost/archive/text_oarchive.hpp&gt;
</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 &lt;boost/serialization/list.hpp&gt;
</code></pre>

includes the code to implement serialization of the STL
<code style="white-space: normal">std::list</code> type. While

<pre><code>
#include &lt;boost/serialization/shared_ptr.hpp&gt;
</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&lt;int&gt;(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>&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>
Commit	Line	Data
7c673cae FG	1	<!doctype HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
	2	<html>
	3	<!--
	4	(C) Copyright 2002-4 Robert Ramey - http://www.rrsd.com .
	5	Use, modification and distribution is subject to the Boost Software
	6	License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
	7	http://www.boost.org/LICENSE_1_0.txt)
	8	-->
	9	<head>
	10	<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
	11	<link rel="stylesheet" type="text/css" href="../../../boost.css">
	12	<link rel="stylesheet" type="text/css" href="style.css">
	13	<title>Serialization - Code Structure</title>
	14	</head>
	15	<body link="#0000ff" vlink="#800080">
	16	<table border="0" cellpadding="7" cellspacing="0" width="100%" summary="header">
	17	<tr>
	18	<td valign="top" width="300">
	19	<h3><a href="../../../index.htm"><img height="86" width="277" alt="C++ Boost" src="../../../boost.png" border="0"></a></h3>
	20	</td>
	21	<td valign="top">
	22	<h1 align="center">Serialization</h1>
	23	<h2 align="center">Code Structure</h2>
	24	</td>
	25	</tr>
	26	</table>
	27	<hr>
	28
	29	<dl class="page-index">
	30	<dt><a href="#userincludes">Files Included by User Programs</a>
	31	<dl class="page-index">
	32	<dt><a href="#archiveimplementations">Archive Implementations</a>
	33	<dt><a href="#serializationdeclarations">Serialization Declarations</a>
	34	<dt><a href="#serializationimplementations">Serialization Implementations</a>
	35	</dl>
	36	<dt><a href="#libraryimplementation">Files Which Implement the Library</a>
	37	<dl class="page-index">
	38	<dt><a href="#archivedevelopment">Archive Development</a>
	39	<dt><a href="#archiveinternals">Archive Internals</a>
	40	<dt><a href="#codemodules">Archive Library Code Modules</a>
	41	<dt><a href="#dataflowiterators">Dataflow Iterators</a>
	42	</dl>
	43	</dl>
	44
	45	This library includes a large number of files. They are organized and classified
	46	according to the purposes listed in the above index.
	47	<p>
	48	<code style="white-space: normal">namespace</code> of classes and templates is synchronized
	49	with the directory in which the file is found. For example, the class declaration
	50	<pre><code>
	51	boost::archive::text_oarchive
	52	</code></pre>
	53	is included with the following declaration
	54	<pre><code>
	55	#include <boost/archive/text_oarchive.hpp>
	56	</code></pre>
	57
	58	<a name="userincludes">
	59	<h3>Files Included by User Programs</h3>
	60	Using this library entails including headers listed in this section.
	61	It should not be necessary to explictly include any other header files.
	62
	63	<a name="archiveimplementations">
	64	<h4>Archive Implementations</h4>
65	These header files contain declarations used to save and restore data to each type
66	of archive. Include the archives according to the facilities the code module requires.
67
68	<dl>
69
70	<dt><a target="archive_exception" href="../../../boost/archive/archive_exception.hpp">
71	boost/archive/archive_exception.hpp
72	</a>
73	<dd>Exceptions which might be invoked by the library.</dd>
74
75	<dt><a target="binary_iarchive" href="../../../boost/archive/binary_iarchive.hpp">
76	boost/archive/binary_iarchive.hpp
77	</a>
78	<dd>native binary input archive used for loading.</dd>
79
80	<dt><a target="binary_oarchive" href="../../../boost/archive/binary_oarchive.hpp">
81	boost/archive/binary_oarchive.hpp
82	</a>
83	<dd>native binary output archive used for saving.</dd>
84
85	<dt><a target="text_iarchive" href="../../../boost/archive/text_iarchive.hpp">
86	boost/archive/text_iarchive.hpp
87	</a>
88	<dd>text input archive used for loading.</dd>
89
90	<dt><a target="text_oarchive" href="../../../boost/archive/text_oarchive.hpp">
91	boost/archive/text_oarchive.hpp
92	</a>
93	<dd>text output archive used for saving.</dd>
94
95	<dt><a target="text_wiarchive" href="../../../boost/archive/text_wiarchive.hpp">
96	boost/archive/text_wiarchive.hpp
97	</a>
98	<dd>wide character text input archive used for loading.</dd>
99
100	<dt><a target="text_woarchive" href="../../../boost/archive/text_woarchive.hpp">
101	boost/archive/text_woarchive.hpp
102	</a>
103	<dd>wide character text input archive used for saving.</dd>
104
105	<dt><a target="xml_iarchive" href="../../../boost/archive/xml_iarchive.hpp">
106	boost/archive/xml_iarchive.hpp
107	</a>
108	<dd>xml input archive used for loading.</dd>
109
110	<dt><a target="text_oarchive" href="../../../boost/archive/xml_oarchive.hpp">
111	boost/archive/xml_oarchive.hpp
112	</a>
113	<dd>xml output archive used for saving.</dd>
114
115	<dt><a target="text_wiarchive" href="../../../boost/archive/xml_wiarchive.hpp">
116	boost/archive/xml_wiarchive.hpp
117	</a>
118	<dd>wide character xml input archive used for loading.</dd>
119
120	<dt><a target="text_woarchive" href="../../../boost/archive/xml_woarchive.hpp">
121	boost/archive/xml_woarchive.hpp
122	</a>
123	<dd>wide character xml output archive used for saving.</dd>
124
125	</dl>
126
127	<a name="serializationdeclarations">
128	<h4>Serialization Declarations</h4>
129	To specify how a type is serialized, one codes templates for serialization functions.
130	In the simplest cases, this does not require the inclusion of any header files for this purpose.
131	In most cases one or more of the following header files will have to be included in order
132	to complete or refine the description of the serializaition implementation for a given class.
133
134	<dl>
135
136	<dt><a target="base_object" href="../../../boost/serialization/base_object.hpp">
137	boost/serialization/base_object.hpp
138	</a>
139	<dd>For serialization of base classes.</dd>
140
141	<dt><a target="nvp" href="../../../boost/serialization/nvp.hpp">
142	boost/serialization/nvp.hpp
143	</a>
144	<dd>To associate a name tag with a serializable object. This is necessary to
145	properly render an xml archive which includes the object name.</dd>
146
147	<dt><a target="split_free" href="../../../boost/serialization/split_free.hpp">
148	boost/serialization/split_free.hpp
149	</a>
150	<dd>To divide implementation of <em>non-intrusive</em> serialization into separate
151	save and load functions.</dd>
152
153	<dt><a target="split_member" href="../../../boost/serialization/split_member.hpp">
154	boost/serialization/split_member.hpp
155	</a>
156	<dd>To divide implementation of <em>intrusive</em> serialization into separate
157	save and load functions.</dd>
158
159	<dt><a target="export" href="../../../boost/serialization/export.hpp">
160	boost/serialization/export.hpp
161	</a>
162	<dd>For serialization of pointers to derived classes via key export.</dd>
163
164	<dt><a target="assume_abstract" href="../../../boost/serialization/assume_abstract.hpp">
165	boost/serialization/assume_abstract.hpp
166	</a>
167	<dd>This is just a thin wrapper which permits one to explicitly specify that a
168	particular type is an abstract base class. It is necessary to use this
169	for compilers which don't support the boost type traits implementation of
170	is_abstact.
171	</dd>
172
173	</dl>
174
175	This group will be required less frequently. The are used to override aspects of
176	the default implementation of the serialization process for specified types.
177
178	<dl>
179
180	<dt><a target="version" href="../../../boost/serialization/version.hpp">
181	boost/serialization/version.hpp
182	</a>
183	<dd>To override the default version index (0) assigned to a class.</dd>
184
185	<dt><a target="level" href="../../../boost/serialization/level.hpp">
186	boost/serialization/level.hpp
187	</a>
188	<dd>To override the default implementaton level trait for a type.</dd>
189
190	<dt><a target="tracking" href="../../../boost/serialization/tracking.hpp">
191	boost/serialization/tracking.hpp
192	</a>
193	<dd>To override the default tracking trait for a type.</dd>
194
195	<dt><a target="type_info_implementation" href="../../../boost/serialization/type_info_implementation.hpp">
196	boost/serialization/type_info_implementation.hpp
197	</a>
198	<dd>By default, the library uses RTTI, to identify types at runtime. In some cases, E.G.
199	such as a platform which doesn't implement RTTI, this header can be included to permit
200	the override of the default runtime type identification system.</dd>
201
202	</dl>
203
204	<a name="serializationimplementations">
205	<h4>Serialization Implementations</h4>
206	This group of headers includes templates which implement serialization for Standard
207	Library or Boost Library templates. Any program which uses these templates can
208	invoke serialization of objects of these types just by including the corresponding header.
209	<p>
210	By convention these header files are named:
211
212	boost/serialization/xxx.hpp
213
214	where xxx is the name of the header file which contains the type to be serialized.
215	For example, the declaration
216	<pre><code>
217	#include <boost/serialization/list.hpp>
218	</code></pre>
219
220	includes the code to implement serialization of the STL
221	<code style="white-space: normal">std::list</code> type. While
222
223	<pre><code>
224	#include <boost/serialization/shared_ptr.hpp>
225	</code></pre>
226
227	includes code to implement serialization of the BOOST <code style="white-space: normal">boost::shared_ptr</code> type.
228
229	Note that including the serialization header for a type automatically includes the
230	appropriate header of the type to be serialized.
231
232	As of this writing, the library includes templates of all STL library templates as well
233	as templates for <code style="white-space: normal">boost::optional</code>,
234	<code style="white-space: normal">boost::shared_ptr</code>, and
235	<code style="white-space: normal">boost::scoped_ptr</code>.
236	Presumably, this list will expand with the passage of time.
237
238	<a name="libraryimplementation">
239	<h3>Files Which Implement the Library</h3>
240
241	<a name="archivedevelopment">
242	<h4>Archive Development</h4>
243	These header files contain declarations for basic types used to create
244	concrete archive types that are made available to users above. Users wishing
245	to make their own type of archive may want to examine these headers to
246	see how the archives included with the libary have been constructed.
247
248	<dl>
249
250	<dt><a target="basic_archive" href="../../../boost/archive/basic_archive.hpp">
251	boost/archive/basic_archive.hpp
252	</a>
253	</dt>
254	<dd>
255	This file includes declarations for certain types that have to be accounted
256	for in all archive implementations. The serialization system relies on
257	certain special types such as <code style="white-space: normal">class_id_type</code> and others to
258	record information in archives that is required to reconstruct the original
259	data structure. These are handled exactly as any other serializable type.
260	That is, they can be handled as simple primitives such as they are in simple
261	text files, or with special code as they are in xml archives.
262	</dd>
263
264	<dt><a target="basic_text_oprimitive" href="../../../boost/archive/basic_text_oprimitive.hpp">
265	boost/archive/basic_text_oprimitive.hpp
266	</a>
267	<dt><a target="basic_text_iprimitive" href="../../../boost/archive/basic_text_iprimitive.hpp">
268	boost/archive/basic_text_iprimitive.hpp
269	</a>
270	</dt>
271	<dd>
272	Implementation of serialization of primitive types in terms of character
273	or wide character text streams. This is used in the implementation of text and
274	xml archives. Presumably this would be useful for implementations of other variations
275	of text archives such as user friendly text or windows ini files.
276	</dd>
277
278	<dt><a target="basic_binary_oprimitive" href="../../../boost/archive/basic_binary_oprimitive.hpp">
279	boost/archive/basic_binary_oprimitive.hpp
280	</a>
281	<dt><a target="basic_binary_iprimitive" href="../../../boost/archive/basic_binary_iprimitive.hpp">
282	boost/archive/basic_binary_iprimitive.hpp
283	</a>
284	</dt>
285	<dd>
286	Implementation of serialization of primitive types in terms of character
287	or wide character binary streams.
288	</dd>
289
290	<dt><a target="basic_binary_oarchive" href="../../../boost/archive/basic_binary_oarchive.hpp">
291	boost/archive/basic_binary_oarchive.hpp
292	</a>
293	<dt><a target="basic_binary_iarchive" href="../../../boost/archive/basic_binary_iarchive.hpp">
294	boost/archive/basic_binary_iarchive.hpp
295	</a>
296	<dd>
297	Implementation of serialization of all types in terms of character
298	or wide character binary streams. This is factored out separately from the
299	implementation of binary primitives above. This may facilitate the creation of
300	other types of binary archives in the future. It also preserves analogy and symmetry with
301	the rest of the library which aids in understanding.
302	</dd>
303	<dt><a target="basic_text_oarchive" href="../../../boost/archive/basic_text_oarchive.hpp">
304	boost/archive/basic_text_oarchive.hpp
305	</a>
306	<dt><a target="basic_te't_iarchive" href="../../../boost/archive/basic_text_iarchive.hpp">
307	boost/archive/basic_text_iarchive.hpp
308	</a>
309	</dt>
310	<dt><a target="basic_xml_oarchive" href="../../../boost/archive/basic_xml_oarchive.hpp">
311	boost/archive/basic_xml_oarchive.hpp
312	</a>
313	<dt><a target="basic_xml_iarchive" href="../../../boost/archive/basic_xml_iarchive.hpp">
314	boost/archive/basic_xml_iarchive.hpp
315	</a>
316	</dt>
317	<dd>
318	Implementation of serialization of all types in terms of character
319	or wide character text streams. These classes specify archive type specific
320	behavior on a type by type basis. For example, <code style="white-space: normal">basic_xml_oarchive.hpp</code>
321	includes code to guarantee that any object not attached to a name will
322	trap during compile time. On the other hand, <code style="white-space: normal">basic_text_oarchive.hpp</code>
323	contains code to strip out and ingore any names attached to objects.
324	<p>
325	<dt><a target="common_iarchive" href="../../../boost/archive/detail/common_iarchive.hpp">
326	boost/archive/detail/common_iarchive.hpp
327	</a>
328	<dt><a target="common_oarchive" href="../../../boost/archive/detail/common_oarchive.hpp">
329	boost/archive/detail/common_oarchive.hpp
330	</a>
331	<dd>
332	All archive implementations are derived from these header files. They provide
333	the interface to the internal implementation details of the library.
334	</dd>
335
336	</dl>
337
338	<a name="archiveinternals">
339	<h4>Archive Internals</h4>
340
341	The interface (see <a target="detail" href="archives.html">Archive Concepts</a>)
342	and implementation are factored out into separate classes to minimize code duplication.
343
344	These files are found in the directory
345	<a target="boost_archive_detail" href="../../../boost/archive/detail">boost/archive/detail</a>.
346	These are included as necessary by the archive class implemenations listed above.
347	This has the unfortunate side effect of making the implementation less transparent.
348	Users should never find it necessary to change these files.
349	<p>
350	The following discussion is based on the
351	<a target="class_diagram" href="class_diagram.html">class diagram</a>.
352	<p>
353	<dt><a target="interface_iarchive" href="../../../boost/archive/detail/interface_iarchive.hpp">
354	boost/archive/detail/interface_iarchive.hpp</a>
355	<dt><a target="interface_iarchive" href="../../../boost/archive/detail/interface_iarchive.hpp">
356	boost/archive/detail/interface_iarchive.hpp</a>
357	<dd>
358	Here are the declarations and definitions for the
359	<a href="archives.html">archive_concept</a>. This class redirects calls to the
360	archive interface to a function named <code>save_override</code> in the most derived
361	archive class.
362	</dd>
363	<code>save_override</code> is declared and implemented in each class in
364	the archive hierarchy.
365
366	<pre><code>
367	template<class T>
368	void save_override(T & t, BOOST_PFTO int){
369	// All for otherwise unhandled types are forwarded to the base class.
370	// This emulates behavior for function overloading.
371	this->base::save_override(t, 0);
372	}
373	void save_override(const some_type & t, int){
374	// any special handling for some type
375	// this will usually entail forwarding some other operation
376	// in the most derived class.
377	this->This()->...
378	// or in one of its parents basic_text_oprimitive
379	this->This()->save(static_cast<int>(t));
380	}
381	... // other special type handling
382	</code></pre>
383
384	Note the usage of
385	<a target="detail" href="implementation.html#functiontemplateordering">Partial Function Template Ordering</a>
386	to permit the correct save implementation to be selected.
387	</dd>
388
389	<a name="codemodules">
390	<h4>Archive Library Code Modules</h4>
391	Parts of the library are implemented as library code. All of this code is to be found in
392	<a target="src" href="../../../libs/serialization/src">libs/serialization/src</a>.
393	in the form of *.cpp. The directory
394	<a target="src" href="../../../boost/archive/impl">boost/archive/impl</a>
395	contains *.ipp files which implement templates. These templates are instantiated
396	only by archive implementation so are generally not included in user code modules.
397	<p>
398	The trade offs related to library implementation via pre-compiled code and templated
399	headers are well known. This library uses both. It uses templated headers
400	to generate code to serialize user and primitive types and it uses pre-compiled
401	library code for that part of the code which only depends upon the archive type.
402	Building of the library generates and compiles code for all archives implemented.
403
404	<ul>
405	<li>Serialization of user and primitive types runs at top speed. This is a noticeable
406	difference with a previous version of the library which did not use templates for archives.
407	<li>Library implementation code that never changes need only be compiled once
408	rather than each time a user's program is recompiled. This can save much
409	development time.
410	<li>Headers which solely related to implementation need only be included
411	in the library code modules. This prevents a user program from accidently
412	depending on an implementation feature of the serialization library.
413	<li>In building the library I came to the conclusions that there can arise
414	situations regarding static code/data instantiation that could not be
415	satisfactorily addressed without a code module. Unfortunately, I've forgotten
416	the circumstances which led me to this conclusion.
417	</ul>
418	An example of this is the usage of the spirit library in the library.
419	It takes a long time to compile and includes lots of other files. Having this
420	only in the library is much more convenient that having to include it in every
421	program which uses xml serialization.
422
423	<a name="dataflowiterators">
424	<h4>Dataflow Iterators</h4>
425	In the course of developing this library, it became convenient to make a set
426	of composable iterator adaptors for handling archive text. Applications include
427	escaping and unescaping xml text and implementing to/from base64 conversion among
428	others.
429	<p>
430	This is a ripe topic in itself. It's touched upon by the
431	<a href="../../../libs/iterator/doc/index.html">boost iterator</a> libraries,
432	<a href="http://www.zib.de/weiser/vtl/index.html">View Template Library</a>, and others.
433	<p>
434	The code for these iterators is really independent of this library. But since it
435	hasn't been and probably won't be reviewed outside of this context. I've left it in a directory
436	local to the serialization library:
437	<a target="archiveiterators" href="../../../boost/archive/iterators">boost/archive/iterators</a>.
438	These iterators are described in
439	<a href="dataflow.html">Dataflow Iterators</a>.
440	<hr>
441	<p><i>© Copyright <a href="http://www.rrsd.com">Robert Ramey</a> 2002-2004.
442	Distributed under the Boost Software License, Version 1.0. (See
443	accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
444	</i></p>
445	</body>
446	</html>