Serialization - Code Structure

###  | # Serialization ## Code Structure

Files Included by User Programs

Archive Implementations
Serialization Declarations
Serialization Implementations

Files Which Implement the Library

Archive Development
Archive Internals
Archive Library Code Modules
Dataflow Iterators

This library includes a large number of files. They are organized and classified according to the purposes listed in the above index.

`namespace` of classes and templates is synchronized with the directory in which the file is found. For example, the class declaration

    boost::archive::text_oarchive

is included with the following declaration

    #include <boost/archive/text_oarchive.hpp>

### Files Included by User Programs

Using this library entails including headers listed in this section. It should not be necessary to explicitly include any other header files.

#### Archive Implementations

These header files contain declarations used to save and restore data to each type of archive. Include the archives according to the facilities the code module requires.

boost/archive/archive_exception.hpp
  Exceptions which might be invoked by the library.
boost/archive/binary_iarchive.hpp
  native binary input archive used for loading.
boost/archive/binary_oarchive.hpp
  native binary output archive used for saving.
boost/archive/text_iarchive.hpp
  text input archive used for loading.
boost/archive/text_oarchive.hpp
  text output archive used for saving.
boost/archive/text_wiarchive.hpp
  wide character text input archive used for loading.
boost/archive/text_woarchive.hpp
  wide character text input archive used for saving.
boost/archive/xml_iarchive.hpp
  xml input archive used for loading.
boost/archive/xml_oarchive.hpp
  xml output archive used for saving.
boost/archive/xml_wiarchive.hpp
  wide character xml input archive used for loading.
boost/archive/xml_woarchive.hpp
  wide character xml output archive used for saving.

#### Serialization Declarations

To specify how a type is serialized, one codes templates for serialization functions. In the simplest cases, this does not require the inclusion of any header files for this purpose. In most cases one or more of the following header files will have to be included in order to complete or refine the description of the serializaition implementation for a given class.

boost/serialization/base_object.hpp
  For serialization of base classes.
boost/serialization/nvp.hpp
  To associate a name tag with a serializable object. This is necessary to properly render an xml archive which includes the object name.
boost/serialization/split_free.hpp
  To divide implementation of non-intrusive serialization into separate save and load functions.
boost/serialization/split_member.hpp
  To divide implementation of intrusive serialization into separate save and load functions.
boost/serialization/export.hpp
  For serialization of pointers to derived classes via key export.
boost/serialization/assume_abstract.hpp
  This is just a thin wrapper which permits one to explicitly specify that a particular type is an abstract base class. It is necessary to use this for compilers which don't support the boost type traits implementation of is_abstact.

This group will be required less frequently. The are used to override aspects of the default implementation of the serialization process for specified types.

boost/serialization/version.hpp
  To override the default version index (0) assigned to a class.
boost/serialization/level.hpp
  To override the default implementation level trait for a type.
boost/serialization/tracking.hpp
  To override the default tracking trait for a type.
boost/serialization/type_info_implementation.hpp
  By default, the library uses RTTI, to identify types at runtime. In some cases, E.G. such as a platform which doesn't implement RTTI, this header can be included to permit the override of the default runtime type identification system.

#### Serialization Implementations

This group of headers includes templates which implement serialization for Standard Library or Boost Library templates. Any program which uses these templates can invoke serialization of objects of these types just by including the corresponding header.

By convention these header files are named: boost/serialization/xxx.hpp where xxx is the name of the header file which contains the type to be serialized. For example, the declaration

    #include <boost/serialization/list.hpp>

includes the code to implement serialization of the STL `std::list` type. While

    #include <boost/serialization/shared_ptr.hpp>

includes code to implement serialization of the BOOST `boost::shared_ptr` type. Note that including the serialization header for a type automatically includes the appropriate header of the type to be serialized. As of this writing, the library includes templates of all STL library templates as well as templates for `boost::optional`, `boost::shared_ptr`, and `boost::scoped_ptr`. Presumably, this list will expand with the passage of time.

### Files Which Implement the Library

#### Archive Development

These header files contain declarations for basic types used to create concrete archive types that are made available to users above. Users wishing to make their own type of archive may want to examine these headers to see how the archives included with the libary have been constructed.

boost/archive/basic_archive.hpp
  This file includes declarations for certain types that have to be accounted for in all archive implementations. The serialization system relies on certain special types such as `class_id_type` and others to record information in archives that is required to reconstruct the original data structure. These are handled exactly as any other serializable type. That is, they can be handled as simple primitives such as they are in simple text files, or with special code as they are in xml archives.
