Serialization

Implementation Notes

Partial Function Template Ordering
Character Encoding
Template Invocation syntax
Partial Template Specialization
Specific Compiler/Library Issues GCC 3.X, 4.X GCC 2.95 Intel 8.0 Visual C++ 8.0 Visual C++ 7.1 Visual C++ 7.0 Visual C++ 6.0 Borland 5.64 and 5.51 Comeau 4.3.3 Code Warrior 9.x Code Warrior 8.3 TRU64 Dinkumware Library STLPort 4.5.3

Partial Function Template Ordering

Not all C++ compilers correctly support partial function template ordering (PFTO). For these compilers, the following code will fail to compile:


template<class Archive, class T>
void serialize(
    Archive & ar, 
    T & t, 
    const unsigned int file_version
){
    ...
}

template<class Archive, class T>
void serialize(
    Archive & ar, 
    my_template<T> & t, 
    const unsigned int file_version
){
    ...
}

The serialization library works around this issue by using a different default definition of the first template:


template<class Archive, class T>
void serialize(
    Archive & ar, 
    T & t, 
    const unsigned long int file_version  // Note: change to long
){
    ...
}

Now, the second template is not matched with the first one so there is no PFTO and no compile error. When the serialization library invokes


serialize(ar, t, 0);

the function declaration is first matched against templates with an integer for the third argument. If there is a match, the matching template is instantiated and later invoked. If there is no match, an attempt is made to match other templates by converting arguments to other types. In this case the third argument can be converted to long to match the first template - which is the default. So in this case, the first template will be instantiated and later invoked. We have managed to use function overloading to achieve the same effect as PFTO were it correctly implemented.

This depends upon undefined behavior of a compiler already determined to be non-conforming. In other words, there is no guarantee that this will work on all compilers. If a compiler does not correctly support PFTO and this method cannot be used to workaround it, non-intrusive serialization cannot be supported for that compiler. As of this writing, such a compiler has not been encountered.

It turns out that using this "trick" can create problems with compilers that DO correctly support PFTO. For this reason we define a macro BOOST_PTFO which is defined to be long for non-conforming compilers and nothing for conforming ones. So the default definition is really: The serialization library works around this issue by using a different default definition of the first template:


template<class Archive, class T>
void serialize(
    Archive & ar, 
    T & t, 
    const unsigned BOOST_PFTO int file_version  // Note: change to BOOST_PFTO
){
    ...
}

Character Encoding

The whole question of character encoding combined with wide characters is much more complicated than it would seem to be. The current library defines in 3 formats (text, binary, and XML), wide and narrow characters, an attempts to be portable between compiler libraries. The results of a rather long consideration of all these factors has been to set default encoding according to the following rules.

All text archives (i.e. text_?archive) will produce text output in the current stream locale. Generally this will produce no changes in string data.
To produce binary output with Microsoft compilers, the stream will have to be opened with mode ios::binary. Failure to do so will result in 0x0d characters (carriage-return) characters being removed from the input stream if they are followed by a 0x0a character (line-feed). This could corrupt the input and make the file unreadable. On UNIX systems the ios::binary is not required and is ignored if used.
character XML archives (i.e. xml_oarchive) will produce XML output with characters encoded according to the current stream locale.
wide character XML archives (i.e. xml_woarchive) will produce files encoded in UTF-8.

This character encoding is implemented by changing the locale of the i/o stream used by an archive when the archive is constructed, the stream local is changed back to its original value. This action can be overridden by specifying boost::archive::no_codecvt when the archive is opened. In this case, the stream locale will not be changed by the serialization library.

Note that the code conversion included for wide character text and XML archives could alter std::string data stored in archives. Suppose a normal (multi-byte) character string is written to a wide character stream. Our system uses the current locale to translate it to a wide character string before writing it out. Upon reading, it is translated back to a (multi-byte)string. If the locale on the platform that reads the archive is different than the locale on the platform that wrote the stream, the actual string data may be altered by the serialization process. To avoid this, either avoid usage of locale dependent multi-byte strings or be sure that the locale is set correctly before reading the archive.

To produce wide character text output (i.e. 16 bit characters on Win32 systems), do the following.

Open a wide character stream.
Alter the stream locale to use boost::archive::codecvt_null<OStream::char_type>
Create the archive with the flag no_codecvt.

Naturally, the input process has to be symmetrical.

Partial Template Specialization

Compilers which fail to support partial template specialization will fail to compile the following code. To make this compiler, the const has to be removed.


void f(A const* a, text_oarchive& oa)
{
  oa << a;
}

