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> 30In 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> 43Intuitively, a type modeling this concept will generate a sequence of bytes 44corresponding to an arbitrary set of C++ data structures. Each type modeling the 45Saving Archive concept (SA) may be associated with another type modeling the 46<a href="#loading_interface">Loading Archive Concept</a>(LA). 47This associated type will perform the inverse operation. 48That is, given a sequence of bytes generated by SA, it will generate a set of 49C++ data structures that is equivalent to the original. 50The notion of equivalence is defined by the implementations of the pair of archives and the 51way 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_<true> 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_<false> 66 </dd> 67 <dt><h4><code> 68 sa << x 69 <br> 70 sa & 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<T>() 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<Helper>(void * const helper_instance_id = 0) 117 </code></h4></dt> 118 <dd> 119 See <code>la.get_helper<Helper>(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> 127Each model of this concept presumes the 128existence of a corresponding type modeling the 129<a href="#saving_interface">Saving Archive Concept</a>. 130The purpose of an instance of this concept is to convert a sequence of bytes 131generated by this corresponding type to a set of C++ data structures 132equivalent 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_<false> 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_<true> 146 </dd> 147 <dt><h4><code> 148 la >> x 149 <br> 150 la & 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<T>() 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<Helper>(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<Helper>(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<Helper>(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 233There are archives based on text, binary and XML file 234formats but all have the above interface. Given that all archives present 235the same public interface, specifcation of serialization is exactly the same 236for all archives. Archive classes have other members not mentioned here. 237However they are related to the internal functioning of the library and 238are not meant to be called by users of an archive. Implementation of new 239archives is discussed in 240<a href="archive_reference.html#implementation">New Archives - Implementation</a>. 241 242<p> 243The existence of the <code style="white-space: normal"><<</code> 244and <code style="white-space: normal">>></code> suggests 245a relationship between archives and C++ i/o streams. <strong>Archives are not 246C++ i/o streams</strong>. All the archives included with this system take a stream 247as an argument in the constructor and that stream is used for output or input. 248However, this is not a requirement of the serialization functions or the 249archive interface. It just turns out that the archives written so far have 250found it useful to base their implementation on streams. 251 252<h3><a name="archive_models">Archive Models</a></h3> 253This library includes various implementations of the Archive concept. 254 255An archive is defined by two complementary classes. One is for saving data while 256the other is for loading it. 257 258This library includes a number of archive implementations that are "ready to go" for the 259most common requirements. These classes implement the archive concept for differing data formats. 260They can be used "as is" or as a basis for developing one's own particular type of archive. 261An archive is defined by two complementary classes. One is for saving data while the other is for loading it. 262 263To invoke serialization using one of 264these archives, one or more of the following header files must be 265included 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 295All of these archives implement the same interface. Hence, it should suffice to describe only one 296of them in detail. For this purpose we will use the text archive. 297 298 299<pre><code> 300namespace boost { 301namespace archive { 302 303enum 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> 314namespace boost { 315namespace archive { 316 317class text_oarchive : ... 318{ 319 ... 320public: 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> 333text_oarchive(std::ostream & os, unsigned int flags = 0); 334</code></h4></dt> 335<dd> 336Constructs an archive given an open <code style="white-space: normal">stream</code> as 337an argument and optional flags. For most applications there will be no need to use flags. 338Flags are defined by <code style="white-space: normal">enum archive_flags</code> enumerator. 339Multiple flags can be combined with the <code style="white-space: normal">|</code> operator. 340 341By default, archives prepend 342output with initial data which helps identify them as archives produced by this system. 343This permits a more graceful handling of the case where an attempt is made to load an archive 344from an invalid file format. In addition to this, each type of archive might have 345its own information. For example, native binary archives include information about 346sizes of native types and endianess to gracefully handle the case where it has been 347erroneously assumed that such an archive is portable across platforms. In some cases, 348where 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> 351In some cases, an archive may alter (and later restore) 352the codecvt facet of the stream locale. To suppress this action, 353include the <code style="white-space: normal">no_codecvt</code> flag. 354<p> 355XML archives contain nested tags signifying the start and end of data fields. 356These tags are normally checked for agreement with the object name when 357data is loaded. If a mismatch occurs an exception is thrown. It's possible 358that this may not be desired behavior. To suppress this checking of XML 359tags, 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> 366Destructor for an archive. This should be called before the stream is 367closed. It restores any altered stream facets to their state before the 368archive was opened. 369</dd> 370 371</dl> 372 373<pre><code> 374namespace boost { 375namespace archive { 376 377class text_iarchive : ... 378{ 379 ... 380public: 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> 394text_iarchive(std::istream & is, unsigned int flags = 0); 395</code></h4></dt> 396<dd> 397Contructs an archive given an open <code style="white-space: normal">stream</code> as 398an argument and optional flags. If flags are used, they should be the same 399as those used when the archive was created. Function and usage of flags is described 400above. 401</dd> 402 403<dt><h4><code> 404~text_iarchive(); 405</code></h4></dt> 406<dd> 407Destructor for an archive. This should be called before the stream is 408closed. It restores any altered stream facets to their state before the 409the archive was opened. 410</dd> 411</dl> 412<p> 413The <code style="white-space: normal">binary_oarchive</code> and 414<code style="white-space: normal">binary_iarchive</code> classes are 415implemented in terms of the more basic 416<code style="white-space: normal">std::streambuf</code>. So, in addition 417to the common class interface described above, they include the following 418constructors: 419<dl> 420<dt><h4><code> 421binary_oarchive(std::streambuf & bsb, unsigned int flags = 0); 422</code></h4></dt> 423and 424<dt><h4><code> 425binary_iarchive(std::streambuf & bsb, unsigned int flags = 0); 426</code></h4></dt> 427</dl> 428 429<h3><a name="exceptions">Exceptions</h3> 430All of the archive classes included may throw exceptions. The list of exceptions that might 431be thrown can be found in section <a target="detail" href="exceptions.html">Archive Exceptions</a> 432of this documentation. 433 434<h3><a name="charactersets">Character Sets</h3> 435This library includes two archive classes for XML. The wide character 436version (<code style="white-space: normal">xml_w?archive</code>) renders its output as UTF-8 which can 437handle 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 439character format using the current <code style="white-space: normal"> 440locale</code>. Hence this version should give a fair rendering of all 441C++ data for all cases. This could result in some unexpected behavior. 442Suppose an <code style="white-space: normal">std::string</code> 443is created with the <code style="white-space: normal">locale</code> character 444set to hebrew characters. On output this is converted to wide characters. 445On input however, there could be a problem if the <code style="white-space: normal">locale</code> is 446not set the same as when the archive is created. 447<p> 448The 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 450fine for serialization, it may create difficulties if the XML archive is used 451for some other purpose. 452<hr> 453<p><i>© Copyright <a href="http://www.rrsd.com">Robert Ramey</a> 2002-2004. 454Distributed under the Boost Software License, Version 1.0. (See 455accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 456</i></p> 457</body> 458</html> 459
