ceph/src/boost/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. 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 &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 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 &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, 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&lt;int&gt;(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>&copy; 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>