Serialization

Archive Classes

Library Interface

Saving

Loading

Details by Type

Primitive Types

Class Types

Base Classes

Pointers

References

Character Sets

Archive Classes

// a portable text archive
boost::archive::text_oarchive(ostream &s) // saving
boost::archive::text_iarchive(istream &s) // loading

// a portable text archive using a wide character stream
boost::archive::text_woarchive(wostream &s) // saving
boost::archive::text_wiarchive(wistream &s) // loading

// a non-portable native binary archive
boost::archive::binary_oarchive(ostream &s) // saving
boost::archive::binary_iarchive(istream &s) // loading

// a portable XML archive
boost::archive::xml_oarchive(ostream &s) // saving
boost::archive::xml_iarchive(istream &s) // loading

// a portable XML archive which uses wide characters - use for utf-8 output
boost::archive::xml_woarchive(wostream &s) // saving
boost::archive::xml_wiarchive(wistream &s) // loading

Archive Library Interface

Saving

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
};

template<class OStream>
class oarchive : ...
{
    ...
public:
    // called to save objects
    template<class T>
    oarchive & operator<<(const T & t);

    template<class T>
    oarchive & operator&(T & t)
    {
        return *this << t;
    }

    void save_binary(const void *address, std::size_t count);

    template<class T>
    register_type(T * t = NULL);

    unsigned int library_version() const;

    struct is_saving {
        typedef mpl::bool_<true> type;
        BOOST_STATIC_CONSTANT(bool, value=true);
    };

    struct is_loading {
        typedef mpl::bool_<false> type;
        BOOST_STATIC_CONSTANT(bool, value=false);
    };

    oarchive(OStream & os, unsigned int flags = 0);

    ~oarchive();
};

template<class T> oarchive & operator<<(const T & t); template<class T> oarchive & operator&(T & t);

Appends an object of type T to the archive. The object may be

• A primitive data type such as int, char, float, etc.
• A class or struct for which a serialize function has been defined.
• A pointer to a serializable object.

void save_binary(const void *address, std::size_t count);

Appends to the archive count bytes found at address.

template<class T> register_type(T * t = NULL);

Appends a sequential integer to the archive. This integer becomes the "key" used to look up the class type when the archive is later loaded. This process is referred to as "class registration". It is only necessary to invoke this function for objects of derived classes which are serialized through a base class pointer. This is explained in detail in Special Considerations - Derived Pointers

unsigned int library_version() const;

Returns 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.

is_saving::type = mpl::bool<true>; is_saving::value= true; is_loading::type = mpl::bool<false>; is_loading::value= false;

These integral constants permit archive attributes to be queried at compiler or execution time. They can used to generate code with boost mpl . For and example showing how these can beused, see the implementation of split_free.hpp.

oarchive(OStream & os, unsigned int flags = 0);

Contructs and archive given an open stream as an argument and optional flags. For most applications there will be no need to use flags. Flags are taken from the following table and 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 in the case where 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 aggreement with the object name when data is loaded. If a mismatch occurs an exception is thrown. Its possible that this may not be desired behavior. To suppress this checking of XML tags, use no_xml_tag_checking flag.

~oarchive();

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

Loading

template<class IStream>
class iarchive : ...
{
    ...
public:
    // called to load objects
    template<class T>
    iarchive & operator>>(T & t);

    template<class T>
    iarchive & operator&(T & t)
    {
        return *this >> t;
    }

    void delete_created_pointers();

    void load_binary(void *address, std::size_t count);

    template<class T>
    register_type(T * t = NULL);

    unsigned int library_version() const;

    struct is_saving {
        typedef mpl::bool_<false> type;
        BOOST_STATIC_CONSTANT(bool, value=false);
    };

    struct is_loading {
        typedef mpl::bool_<true> type;
        BOOST_STATIC_CONSTANT(bool, value=true);
    };

    iarchive(IStream & is, unsigned int flags = 0);

    ~iarchive();
};

} //namespace archive
) //namespace boost

template<class T> iarchive & operator>>(T & t); template<class T> iarchive & operator&(T & t);

Retrieves an object of type T from the archive. The object may be

• A primitive data type such as int, char, float, etc.
• A class or struct for which a serialize function has been defined.
• A pointer to a serializable object.

void load_binary(void *address, std::size_t count);

Retrieves from the archive count bytes and stores them in memory starting at address.

void 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.

template<class T> register_type(T * t = NULL);

Retrieves the next integer from the archive and adds an entry to a table which relates the integer to the type T. When pointers are loaded, this integer is used to indicate which object type should be created. This process is referred to as "class registration". It is only necessary to invoke this function for objects of derived classes which are serialized through a base class pointer. If this function is called during the saving of data to the archive, it should be called during the loading of the data from the archive at the same point in the serialization process. This is explained in detail in Special Considerations - Derived Pointers

unsigned int library_version() const;

Returns 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.

is_saving::type = mpl::bool<false>; is_saving::value= false; is_loading::type = mpl::bool<true>; is_loading::value= true;

These integral constants permit archive attributes to be queried at compiler or execution time. They can used to generate code with boost mpl . For and example showing how these can beused, see the implementation of split_free.hpp.

iarchive(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.

~iarchive();

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

The existence of the << and >> suggest 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.

Details by Type

Primitive Types

The template operators &, <<, and >> of the archive classes described above will generate code to save/load all primitive types to/from an archive. This code will usually just add the data to the archive according to the archive format. For example, a four byte integer is appended to a binary archive as 4 binary bytes while a to a text archive it would be rendered as a space followed by a string representation.

Class Types

Base Classes

template<class Base, class Derived>
Base & base_object(Derived &d);

ar & boost::serialization::base_object<Base>(*this);

Pointers

To properly save and restore an object through a pointer the following situations must be addressed:

1. If the same object is saved multiple times through different pointers, only one copy of the object need be saved.
2. If an object is loaded multiple times through different pointers, only one new object should be created and all returned pointers should point to it.
3. The system must detect the case where an object is first saved through a pointer then the object itself is saved. Without taking extra precautions, loading would result in the creation of multiple copies of the original object. This system detects this case when saving and throws an exception - see below.
4. An object of a derived class may be stored through a pointer to the base class. The true type of the object must be determined and saved. Upon restoration the correct type must be created and its address correctly cast to the base class. That is, polymorphic pointers have to be considered.
5. NULL pointers must be dectected when saved and restored to NULL when deserialized.

Saving a pointer:

1. determine the true type of the object being pointed to.
2. write a special tag to the archive
3. if the object pointed to has not already been written to the archive, do so now

1. read a tag from the archive.
2. determine the type of object to be created
3. if the object has already been loaded, return it's address.
4. otherwise, create a new instance of the object
5. read the data back in using the operators described above
6. return the address of the newly created object.

• Loading the same pointer object multiple times results in only one object being created, thereby replicating the original pointer configuration.
• Structures such as collections of polymorphic pointers, are handled with no special effort on the part of users of this library.

References

Character Sets

© 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)