1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
|
<!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. The are organized and classified
according to purpose listed in the above index.
<p>
<code style="white-space: normal">namespace</code> of a classes and templates is syncronized
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 forloading.</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="is_abstract" href="../../../boost/serialization/is_abstract.hpp">
boost/serialization/is_abstract.hpp
</a>
<dd>For serialization of pointers to abstract base classes. A generic implementation
of this is functional only on the most modern compilers. This one is just
a thin wrapper which permits one to specify "by hand" whether or not a base class
is abstract or not.</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, the 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 an 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 an 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 an 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 symetry 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_text_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 an 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 guarentee 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 implmentations 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 header files in the directory
<a target="basic_xml_iarchive" href="../../../boost/archive/detail">boost/archive/detail</a>
implement parts of the library itself. The should never need to be changed by users
of the library in order to implement either a class serialization or a new
archive type.
<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 a top speed. This is a noticiable
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 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, implementing to/from base64 conversion among
others.
<p>
This is a ripe topic in itself. Its 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 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>
|
