Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_34_1/libs/serialization/doc/headers.html @ 29

Last change on this file since 29 was 29, checked in by landauf, 17 years ago

updated boost from 1_33_1 to 1_34_1
File size: 16.5 KB
Line 
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 .
5Use, modification and distribution is subject to the Boost Software
6License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
7http://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
45This library includes a large number of files. The are organized and classified
46according to purpose listed in the above index.
47<p>
48<code style="white-space: normal">namespace</code> of a classes and templates is syncronized
49with the directory in which the file is found.  For example, the class declaration
50<pre><code>
51boost::archive::text_oarchive
52</code></pre>
53is included with the following declaration
54<pre><code>
55#include &lt;boost/archive/text_oarchive.hpp&gt;
56</code></pre>
57
58<a name="userincludes">
59<h3>Files Included by User Programs</h3>
60Using this library entails including headers listed in this section.
61It should not be necessary to explictly include any other header files.
62
63<a name="archiveimplementations">
64<h4>Archive Implementations</h4>
65These header files contain declarations used to save and restore data to each type
66of 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">
71boost/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">
76boost/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">
81boost/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">
86boost/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">
91boost/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">
96boost/archive/text_wiarchive.hpp
97</a>
98<dd>wide character text input archive used forloading.</dd>
99
100<dt><a target="text_woarchive" href="../../../boost/archive/text_woarchive.hpp">
101boost/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">
106boost/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">
111boost/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">
116boost/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">
121boost/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>
129To specify how a type is serialized, one codes templates for serialization functions.
130In the simplest cases, this does not require the inclusion of any header files for this purpose.
131In most cases one or more of the following header files will have to be included in order
132to 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">
137boost/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">
142boost/serialization/nvp.hpp
143</a>
144<dd>To associate a name tag with a serializable object.  This is necessary to
145properly render an xml archive which includes the object name.</dd>
146
147<dt><a target="split_free" href="../../../boost/serialization/split_free.hpp">
148boost/serialization/split_free.hpp
149</a>
150<dd>To divide implementation of <em>non-intrusive</em> serialization into separate
151save and load functions.</dd>
152
153<dt><a target="split_member" href="../../../boost/serialization/split_member.hpp">
154boost/serialization/split_member.hpp
155</a>
156<dd>To divide implementation of <em>intrusive</em> serialization into separate
157save and load functions.</dd>
158
159<dt><a target="export" href="../../../boost/serialization/export.hpp">
160boost/serialization/export.hpp
161</a>
162<dd>For serialization of pointers to derived classes via key export.</dd>
163
164<dt><a target="is_abstract" href="../../../boost/serialization/is_abstract.hpp">
165boost/serialization/is_abstract.hpp
166</a>
167<dd>For serialization of pointers to abstract base classes.  A generic implementation
168of this is functional only on the most modern compilers.  This one is just
169a thin wrapper which permits one to specify "by hand" whether or not a base class
170is abstract or not.</dd>
171
172</dl>
173
174This group will be required less frequently.  The are used to override aspects of
175the default implementation of the serialization process for specified types.
176
177<dl>
178
179<dt><a target="version" href="../../../boost/serialization/version.hpp">
180boost/serialization/version.hpp
181</a>
182<dd>To override the default version index (0) assigned to a class.</dd>
183
184<dt><a target="level" href="../../../boost/serialization/level.hpp">
185boost/serialization/level.hpp
186</a>
187<dd>To override the default implementaton level trait for a type.</dd>
188
189<dt><a target="tracking" href="../../../boost/serialization/tracking.hpp">
190boost/serialization/tracking.hpp
191</a>
192<dd>To override the default tracking trait for a type.</dd>
193
194<dt><a target="type_info_implementation" href="../../../boost/serialization/type_info_implementation.hpp">
195boost/serialization/type_info_implementation.hpp
196</a>
197<dd>By default, the library uses RTTI, to identify types at runtime. In some cases, E.G.
198such as a platform which doesn't implement RTTI, this header can be included to permit
199the override of the default runtime type identification system.</dd>
200
201</dl>
202
203<a name="serializationimplementations">
204<h4>Serialization Implementations</h4>
205This group of headers includes templates which implement serialization for Standard
206Library or Boost Library templates.  Any program which uses these templates can
207invoke serialization of objects of these types just by including the corresponding header.
208<p>
209By convention, these header files are named:
210
211boost/serialization/xxx.hpp
212
213where xxx is the name of the header file which contains the type to be serialized.
214For example, the declaration
215<pre><code>
216#include &lt;boost/serialization/list.hpp&gt;
217</code></pre>
218
219includes the code to implement serialization of the STL
220<code style="white-space: normal">std::list</code> type. While
221
222<pre><code>
223#include &lt;boost/serialization/shared_ptr.hpp&gt;
224</code></pre>
225
226includes code to implement serialization of the BOOST <code style="white-space: normal">boost::shared_ptr</code> type.
227
228Note that including the serialization header for a type automatically includes the
229appropriate header of the type to be serialized.
230
231As of this writing, the library includes templates of all STL library templates as well
232as templates for <code style="white-space: normal">boost::optional</code>,
233<code style="white-space: normal">boost::shared_ptr</code>, and
234<code style="white-space: normal">boost::scoped_ptr</code>. 
235Presumably, this list will expand with the passage of time.
236
237<a name="libraryimplementation">
238<h3>Files Which Implement the Library</h3>
239
240<a name="archivedevelopment">
241<h4>Archive Development</h4>
242These header files contain declarations for basic types used to create
243concrete archive types that are made available to users above. Users wishing
244to make their own type of archive may want to examine these headers to
245see how the archives included with the libary have been constructed.
246
247<dl>
248
249<dt><a target="basic_archive" href="../../../boost/archive/basic_archive.hpp">
250boost/archive/basic_archive.hpp
251</a>
252</dt>
253<dd>
254This file includes declarations for certain types that have to be accounted
255for in all archive implementations.  The serialization system relies on
256certain special types such as <code style="white-space: normal">class_id_type</code> and others to
257record information in archives that is required to reconstruct the original
258data structure.  These are handled exactly as any other serializable type.
259That is, the can be handled as simple primitives such as they are in simple
260text files, or with special code as they are in xml archives.
261</dd>
262
263<dt><a target="basic_text_oprimitive" href="../../../boost/archive/basic_text_oprimitive.hpp">
264boost/archive/basic_text_oprimitive.hpp
265</a>
266<dt><a target="basic_text_iprimitive" href="../../../boost/archive/basic_text_iprimitive.hpp">
267boost/archive/basic_text_iprimitive.hpp
268</a>
269</dt>
270<dd>
271Implementation of serialization of primitive types in terms of an character
272or wide character text streams. This is used in the implementation of text and
273xml archives.  Presumably this would be useful for implementations of other variations
274of text archives such as user friendly text or windows ini files.
275</dd>
276
277<dt><a target="basic_binary_oprimitive" href="../../../boost/archive/basic_binary_oprimitive.hpp">
278boost/archive/basic_binary_oprimitive.hpp
279</a>
280<dt><a target="basic_binary_iprimitive" href="../../../boost/archive/basic_binary_iprimitive.hpp">
281boost/archive/basic_binary_iprimitive.hpp
282</a>
283</dt>
284<dd>
285Implementation of serialization of primitive types in terms of an character
286or wide character binary streams.
287</dd>
288
289<dt><a target="basic_binary_oarchive" href="../../../boost/archive/basic_binary_oarchive.hpp">
290boost/archive/basic_binary_oarchive.hpp
291</a>
292<dt><a target="basic_binary_iarchive" href="../../../boost/archive/basic_binary_iarchive.hpp">
293boost/archive/basic_binary_iarchive.hpp
294</a>
295<dd>
296Implementation of serialization of all types in terms of an character
297or wide character binary streams.  This is factored out separately from the
298implementation of binary primitives above.  This may facilitate the creation of
299other types of binary archives in the future. It also preserves analogy and symetry with
300the rest of the library which aids in understanding.
301</dd>
302<dt><a target="basic_text_oarchive" href="../../../boost/archive/basic_text_oarchive.hpp">
303boost/archive/basic_text_oarchive.hpp
304</a>
305<dt><a target="basic_text_iarchive" href="../../../boost/archive/basic_text_iarchive.hpp">
306boost/archive/basic_text_iarchive.hpp
307</a>
308</dt>
309<dt><a target="basic_xml_oarchive" href="../../../boost/archive/basic_xml_oarchive.hpp">
310boost/archive/basic_xml_oarchive.hpp
311</a>
312<dt><a target="basic_xml_iarchive" href="../../../boost/archive/basic_xml_iarchive.hpp">
313boost/archive/basic_xml_iarchive.hpp
314</a>
315</dt>
316<dd>
317Implementation of serialization of all types in terms of an character
318or wide character text streams. These classes specify archive type specific
319behavior on a type by type basis.  For example, <code style="white-space: normal">basic_xml_oarchive.hpp</code>
320includes code to guarentee that any object not attached to a name will
321trap during compile time. On the other hand, <code style="white-space: normal">basic_text_oarchive.hpp</code>
322contains code to strip out and ingore any names attached to objects.
323<p>
324<dt><a target="common_iarchive" href="../../../boost/archive/detail/common_iarchive.hpp">
325boost/archive/detail/common_iarchive.hpp
326</a>
327<dt><a target="common_oarchive" href="../../../boost/archive/detail/common_oarchive.hpp">
328boost/archive/detail/common_oarchive.hpp
329</a>
330<dd>
331All archive implmentations are derived from these header files.  They provide
332the interface to the internal implementation details of the library.
333</dd>
334
335</dl>
336
337<a name="archiveinternals">
338<h4>Archive Internals</h4>
339The header files in the directory
340<a target="basic_xml_iarchive" href="../../../boost/archive/detail">boost/archive/detail</a>
341implement parts of the library itself.  The should never need to be changed by users
342of the library in order to implement either a class serialization or a new
343archive type.
344
345<a name="codemodules">
346<h4>Archive Library Code Modules</h4>
347Parts of the library are implemented as library code. All of this code is to be found in
348<a target="src" href="../../../libs/serialization/src">libs/serialization/src</a>.
349in the form of *.cpp.  The directory
350<a target="src" href="../../../boost/archive/impl">boost/archive/impl</a>
351contains *.ipp files which implement templates. These templates are instantiated
352only by archive implementation so are generally not included in user code modules.
353<p>
354The trade offs related to library implementation via pre-compiled code and templated
355headers are well known.  This library uses both.  It uses templated headers
356to generate code to serialize user and primitive types and it uses pre-compiled
357library code for that part of the code which only depends upon the archive type.
358Building of the library generates and compiles code for all archives implemented.
359
360<ul>
361  <li>Serialization of user and primitive types runs a top speed. This is a noticiable
362  difference with a previous version of the library which did not use templates for archives.
363  <li>Library implementation code that never changes need only be compiled once
364  rather than each time a user's program is recompiled.  This can save much
365  development time.
366  <li>Headers which solely related to implementation need only be included
367  in the library code modules. This prevents a user program from accidently
368  depending on an implementation feature of the serialization library.
369  <li>In building the library I came to the conclusions that there can arise
370  situations regarding static code/data instantiation that could not be
371  satisfactorily addressed without a code module.  Unfortunately, I've forgotten
372  the circumstances which led me to this conclusion.
373</ul>   
374An example of this is the usage of the spirit library in the library.
375It takes a long time to compile and includes lots of other files. Having this
376only in the library is much more convenient that having to include in every
377program which uses xml serialization.
378
379<a name="dataflowiterators">
380<h4>Dataflow Iterators</h4>
381In the course of developing this library, it became convenient to make a set
382of composable iterator adaptors for handling archive text.  Applications include
383escaping and unescaping xml text, implementing to/from base64 conversion among
384others.
385<p>
386This is a ripe topic in itself. Its touched upon by the
387<a href="../../../libs/iterator/doc/index.html">boost iterator</a> libraries,
388<a href="http://www.zib.de/weiser/vtl/index.html">View Template Library</a>, and others.
389<p>
390The code for these iterators is really independent of this library.  But since it
391hasn't been and probably won't be reviewed outside of this context. I've left in a directory
392local to the serialization library:
393<a target="archiveiterators" href="../../../boost/archive/iterators">boost/archive/iterators</a>.
394These iterators are described in
395<a href="dataflow.html">Dataflow Iterators</a>.
396<hr>
397<p><i>&copy; Copyright <a href="http://www.rrsd.com">Robert Ramey</a> 2002-2004.
398Distributed under the Boost Software License, Version 1.0. (See
399accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
400</i></p>
401</body>
402</html>
Note: See TracBrowser for help on using the repository browser.