Serialization - Archives

###  | # Serialization ## Archive Concepts

Saving Archive Concept
Loading Archive Concept
Models
Exceptions
Character Sets

#### Notation

In the following descriptions

- `SA` is an type modeling the Saving Archive Concept.
- `sa` is an instance of type SA.
- `LA` is an type modeling the Loading Archive Concept.
- `la` is an instance of type LA.
- `T` is an Serializable Type.
- `x` is an instance of type T Type.
- `u,v` is a pointer to a an instance of type T.
- `count` is an instance of a type that can be converted to `std::size_t`.

#### Saving Archive Concept

#### Associated Types

Intuitively, a type modeling this concept will generate a sequence of bytes corresponding to an arbitrary set of C++ data structures. Each type modeling the Saving Archive concept (SA) may be associated with another type modeling the Loading Archive Concept(LA). This associated type will perform the inverse operation. That is, given a sequence of bytes generated by SA, it will generate a set of C++ data structures that is equivalent to the original. The notion of equivalence is defined by the implementations of the pair of archives and the way the data are rendered serializable.

#### Valid Expressions

#### `SA::is_saving`

  Returns the Boost MPL Integral Constant type boost::mpl::bool_<true>

#### `SA::is_loading`

  Returns the Boost MPL Integral Constant type boost::mpl::bool_<false>

