← Back to branch summary

~ubuntu-branches/debian/sid/boost1.49/sid

« back to all changes in this revision

Viewing changes to libs/serialization/doc/headers.html

  • Committer: Package Import Robot
  • Author(s): Steve M. Robbins
  • Date: 2012-02-26 00:31:44 UTC
  • Revision ID: package-import@ubuntu.com-20120226003144-eaytp12cbf6ubpms
Tags: upstream-1.49.0
Import upstream version 1.49.0

Show diffs side-by-side

added added

removed removed

Lines of Context:
libs/serialization/doc/headers.html
 
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. The are organized and classified
 
46
according to purpose listed in the above index. 
 
47
<p>
 
48
<code style="white-space: normal">namespace</code> of a classes and templates is syncronized
 
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 &lt;boost/archive/text_oarchive.hpp&gt;
 
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 forloading.</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 &lt;boost/serialization/list.hpp&gt;
 
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 &lt;boost/serialization/shared_ptr.hpp&gt;
 
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, the 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 an 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 an 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 an 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 symetry 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 an 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 guarentee 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
of the library in order to implement either a class serialization or a new
 
349
archive type. Users should never find it necessary to change these files.
 
350
<p>
 
351
The following discussion is based on the
 
352
<a target="class_diagram" href="class_diagram.html">class diagram</a>.
 
353
<p>
 
354
<dt><a target="interface_iarchive" href="../../../boost/archive/detail/interface_iarchive.hpp">
 
355
boost/archive/detail/interface_iarchive.hpp</a>
 
356
<dt><a target="interface_iarchive" href="../../../boost/archive/detail/interface_iarchive.hpp">
 
357
boost/archive/detail/interface_iarchive.hpp</a>
 
358
<dd>
 
359
Here are the declarations and definitions which for the 
 
360
<a href="archives.html">archive_concept</a>. This class redirects calls to the 
 
361
archive interface to a function named <code>save_override</code> in the most derived
 
362
archive class. 
 
363
</dd>
 
364
<code>save_override</code> is declared and implemented in each class in
 
365
the archive hierarchy.
 
366
 
 
367
<pre><code>
 
368
template<class T>
 
369
void save_override(T & t, BOOST_PFTO int){
 
370
    // All for otherwise unhandled types are forwarded to the base class.
 
371
    // This emulates behavior for function overloading.
 
372
    this->base::save_override(t, 0);
 
373
}
 
374
void save_override(const some_type & t, int){
 
375
    // any special handling for some type
 
376
    // this will usually entail forwarding some other operation
 
377
    // in the most derived class.
 
378
    this->This()->...
 
379
    // or in one of its parents basic_text_oprimitive
 
380
    this->This()->save(static_cast&lt;int&gt;(t));
 
381
}
 
382
... // other special type handling
 
383
</code></pre>
 
384
 
 
385
Note the usage of
 
386
<a target="detail" href="implementation.html#functiontemplateordering">Partial Function Template Ordering</a>
 
387
to permit the correct save implementation to be selected.  
 
388
</dd>
 
389
 
 
390
<a name="codemodules">
 
391
<h4>Archive Library Code Modules</h4>
 
392
Parts of the library are implemented as library code. All of this code is to be found in
 
393
<a target="src" href="../../../libs/serialization/src">libs/serialization/src</a>. 
 
394
in the form of *.cpp.  The directory
 
395
<a target="src" href="../../../boost/archive/impl">boost/archive/impl</a>
 
396
contains *.ipp files which implement templates. These templates are instantiated
 
397
only by archive implementation so are generally not included in user code modules.
 
398
<p>
 
399
The trade offs related to library implementation via pre-compiled code and templated
 
400
headers are well known.  This library uses both.  It uses templated headers
 
401
to generate code to serialize user and primitive types and it uses pre-compiled
 
402
library code for that part of the code which only depends upon the archive type.
 
403
Building of the library generates and compiles code for all archives implemented.
 
404
 
 
405
<ul>
 
406
  <li>Serialization of user and primitive types runs a top speed. This is a noticiable
 
407
  difference with a previous version of the library which did not use templates for archives.
 
408
  <li>Library implementation code that never changes need only be compiled once
 
409
  rather than each time a user's program is recompiled.  This can save much
 
410
  development time.
 
411
  <li>Headers which solely related to implementation need only be included
 
412
  in the library code modules. This prevents a user program from accidently 
 
413
  depending on an implementation feature of the serialization library.
 
414
  <li>In building the library I came to the conclusions that there can arise
 
415
  situations regarding static code/data instantiation that could not be 
 
416
  satisfactorily addressed without a code module.  Unfortunately, I've forgotten
 
417
  the circumstances which led me to this conclusion.
 
418
</ul>   
 
419
An example of this is the usage of the spirit library in the library.
 
420
It takes a long time to compile and includes lots of other files. Having this
 
421
only in the library is much more convenient that having to include in every
 
422
program which uses xml serialization.
 
423
 
 
424
<a name="dataflowiterators">
 
425
<h4>Dataflow Iterators</h4>
 
426
In the course of developing this library, it became convenient to make a set
 
427
of composable iterator adaptors for handling archive text.  Applications include
 
428
escaping and unescaping xml text, implementi'g to/from base64 conversion among
 
429
others.
 
430
<p>
 
431
This is a ripe topic in itself. Its touched upon by the 
 
432
<a href="../../../libs/iterator/doc/index.html">boost iterator</a> libraries, 
 
433
<a href="http://www.zib.de/weiser/vtl/index.html">View Template Library</a>, and others. 
 
434
<p>
 
435
The code for these iterators is really independent of this library.  But since it
 
436
hasn't been and probably won't be reviewed outside of this context. I've left in a directory 
 
437
local to the serialization library:
 
438
<a target="archiveiterators" href="../../../boost/archive/iterators">boost/archive/iterators</a>.
 
439
These iterators are described in 
 
440
<a href="dataflow.html">Dataflow Iterators</a>.
 
441
<hr>
 
442
<p><i>&copy; Copyright <a href="http://www.rrsd.com">Robert Ramey</a> 2002-2004. 
 
443
Distributed under the Boost Software License, Version 1.0. (See
 
444
accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 
445
</i></p>
 
446
</body>
 
447
</html>