boost/archive/basic_text_oprimitive.hpp
boost/archive/basic_text_iprimitive.hpp
  Implementation of serialization of primitive types in terms of character or wide character text streams. This is used in the implementation of text and xml archives. Presumably this would be useful for implementations of other variations of text archives such as user friendly text or windows ini files.
boost/archive/basic_binary_oprimitive.hpp
boost/archive/basic_binary_iprimitive.hpp
  Implementation of serialization of primitive types in terms of character or wide character binary streams.
boost/archive/basic_binary_oarchive.hpp
boost/archive/basic_binary_iarchive.hpp
  Implementation of serialization of all types in terms of character or wide character binary streams. This is factored out separately from the implementation of binary primitives above. This may facilitate the creation of other types of binary archives in the future. It also preserves analogy and symmetry with the rest of the library which aids in understanding.
boost/archive/basic_text_oarchive.hpp
boost/archive/basic_text_iarchive.hpp
boost/archive/basic_xml_oarchive.hpp
boost/archive/basic_xml_iarchive.hpp
  Implementation of serialization of all types in terms of character or wide character text streams. These classes specify archive type specific behavior on a type by type basis. For example, `basic_xml_oarchive.hpp` includes code to guarantee that any object not attached to a name will trap during compile time. On the other hand, `basic_text_oarchive.hpp` contains code to strip out and ignore any names attached to objects.

boost/archive/detail/common_iarchive.hpp
boost/archive/detail/common_oarchive.hpp
  All archive implementations are derived from these header files. They provide the interface to the internal implementation details of the library.

#### Archive Internals

The interface (see Archive Concepts) and implementation are factored out into separate classes to minimize code duplication. These files are found in the directory boost/archive/detail. These are included as necessary by the archive class implementations listed above. This has the unfortunate side effect of making the implementation less transparent. Users should never find it necessary to change these files.

The following discussion is based on the class diagram.

boost/archive/detail/interface_iarchive.hpp
boost/archive/detail/interface_iarchive.hpp
  Here are the declarations and definitions for the archive_concept. This class redirects calls to the archive interface to a function named `save_override` in the most derived archive class.
`save_override` is declared and implemented in each class in the archive hierarchy.

    template<class T>
    void save_override(T & t, BOOST_PFTO int){
        // All for otherwise unhandled types are forwarded to the base class.
        // This emulates behavior for function overloading.
        this->base::save_override(t, 0);
    }
    void save_override(const some_type & t, int){
        // any special handling for some type
        // this will usually entail forwarding some other operation
        // in the most derived class.
        this->This()->...
        // or in one of its parents basic_text_oprimitive
        this->This()->save(static_cast<int>(t));
    }
    ... // other special type handling

Note the usage of Partial Function Template Ordering to permit the correct save implementation to be selected.

#### Archive Library Code Modules

Parts of the library are implemented as library code. All of this code is to be found in libs/serialization/src. in the form of *.cpp. The directory boost/archive/impl contains *.ipp files which implement templates. These templates are instantiated only by archive implementation so are generally not included in user code modules.

The trade offs related to library implementation via pre-compiled code and templated headers are well known. This library uses both. It uses templated headers to generate code to serialize user and primitive types and it uses pre-compiled library code for that part of the code which only depends upon the archive type. Building of the library generates and compiles code for all archives implemented.

- Serialization of user and primitive types runs at top speed. This is a noticeable difference with a previous version of the library which did not use templates for archives.
- Library implementation code that never changes need only be compiled once rather than each time a user's program is recompiled. This can save much development time.
- Headers which solely related to implementation need only be included in the library code modules. This prevents a user program from accidentally depending on an implementation feature of the serialization library.
- In building the library I came to the conclusions that there can arise situations regarding static code/data instantiation that could not be satisfactorily addressed without a code module. Unfortunately, I've forgotten the circumstances which led me to this conclusion.

An example of this is the usage of the spirit library in the library. It takes a long time to compile and includes lots of other files. Having this only in the library is much more convenient that having to include it in every program which uses xml serialization.

#### Dataflow Iterators

In the course of developing this library, it became convenient to make a set of composable iterator adaptors for handling archive text. Applications include escaping and unescaping xml text and implementing to/from base64 conversion among others.

This is a ripe topic in itself. It's touched upon by the boost iterator libraries, View Template Library, and others.

The code for these iterators is really independent of this library. But since it hasn't been and probably won't be reviewed outside of this context. I've left it in a directory local to the serialization library: boost/archive/iterators. These iterators are described in Dataflow Iterators.

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