#### `sa << x
sa & x`

  These expressions must perform exactly the same function. They append the value of `x` along with other information to `sa`. This other information is defined by the implementation of the archive. Typically this information is that which is required by a corresponding Loading Archive type to properly restore the value of `x`.

  Returns a reference to `sa`.

#### `sa.save_binary(u, count)`

  Appends to the archive `size_t(count)` bytes found at `u`.

#### `sa.register_type<T>()
sa.register_type(u)`

  Appends information about class T to the archive. This information is used to construct the correct class when a derived pointer is loaded by a corresponding Loading Archive type. Invocation of this member function is referred to as "class registration". This is explained in detail in Special Considerations - Derived Pointers. The second syntax is included to permit this function to be called on non-conforming compilers when `sa` is a template argument. For more information, see Template Invocation syntax

#### `sa.get_library_version()`

  Returns an unsigned integer containing the current version number of the serialization library. This number will be incremented each time the library is altered in such a way that serialization could be altered for some type. For example, suppose the type used for a count of collection members is changed. The code that loads collections might be conditioned on the library version to make sure that libraries created by previous versions of the library can still be read.

#### `sa.get_helper<Helper>(void * const helper_instance_id = 0)`

  See `la.get_helper<Helper>(void * const helper_instance_id = 0)` below.

#### Loading Archive Concept

#### Associated Types

Each model of this concept presumes the existence of a corresponding type modeling the Saving Archive Concept. The purpose of an instance of this concept is to convert a sequence of bytes generated by this corresponding type to a set of C++ data structures equivalent to the original.

#### Valid Expressions

#### `LA::is_saving`

  Returns the Boost MPL Integral Constant type boost::mpl::bool_<false>

#### `LA::is_loading`

  Returns the Boost MPL Integral Constant type boost::mpl::bool_<true>

#### `la >> x
la & x`

  These expressions must perform exactly the same function. Sets `x` to a value retrieved from `la`.

  Returns a reference to `la`.

#### `la.load_binary(u, count)`

  Retrieves from `la` `size_t(count)` bytes and stores them in memory starting at `u`.

#### `la.register_type<T>()
la.register_type(u)`

  Retrieves information about class T from the archive. This information is used to construct the correct class when loading a pointer to a derived class not otherwise referred to in the program by name. Invocation of this member function is referred to as "class registration". This is explained in detail in Special Considerations - Derived Pointers. The second syntax is included to permit this function to be called on non-conforming compilers when `la` is a template argument. For more information, see Template Invocation syntax

#### `la.get_library_version()`

  Returns an unsigned integer containing the version number of the serialization library that created the archive. This number will be incremented each time the library is altered in such a way that serialization could be altered for some type. For example, suppose the type used for a count of collection members is changed. The code that loads collections might be conditioned on the library version to make sure that libraries created by previous versions of the library can still be read.

#### `la.get_helper<Helper>(void * const helper_instance_id)`

  Some otherwise unserializable types can be made serializable by inclusion of a helper object. The iconic example of this is shared_ptr which needs this helper object to keep track of previously loaded shared_ptr instances so they can be "matched up" with subsequently loaded ones. The first time `la.get_helper<Helper>(void * const helper_instance_id)` is invoked for a given helper_instance_id, `Helper`, a default-constructed `Helper` object is created, attached to `la` and a reference to it is returned. Subsequent invocations of `la.get_helper<Helper>(void * const helper_instance_id)` with the same id value return a reference to the formerly constructed object. All objects created in this manner are destroyed upon `la` destruction time. The purpose of helper objects is discussed in Special Considerations - Helper Support.

#### `la.reset_object_address(v, u)`

  Communicates to the archive that the object originally at address u has been moved to address v.

  When an object is loaded to a temporary variable and later moved to another location, this function must be called in order communicate this fact. This permits the archive to properly implement object tracking. Object tracking is required in order to correctly implement serialization of pointers to instances of derived classes.

#### `la.delete_created_pointers()`

  Deletes all objects created by the loading of pointers. This can be used to avoid memory leaks that might otherwise occur if pointers are being loaded and the archive load encounters an exception.

There are archives based on text, binary and XML file formats but all have the above interface. Given that all archives present the same public interface, specifcation of serialization is exactly the same for all archives. Archive classes have other members not mentioned here. However they are related to the internal functioning of the library and are not meant to be called by users of an archive. Implementation of new archives is discussed in New Archives - Implementation.

The existence of the `<<` and `>>` suggests a relationship between archives and C++ i/o streams. Archives are not C++ i/o streams. All the archives included with this system take a stream as an argument in the constructor and that stream is used for output or input. However, this is not a requirement of the serialization functions or the archive interface. It just turns out that the archives written so far have found it useful to base their implementation on streams.

### Archive Models

This library includes various implementations of the Archive concept. An archive is defined by two complementary classes. One is for saving data while the other is for loading it. This library includes a number of archive implementations that are "ready to go" for the most common requirements. These classes implement the archive concept for differing data formats. They can be used "as is" or as a basis for developing one's own particular type of archive. An archive is defined by two complementary classes. One is for saving data while the other is for loading it. To invoke serialization using one of these archives, one or more of the following header files must be included in the code module containing the serialization code.

    // a portable text archive
    boost::archive::text_oarchive // saving
    boost::archive::text_iarchive // loading

    // a portable text archive using a wide character stream
    boost::archive::text_woarchive // saving
    boost::archive::text_wiarchive // loading

    // a portable XML archive
    boost::archive::xml_oarchive // saving
    boost::archive::xml_iarchive // loading

    // a portable XML archive which uses wide characters - use for utf-8 output
    boost::archive::xml_woarchive // saving
    boost::archive::xml_wiarchive // loading

    // a non-portable native binary archive
    boost::archive::binary_oarchive // saving
    boost::archive::binary_iarchive // loading

All of these archives implement the same interface. Hence, it should suffice to describe only one of them in detail. For this purpose we will use the text archive.

    namespace boost {
    namespace archive {

    enum archive_flags {
        no_header = 1,          // suppress archive header info
        no_codecvt = 2,         // suppress alteration of codecvt facet
        no_xml_tag_checking = 4 // suppress checking of xml tags - igored on saving
    };

    } // archive
    } // boost

    namespace boost {
    namespace archive {

    class text_oarchive : ...
    {
        ...
    public:
        ... // implementation of the Saving Archive concept
        text_oarchive(std::ostream & os, unsigned int flags = 0);
        ~text_oarchive();
    };

    } // archive
    } // boost

#### `text_oarchive(std::ostream & os, unsigned int flags = 0);`

  Constructs an archive given an open `stream` as an argument and optional flags. For most applications there will be no need to use flags. Flags are defined by `enum archive_flags` enumerator. Multiple flags can be combined with the `|` operator. By default, archives prepend output with initial data which helps identify them as archives produced by this system. This permits a more graceful handling of the case where an attempt is made to load an archive from an invalid file format. In addition to this, each type of archive might have its own information. For example, native binary archives include information about sizes of native types and endianess to gracefully handle the case where it has been erroneously assumed that such an archive is portable across platforms. In some cases, where this extra overhead might be considered objectionable, it can be suppressed with the `no_header` flag.

  In some cases, an archive may alter (and later restore) the codecvt facet of the stream locale. To suppress this action, include the `no_codecvt` flag.

  XML archives contain nested tags signifying the start and end of data fields. These tags are normally checked for agreement with the object name when data is loaded. If a mismatch occurs an exception is thrown. It's possible that this may not be desired behavior. To suppress this checking of XML tags, use `no_xml_tag_checking` flag.

#### `~text_oarchive();`

  Destructor for an archive. This should be called before the stream is closed. It restores any altered stream facets to their state before the archive was opened.

    namespace boost {
    namespace archive {

    class text_iarchive : ...
    {
        ...
    public:
        ... // implementation of the Loading Archive concept
        text_iarchive(std::istream & is, unsigned int flags = 0);
        ~text_iarchive();
    };

    } //namespace archive
    ) //namespace boost

#### `text_iarchive(std::istream & is, unsigned int flags = 0);`

  Contructs an archive given an open `stream` as an argument and optional flags. If flags are used, they should be the same as those used when the archive was created. Function and usage of flags is described above.

#### `~text_iarchive();`

  Destructor for an archive. This should be called before the stream is closed. It restores any altered stream facets to their state before the the archive was opened.

The `binary_oarchive` and `binary_iarchive` classes are implemented in terms of the more basic `std::streambuf`. So, in addition to the common class interface described above, they include the following constructors:

#### `binary_oarchive(std::streambuf & bsb, unsigned int flags = 0);`

and

#### `binary_iarchive(std::streambuf & bsb, unsigned int flags = 0);`

### Exceptions

All of the archive classes included may throw exceptions. The list of exceptions that might be thrown can be found in section Archive Exceptions of this documentation.

### Character Sets

This library includes two archive classes for XML. The wide character version (`xml_w?archive`) renders its output as UTF-8 which can handle any wide character without loss of information. `std::string` data is converted from multi-byte format to wide character format using the current `locale`. Hence this version should give a fair rendering of all C++ data for all cases. This could result in some unexpected behavior. Suppose an `std::string` is created with the `locale` character set to hebrew characters. On output this is converted to wide characters. On input however, there could be a problem if the `locale` is not set the same as when the archive is created.

The normal character version (`xml_?archive`) renders `std::string` output without any conversion. Though this may work fine for serialization, it may create difficulties if the XML archive is used for some other purpose.

© Copyright Robert Ramey 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)