Template Invocation syntax

Some compilers may not recognize the syntax:


ar.template register_type<T>();

for "registering" derived pointers of polymorphic classes. The actual function prototype is:


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

so that one may write ar.register_type(static_cast<T *>(NULL)) instead of the syntax described above.

Specific Compiler/Library Issues

GCC 3.X, 4.X

GCC versions for Cygwin and MinGW fail to support wide character I/O. So all tests using wide char I/O fail. Note that if wide character I/O support is added with STLPort, all tests complete successfully.
This compiler generates long warning messages related to the usage of non virtual destructors in polymorphic classes. These warnings have been carefully considered and the code that generates these warning has been unchanged. In this case the warning should should be ignored as in certain usages of the library, making the destructors virtual could lead to problems. As an alternative, base class destructors have been made "protected" to address the concerns that motivate these warning messages. When building the serialization library and tests with bjam, these warnings are suppressed. When building one's own applications, these warnings can be suppressed by adding the following to the compiler command line:
```
    -Wno-non-virtual-dtor
    -Wno-ctor-dtor-privacy
    
```

GCC 2.95

All of the above plus:

The serialization library depends on the templated stream implementation to function properly. to function properly. So STLPort must be used to build the library.
Polymorphic archive tests fail.
XML serialization only works with version 1.6x of spirit. In order to build and use this library with this compiler, one must use version 1.6x rather than the latest version shipped with boost. See Release Notes.

Intel C++ 8.0

No known issues. All tests compile and run in debug and release modes.

Visual C++ 8.0

This compiler emits warnings for calls to functions from the standard library which are deemed security risks. The serialization depends upon making some of these calls so programs which use the serialization library will get warning messages. These messages can be suppressed from the command line by including the following switch:


    /wd4996

Visual C++ 7.1

Derivation from an archive class defined in a DLL as described in ... will not work. This is due to the way that VC++ handles templated code with __decl(dllexport) and __decl(dllimport) specifications. Basically, this compiler requires that all the instantiations have the same specification - even though they have different template arguments. The example


demo_portable_iarchive.cpp

would have to reformulated as a library or dll similar to the pre-defined archives in order to function.

This compiler does not have RTTI or exception handling turned on by default. Although they are not strictly necessary to use the serialization package, the example and test program presume that they are enabled. So be sure your command line or IDE settings enable these features if you want to build and run these programs.

This compiler can treat wchar_t as either a short integer or an intrinsic type. If /Zc:wchar_t is specified on the compile command line, wchar_t will be considered an intrinsic type - otherwise it will be treated as a synonym for a 16 bit integer. The library can be used either way - BUT - both the libray AND the application must be compiled with the same switch settings. Note that BJAM includes this switch by default. So if want to use the libraries that BJAM builds, you should include this switch when you compile your own applications.

Using the Visual C++ IDE

The library includes a VC++ 7.1 "Solution" - BoostSerializationLibrary along with of a set of project files - one for each demo and test. Consider the following if you decided to use these configurations.

The projects assume that the tests have been built with bjam using the default locations. This will result in a bin subdirectory within one's main boost directory. Below this there is a whole structure which maintains object and library files according to the type of build. The easiest way to build this is to invoke the runtest script which uses bjam. (see below) If the libraries are not in these locations, the projects will have to be modified accordingly.
There are project configurations for all the combinations of build variants that boost supports. That is for release, debug, static, static multi-threading, etc..
If you want to use/debug the DLL versions of libraries and corresponding tests, alter the project file to define BOOST_ALL_DYN_LINK=1. Note that for the executables to run, the PATH environmental variable will have to include the directories that contain the DLL versions of the boost libraries.
If you have difficulties building your own projects and linking with the boost libraries, compare the project settings of your own projects with the ones here. VC sometimes requires consistent settings between projects and the libraries they use in order to link properly. In particular, check support for exceptions, runtime typing(RTTI), and intrinsic support for wide characters. The standard version of this library presumes that these facilities are enabled. Projects generated by the IDE wizard do not have these features enabled by default.
Frequently when trying to build a project or view project properties, one is presented with a message box with the message "unspecified error". This seems to occur when one changes the build configuration selection. It turns out this can be "fixed" by going to the "Build" menu item, selecting "Configuration Manager" and selecting a build configuration for the project you're working with.
To test that boost libraries are built correctly, one can build and test them the way we do. This entails:
1. downloading a copy of bjam.exe
2. building process_jam_log
3. building compiler_status
4. invoking runtest.bat
This will build the serialization library and run the tests on your system. If there are more than a a couple of test failures, you likely won't be able to get your own projects working. If most of the tests pass, you can be confident that your own projects will work once you get your project settings in sync with those included here.

