ceph/src/boost/libs/serialization/doc/archives.html

   1 <!doctype HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   5 <link rel="stylesheet" type="text/css" href="../../../boost.css">
   6 <link rel="stylesheet" type="text/css" href="style.css">
   7 <title>Serialization - Archives</title>
   8 </head>
   9 <body link="#0000ff" vlink="#800080">
  10 <table border="0" cellpadding="7" cellspacing="0" width="100%" summary="header">
  11   <tr>
  12     <td valign="top" width="300">
  13       <h3><a href="../../../index.htm"><img height="86" width="277" alt="C++ Boost" src="../../../boost.png" border="0"></a></h3>
  14     </td>
  15     <td valign="top">
  16       <h1 align="center">Serialization</h1>
  17       <h2 align="center">Archive Concepts</h2>
  18     </td>
  19   </tr>
  20 </table>
  21 <hr>
  22 <dl class="page-index">
  23   <dt><a href="#saving_interface">Saving Archive Concept</a>
  24   <dt><a href="#loading_interface">Loading Archive Concept</a>
  25   <dt><a href="#archive_models">Models</a>
  26   <dt><a href="#exceptions">Exceptions</a>
  27   <dt><a href="#charactersets">Character Sets</a>
  28 </dl>
  29 <h4>Notation</h4>
  30 In the following descriptions
  31 <ul>
  32   <li><code>SA</code> is an type modeling the <a href="#saving_interface">Saving Archive Concept</a>.
  33   <li><code>sa</code> is an instance of type SA.
  34   <li><code>LA</code> is an type modeling the <a href="#loading_interface">Loading Archive Concept</a>.
  35   <li><code>la</code> is an instance of type LA.
  36   <li><code>T</code> is an <a href="serialization.html"><strong>Serializable</strong></a> Type.
  37   <li><code>x</code> is an instance of type T Type.
  38   <li><code>u,v</code> is a pointer to a an instance of type T.
  39   <li><code>count</code> is an instance of a type that can be converted to <code>std::size_t</code>.
  40 </ul>
  41 <h4><a name="saving_interface">Saving Archive Concept</a></h4>
  42 <h4>Associated Types</h4>
  43 Intuitively, a type modeling this concept will generate a sequence of bytes
  44 corresponding to an arbitrary set of C++ data structures.  Each type modeling the
  45 Saving Archive concept (SA) may be associated with another type modeling the
  46 <a href="#loading_interface">Loading Archive Concept</a>(LA).
  47 This associated type will perform the inverse operation.
  48 That is, given a sequence of bytes generated by SA, it will generate a set of
  49 C++ data structures that is equivalent to the original.
  50 The notion of equivalence is defined by the implementations of the pair of archives and the
  51 way the data are rendered <a href="serialization.html">serializable</a>.
  52 <p>
  53 <h4>Valid Expressions</h4>
  54 <dl>
  55   <dt><h4><code>
  56     SA::is_saving
  57   </code></h4></dt>
  58   <dd>
  59     Returns the Boost MPL Integral Constant type boost::mpl::bool_&lt;true&gt;
  60   </dd>
  61   <dt><h4><code>
  62     SA::is_loading
  63   </code></h4></dt>
  64   <dd>
  65     Returns the Boost MPL Integral Constant type boost::mpl::bool_&lt;false&gt;
  66   </dd>
  67   <dt><h4><code>
  68     sa &lt;&lt; x
  69     <br>
  70     sa &amp; x
  71   </code></h4></dt>
  72   <dd>
  73     These expressions must perform exactly the same function.  They append the
  74     value of <code style="white-space: normal">x</code> along with other information to <code>sa</code>.
  75     This other information is defined by the implementation of the archive.
  76     Typically this information is that which is required by a corresponding
  77     Loading Archive type to properly restore the value of <code>x</code>.
  78     <p>
  79     Returns a reference to <code>sa</code>.
  80   </dd>
  81   <dt><h4><code>
  82     sa.save_binary(u, count)
  83   </code></h4></dt>
  84   <dd>
  85     Appends to the archive <code style="white-space: normal">size_t(count)</code> bytes found at
  86     <code style="white-space: normal">u</code>.
  87   </dd>
  88   <dt><h4><code>
  89     sa.register_type&lt;T&gt;()
  90     <br>
  91     sa.register_type(u)
  92   </code></h4></dt>
  93   <dd>
  94     Appends information about class T to the archive.  This information is used to
  95     construct the correct class when a derived pointer is loaded by a corresponding
  96     Loading Archive type.
  97     Invocation of this member function is referred to as "class registration".
  98     This is explained in detail in
  99     <a href="special.html#derivedpointers">Special Considerations - Derived Pointers</a>.
 100     The second syntax is included to permit this function to be called on non-conforming
 101     compilers when <code style="white-space: normal">sa</code> is a template argument.
 102     For more information, see <a target="detail" href="implementation.html#tempatesyntax">Template Invocation syntax</a>
 103   </dd>
 104   <dt><h4><code>
 105     sa.get_library_version()
 106   </code></h4></dt>
 107   <dd>
 108     Returns an unsigned integer containing the current version number of the serialization
 109     library. This number will be incremented each time the library is altered in such a
 110     way that serialization could be altered for some type.  For example, suppose the type
 111     used for a count of collection members is changed. The code that loads collections
 112     might be conditioned on the library version to make sure that libraries created by
 113     previous versions of the library can still be read.
 114   </dd>
 115   <dt><h4><code>
 116     sa.get_helper&lt;Helper&gt;(void * const helper_instance_id = 0)
 117   </code></h4></dt>
 118   <dd>
 119     See <code>la.get_helper&lt;Helper&gt;(void * const helper_instance_id = 0)</code>
 120     below.
 121   </dd>
 122
 123 </dl>
 124
 125 <h4><a name="loading_interface">Loading Archive Concept</a></h4>
 126 <h4>Associated Types</h4>
 127 Each model of this concept presumes the
 128 existence of a corresponding type modeling the
 129 <a href="#saving_interface">Saving Archive Concept</a>.
 130 The purpose of an instance of this concept is to convert a sequence of bytes
 131 generated by this corresponding type to a set of C++ data structures
 132 equivalent to the original.
 133 <h4>Valid Expressions</h4>
 134 <dl>
 135   <dt><h4><code>
 136     LA::is_saving
 137   </code></h4></dt>
 138   <dd>
 139     Returns the Boost MPL Integral Constant type boost::mpl::bool_&lt;false&gt;
 140   </dd>
 141   <dt><h4><code>
 142     LA::is_loading
 143   </code></h4></dt>
 144   <dd>
 145     Returns the Boost MPL Integral Constant type boost::mpl::bool_&lt;true&gt;
 146   </dd>
 147   <dt><h4><code>
 148     la &gt;&gt; x
 149     <br>
 150     la &amp; x
 151   </code></h4></dt>
 152   <dd>
 153     These expressions must perform exactly the same function.
 154     Sets <code>x</code> to a value retrieved from <code>la</code>.
 155     <p>
 156     Returns a reference to <code>la</code>.
 157   </dd>
 158   <dt><h4><code>
 159     la.load_binary(u, count)
 160   </code></h4></dt>
 161   <dd>
 162     Retrieves from <code style="white-space: normal">la</code> <code style="white-space: normal">size_t(count)</code> bytes and stores
 163     them in memory starting at <code style="white-space: normal">u</code>.
 164   </dd>
 165   <dt>
 166   <dt><h4><code>
 167     la.register_type&lt;T&gt;()
 168     <br>
 169     la.register_type(u)
 170   </code></h4></dt>
 171   <dd>
 172     Retrieves information about class T from the archive.  This information is used to
 173     construct the correct class when loading a pointer to a derived class not
 174     otherwise referred to in the program by name.
 175     Invocation of this member function is referred to as "class registration".
 176     This is explained in detail in
 177     <a href="special.html#derivedpointers">Special Considerations - Derived Pointers</a>.
 178     The second syntax is included to permit this function to be called on non-conforming
 179     compilers when <code style="white-space: normal">la</code> is a template argument.
 180     For more information, see <a target="detail" href="implementation.html#tempatesyntax">Template Invocation syntax</a>
 181   </dd>
 182   <dt><h4><code>
 183     la.get_library_version()
 184   </code></h4></dt>
 185   <dd>
 186     Returns an unsigned integer containing the version number of the serialization
 187     library that created the archive. This number will be incremented each time the
 188     library is altered in such a way that serialization could be altered for some type.
 189     For example, suppose the type used for a count of collection members is changed.
 190     The code that loads collections might be conditioned on the library version to make
 191     sure that libraries created by previous versions of the library can still be read.
 192   </dd>
 193   <dt><h4><code>
 194     la.get_helper&lt;Helper&gt;(void * const helper_instance_id)
 195   </code></h4></dt>
 196   <dd>
 197     Some otherwise unserializable types can be made serializable by inclusion of
 198     a helper object.  The iconic example of this is shared_ptr which needs this
 199     helper object to keep track of previously loaded shared_ptr instances so they
 200     can be "matched up" with subsequently loaded ones.
 201     The first time <code  style="white-space: normal">la.get_helper&lt;Helper&gt;(void * const helper_instance_id)</code>
 202     is invoked for a given helper_instance_id, <code  style="white-space: normal">Helper</code>, a default-constructed
 203     <code style="white-space: normal">Helper</code> object is created, attached to
 204     <code  style="white-space: normal">la</code> and a reference to it is returned. Subsequent
 205     invocations of <code style="white-space: normal">la.get_helper&lt;Helper&gt;(void * const helper_instance_id)</code> with the same id value return
 206     a reference to the formerly constructed object. All objects created in this manner are
 207     destroyed  upon <code style="white-space: normal">la</code> destruction time. The purpose
 208     of helper objects is discussed in
 209     <a href="special.html#helpersupport">Special Considerations - Helper Support</a>.
 210   </dd>
 211   <dt><h4><code>
 212     la.reset_object_address(v, u)
 213   </code></h4></dt>
 214   <dd>
 215     Communicates to the archive that the object originally at address u has been
 216     moved to address v.
 217     <p>
 218     When an object is loaded to a temporary variable and later moved to another location,
 219     this function must be called in order communicate this fact.  This permits the
 220     archive to properly implement object tracking.  Object tracking is required in order
 221     to correctly implement serialization of pointers to instances of derived classes.
 222   </dd>
 223   <dt><h4><code>
 224     la.delete_created_pointers()
 225   </code></h4></dt>
 226   <dd>
 227     Deletes all objects created by the loading of pointers.  This can be used to
 228     avoid memory leaks that might otherwise occur if pointers are being loaded
 229     and the archive load encounters an exception.
 230   </dd>
 231 </dl>
 232
 233 There are archives based on text, binary and XML file
 234 formats but all have the above interface.  Given that all archives present
 235 the same public interface, specifcation of serialization is exactly the same
 236 for all archives.  Archive classes have other members not mentioned here.
 237 However they are related to the internal functioning of the library and
 238 are not meant to be called by users of an archive.  Implementation of new
 239 archives is discussed in
 240 <a href="archive_reference.html#implementation">New Archives - Implementation</a>.
 241
 242 <p>
 243 The existence of the <code style="white-space: normal">&lt;&lt;</code>
 244 and <code style="white-space: normal">&gt;&gt;</code> suggests
 245 a relationship between archives and C++ i/o streams. <strong>Archives are not
 246 C++ i/o streams</strong>. All the archives included with this system take a stream
 247 as an argument in the constructor and that stream is used for output or input.
 248 However, this is not a requirement of the serialization functions or the
 249 archive interface. It just turns out that the archives written so far have
 250 found it useful to base their implementation on streams.
 251
 252 <h3><a name="archive_models">Archive Models</a></h3>
 253 This library includes various implementations of the Archive concept.
 254
 255 An archive is defined by two complementary classes.  One is for saving data while
 256 the other is for loading it.
 257
 258 This library includes a number of archive implementations that are "ready to go" for the
 259 most common requirements.  These classes implement the archive concept for differing data formats.
 260 They can be used "as is" or as a basis for developing one's own particular type of archive.
 261 An archive is defined by two complementary classes. One is for saving data while the other is for loading it.
 262
 263 To invoke serialization using one of
 264 these archives, one or more of the following header files must be
 265 included in the code module containing the serialization code.
 266 <pre><code>
 267 // a portable text archive</a>
 268 <a href="../../../boost/archive/text_oarchive.hpp" target="text_oarchive_cpp">boost::archive::text_oarchive</a> // saving
 269 <a href="../../../boost/archive/text_iarchive.hpp" target="text_iarchive_cpp">boost::archive::text_iarchive</a> // loading
 270
 271 // a portable text archive using a wide character stream</a>
 272 <a href="../../../boost/archive/text_woarchive.hpp">boost::archive::text_woarchive</a> // saving
 273 <a href="../../../boost/archive/text_wiarchive.hpp">boost::archive::text_wiarchive</a> // loading
 274
 275 // a portable XML archive</a>
 276 <a href="../../../boost/archive/xml_oarchive.hpp" target="xml_oarchive_cpp">boost::archive::xml_oarchive</a> // saving
 277 <a href="../../../boost/archive/xml_iarchive.hpp" target="xml_iarchive_cpp">boost::archive::xml_iarchive</a> // loading
 278
 279 // a portable XML archive which uses wide characters - use for utf-8 output</a>
 280 <a href="../../../boost/archive/xml_woarchive.hpp" target="xml_woarchive_cpp">boost::archive::xml_woarchive</a> // saving
 281 <a href="../../../boost/archive/xml_wiarchive.hpp" target="xml_wiarchive_cpp">boost::archive::xml_wiarchive</a> // loading
 282
 283 // a non-portable native binary archive</a>
 284 <a href="../../../boost/archive/binary_oarchive.hpp" target="binary_oarchive_cpp">boost::archive::binary_oarchive</a> // saving
 285 <a href="../../../boost/archive/binary_iarchive.hpp" target="binary_iarchive_cpp">boost::archive::binary_iarchive</a> // loading
 286
 287 <!--
 288 // a non-portable native binary archive which use wide character streams
 289 <a href="../../../boost/archive/binary_woarchive.hpp">boost::archive::binary_woarchive</a> // saving
 290 <a href="../../../boost/archive/binary_wiarchive.hpp">boost::archive::binary_wiarchive</a> // loading
 291 -->
 292
 293 </code></pre>
 294
 295 All of these archives implement the same inteface. Hence, it should suffice to describe only one
 296 of them in detail.  For this purpose we will use the text archive.
 297
 298
 299 <pre><code>
 300 namespace boost {
 301 namespace archive {
 302
 303 enum archive_flags {
 304     no_header = 1,          // suppress archive header info
 305     no_codecvt = 2,         // suppress alteration of codecvt facet
 306     no_xml_tag_checking = 4 // suppress checking of xml tags - igored on saving
 307 };
 308
 309 } // archive
 310 } // boost
 311 </code></pre>
 312
 313 <pre><code>
 314 namespace boost {
 315 namespace archive {
 316
 317 class text_oarchive : ...
 318 {
 319     ...
 320 public:
 321     ... // implementation of the <strong>Saving Archive</strong> concept
 322     text_oarchive(std::ostream & os, unsigned int flags = 0);
 323     ~text_oarchive();
 324 };
 325
 326 } // archive
 327 } // boost
 328 </code></pre>
 329
 330 <dl>
 331
 332 <dt><h4><code>
 333 text_oarchive(std::ostream & os, unsigned int flags = 0);
 334 </code></h4></dt>
 335 <dd>
 336 Constructs an archive given an open <code style="white-space: normal">stream</code> as
 337 an argument and optional flags. For most applications there will be no need to use flags.
 338 Flags are defined by <code style="white-space: normal">enum archive_flags</code> enumerator.
 339 Multiple flags can be combined with the <code style="white-space: normal">|</code> operator.
 340
 341 By default, archives prepend
 342 output with initial data which helps identify them as archives produced by this system.
 343 This permits a more graceful handling of the case where an attempt is made to load an archive
 344 from an invalid file format. In addition to this, each type of archive might have
 345 its own information.  For example, native binary archives include information about
 346 sizes of native types and endianess to gracefully handle the case where it has been
 347 erroneously assumed that such an archive is portable across platforms.  In some cases,
 348 where this extra overhead might be considered objectionable, it can be suppressed with the
 349 <code style="white-space: normal">no_header</code> flag.
 350 <p>
 351 In some cases, an archive may alter (and later restore)
 352 the codecvt facet of the stream locale.  To suppress this action,
 353 include the <code style="white-space: normal">no_codecvt</code> flag.
 354 <p>
 355 XML archives contain nested tags signifying the start and end of data fields.
 356 These tags are normally checked for agreement with the object name when
 357 data is loaded.  If a mismatch occurs an exception is thrown.  It's possible
 358 that this may not be desired behavior.  To suppress this checking of XML
 359 tags, use <code style="white-space: normal">no_xml_tag_checking</code> flag.
 360 </dd>
 361
 362 <dt><h4><code>
 363 ~text_oarchive();
 364 </code></h4></dt>
 365 <dd>
 366 Destructor for an archive.  This should be called before the stream is
 367 closed.  It restores any altered stream facets to their state before the
 368 archive was opened.
 369 </dd>
 370
 371 </dl>
 372
 373 <pre><code>
 374 namespace boost {
 375 namespace archive {
 376
 377 class text_iarchive : ...
 378 {
 379     ...
 380 public:
 381     ... // implementation of the <strong>Loading Archive</strong> concept
 382     text_iarchive(std::istream & is, unsigned int flags = 0);
 383     ~text_iarchive();
 384 };
 385
 386 } //namespace archive
 387 ) //namespace boost
 388
 389 </code></pre>
 390
 391 <dl>
 392
 393 <dt><h4><code>
 394 text_iarchive(std::istream & is, unsigned int flags = 0);
 395 </code></h4></dt>
 396 <dd>
 397 Contructs an archive given an open <code style="white-space: normal">stream</code> as
 398 an argument and optional flags. If flags are used, they should be the same
 399 as those used when the archive was created. Function and usage of flags is described
 400 above.
 401 </dd>
 402
 403 <dt><h4><code>
 404 ~text_iarchive();
 405 </code></h4></dt>
 406 <dd>
 407 Destructor for an archive.  This should be called before the stream is
 408 closed.  It restores any altered stream facets to their state before the
 409 the archive was opened.
 410 </dd>
 411 </dl>
 412 <p>
 413 The <code style="white-space: normal">binary_oarchive</code> and
 414 <code style="white-space: normal">binary_iarchive</code> classes are
 415 implemented in terms of the more basic
 416 <code style="white-space: normal">std::streambuf</code>.  So, in addition
 417 to the common class interface described above, they include the following
 418 constructors:
 419 <dl>
 420 <dt><h4><code>
 421 binary_oarchive(std::streambuf & bsb, unsigned int flags = 0);
 422 </code></h4></dt>
 423 and
 424 <dt><h4><code>
 425 binary_iarchive(std::streambuf & bsb, unsigned int flags = 0);
 426 </code></h4></dt>
 427 </dl>
 428
 429 <h3><a name="exceptions">Exceptions</h3>
 430 All of the archive classes included may throw exceptions.  The list of exceptions that might
 431 be thrown can be found in section <a target="detail" href="exceptions.html">Archive Exceptions</a>
 432 of this documentation.
 433
 434 <h3><a name="charactersets">Character Sets</h3>
 435 This library includes two archive classes for XML. The wide character
 436 version (<code style="white-space: normal">xml_w?archive</code>) renders its output as UTF-8 which can
 437 handle any wide character without loss of information.
 438 <code style="white-space: normal">std::string</code> data is converted from multi-byte format to wide
 439 character format using the current <code style="white-space: normal">
 440 locale</code>.  Hence this version should give a fair rendering of all
 441 C++ data for all cases.  This could result in some unexpected behavior.
 442 Suppose an <code style="white-space: normal">std::string</code>
 443 is created with the <code style="white-space: normal">locale</code> character
 444 set to hebrew characters.  On output this is converted to wide characters.
 445 On input however, there could be a problem if the <code style="white-space: normal">locale</code> is
 446 not set the same as when the archive is created.
 447 <p>
 448 The normal character version (<code style="white-space: normal">xml_?archive</code>) renders
 449 <code style="white-space: normal">std::string</code> output without any conversion.  Though this may work
 450 fine for serialization,  it may create difficulties if the XML archive is used
 451 for some other purpose.
 452 <hr>
 453 <p><i>&copy; Copyright <a href="http://www.rrsd.com">Robert Ramey</a> 2002-2004.
 454 Distributed under the Boost Software License, Version 1.0. (See
 455 accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 456 </i></p>
 457 </body>
 458 </html>