Serialization

Serialization Wrappers

Binary Objects
Arrays
BOOST_STRONG_TYPEDEF
Collection Sizes
Name-Value Pairs
Composition

Sometimes it convenient to create a temporary object just to support serialization of some underlying data. This permits an archive class to define special handling of this type. The library includes several such types for varying purposes.

Wrappers need to be treated in a special way by some archives, and hence the is_wrapper trait for these wrapper classes is set to true.

Binary Objects

A binary object is just a sequence of bytes stored as raw binary data. This would most likely be used for a large amount of "light weight" data such as a pixel map or embedded binary file. The header file binary_object.hpp includes the constructors:


boost::serialization::binary_object(void * t, size_t size);
boost::serialization::make_binary_object(void * t, size_t size);

which will construct a temporary binary object that can be serialized just like any other object. Its default serialization is to use archive class primitives save_binary and load_binary. Note that it doesn't allocated any storage or create any objects. Its sole purpose is to pass the data size and address as a pair to the archive class.

Arrays

An array is a contiguous sequence of homogeneous data types, such as a builtin C-array, a boost::array<T> or a std::vector<T>. The purpose of this wrapper is to support archive types (such as binary archives) that provide optimized serialization for contiguous sequences of objects of the same type. The header file array.hpp includes the function


template <T>
boost::serialization::make_array(T* t, std::size_t size);

which will construct a temporary array object


template<class T>
class array
{
public:    
    typedef T value_type;
    array(value_type* t, std::size_t s);
    value_type* address() const;
    std::size_t count() const;
};

that can be serialized just like any other object. Its default serialization is to serialize each array element. Note that it doesn't allocated any storage or create any objects. Its sole purpose is to pass the data type, size and address to the archive class. Archive types that can provide optimized implementations for contiguous arrays of homogeneous data types should overload the serialization of array.

`BOOST_STRONG_TYPEDEF`

Another example of a serialization wrapper is the BOOST_STRONG_TYPEDEF template. The serialization libraries uses these to pass particular kinds of integers such as object_id, version, etc. to an archive class. Given that these integers are now distinguishable according to their type, XML archives can apply special handling to these types. For example, a version number is rendered as an XML attribute in the form "version=12". In the absence of any specific override, these types are automatically converted to the underlying integer type so the special overrides used for XML archives aren't needed for other archives.

Collection Sizes

An example of a strong typedef is the collection_size_type in the header file collection_size_type.hpp . This type should be used for serializing the size of a C++ collection, so that the archive can pick the best integral representation for the serialization of collection sizes. This is necessary since, although std::size_t is guaranteed to be an integral type large enough to represent the size of a collection on a specific platform, the archive might want to serialize the size differently than this type. For example, the collection_size_type might be serialized as a variable length integer in a portable binary archive.

Name-Value Pairs

XML archives present a somewhat special case. XML format has a nested structure that maps well to the "recursive class member visitor" pattern used by the serialization system. However, XML differs from other formats in that it requires a name for each class data member. Our goal is to add this information to the class serialization specification while still permiting the the serialization code to be used with any archive.

Our solution is to wrap class members to be serialized in a name-value-pair. This structure is defined in nvp.hpp. It is just a reference to the data member coupled with a pointer to to a const char * which corresponds to the XML name. It implements the default serialization functions for a name-value pair. This default action is to just ignore the item name and serialize the data value in the normal manner. For archive classes that don't make any special provision for name-value pairs, this is the action which will be invoked when the name-value pair is serialized. Hence, wrapping a data value into a name-value pair will have no effect when used with archives which make no special provision for this wrapper.

The xml archive classes contain code similar to:


// special treatment for name-value pairs.
template<class T>
xml_oarchive & operator&(const boost::serialization::nvp<T> & t)
{
    // write an xml start tag
    start_tag(t.name());

    // serialize the data as usual
    *this & t.value();

    // write an xml end tag
    end_tag(t.name());
}

The most obvious and convenient name to assign to as the XML data item name is - surprise! - the name of the C++ class data member. So our serialization code will look like:


ar & make_nvp("my_variable", my_variable);

To simplify typing and enhance readability a macro is defined so we can write:


ar & BOOST_SERIALIZATION_NVP(my_variable);

Similarly there exists a macro definition that permits us to write:


BOOST_SERIALIZATION_BASE_OBJECT_NVP(my_base_class)

Note that these macros must be used in the namespace of the class, and without qualifying the namespace in the argument.

demo_gps.hpp includes NVP wrappers or all data members. demo_xml.cpp saves and loads data to an XML archive. Here is example of the XML Archive corresponding to our tutorial example.

Composition

Wrappers should be designed so that they can be composed as necessary. For example, to pass binary data as a name value pair use:


ar & make_nvp("named_binary_object", make_binary_object(address, size));