Visual C++ 7.0

The "pimpl" demo fails to link. Cause and workaround for this is unknown
XML serialization only works with version 1.6x of spirit. In order to build and use this library with this compiler, one must use version 1.6x rather than the latest version shipped with boost. See Release Notes.
This compiler does not support partial template specialization. The implementation of the new shared_ptr serialization depends upon compiler support for partial template specialization. This compiler doesn't implement this feature. In order to serialize shared_ptr<A>, invoke the macro BOOST_SERIALIZATION_SHARED_PTR(A) in the header code.
Lack of support for partial template specialization also creates problems for serialization of std::map. In order to serialize instances of this type include the invocation of BOOST_BROKEN_COMPILER_TYPE_TRAITS_SPECIALIZATION for the key type of the map.

Visual C++ 6.5

all the above issues for Visual C++ 7.0 plus:

Out of line template definitions are not recognized and fail with a confusing error message. To function save/load/serialize member function templates must be defined within the class definition. This feature is essential to demo_pimpl. Hence, this program will fail to compile. In this case the problem can't be worked around and still demonstrate this facility.
This compiler does not support wchar_t as a separate type. It defines wchar_t as an alias for short int. In general things will still function. However certain customization, such as overloading archive operators for saving/loading wide character arrays would produce surprises in this environment.
Under certain circumstances, a program will fail to link with the message: LIN1179 - "invalid or corrupt file: duplicate comdat". According to http://groups.google.com/groups?th=8a05c82c4ffee280 (look for P78) A LNK1179 error occurs when:
- The template class takes at least two arguments.
- The template is used at least two times with identical first and different second arguments.
- The static member variable is of an object type with at least one base class. (In another scenario it also occurred using a member without a base class.)
Working around this in the implementation of the library for this compiler entailed a ridiculous amount of effort. Even so, the effort wasn't entirely successful. With this compiler, this message will still appear under the following conditions:
- When serializing a class with multiple base classes. This problem causes two failure in the test suite. I have been unable to devise a way to work around this.
- Using more than one kind of archive in the same code module. This should be easy to work around in practice.
Code modules exceeding some undetermined size that use the library will fail with fatal error C1204: compiler limit : internal structure overflow. This can be addressed by dividing the module into smaller ones.

Borland 5.64 and 5.51

enum data members cannot be serialized. Conversion to/from integers will work around the problem.
If class serialize functions are not accessible either by making them public or by including friend declarations as described in Class Serialization - Member Function, the will compile but fail at runtime.
Tests using custom extended type which doesn't use RTTI fails. (5.64 only !).
Tests built in release mode fail. This seems to be an issue with the boost test system with this compiler.
XML serialization only works with version 1.6x of spirit. In order to build and use this library with this compiler, one must use version 1.6x rather than the latest version shipped with boost. See Release Notes.

Comeau 4.3.3

This compiler fails to make a DLL with export under windows.
The associated library - libcomo fails when using a codecvt facet. This generates a failure with all wide character archives.
the test_set fails by going into an infinite memory leak.

Code Warrior 9.x

Some tests and demos demos fail - still under investigation

Code Warrior 8.3

all the above issues for Code Warrior 9.x plus:

This compiler only supports templated streams with the static library version.
The above inhibits the build of DLL versions of the library.
Some demos fail - still under investigation

TRU64

All tests and demos pass except for test_variant. Boost Variant doesn't function wih this compiler

Dinkumware Library

Several compilers, including Visual C++ 6.0, use an older dinkumware library. These platforms have several issues:

The dinkumware library shipped with this compiler does not change the locale facet of an i/o stream unless the imbue function is called before the the stream is opened. In order to use this library with this environment to generate UTF-8 files, one cannot depend on the "automatic" setting of locale that archives implement. The stream locale must be set explicitly on the stream before an archive is opened on it. The archive should be opened with the no_codecvt flag. Note this problem will occur on all compilers shipped with this library.
Other issues have been worked around in the file. dinkumware.hpp

STLPort 4.5.3

when built to use dynamic linking versions of C++ runtime code (dynamic) all tests fail to link. This is due to a missing symbol in the stlport library related to custom codecvt facets.
the test_set fails to run correctly. It seems the hashed set iterator doesn't implement the ++ operator correctly. This causes the test to fail by consuming all available memory. Given this, this test is commented out.

Revised 1 November, 2004