C++ Boost

Serialization

Archive Concepts


Saving Archive Concept
Loading Archive Concept
Models
Exceptions
Character Sets

Notation

In the following descriptions

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)