Our archives have been factored in to a tree of classes in order to minimize repetition of code. This is shown in the accompanying class diagram. -All input archives should be derived from the following template: + +Any class which fullfills the following requirements will function as +a loading archive. + + +
template<class Archive>
detail::common_iarchive;
-void load(T &t);void load_binary(void *address, std::size_t size);stream as a template parameter rather than simple classes.
+ stream or
+ streambuf
+ as a template parameter rather than simple classes.
Combined with the above, even more issues arise with non-conforming compilers.
The attached class diagram
@@ -241,17 +253,15 @@ EXCEPT for one special case.
BOOT_CLASS_EXPORT is used to instantiate the serialization
- code for the included archives.
+ is, the macro BOOT_CLASS_EXPORT is used
+ to instantiate the serialization code for the included archives.
-#define BOOST_ARCHIVE_CUSTOM_OARCHIVE_TYPES trivial_oarchive
-#define BOOST_ARCHIVE_CUSTOM_IARCHIVE_TYPES trivial_iarchive
+#define BOOST_SERIALIZATION_REGISTER_ARCHIVE(Archive)
-before BOOST_CLASS_EXPORT is invoked for any serializable class.
Failure to do this will not inhibit the program from compiling, linking
and executing properly - except in one case. If an instance of a derived
class is serialized through a pointer to its base class, the program
@@ -259,8 +269,7 @@ will throw an
unregistered_class
exception.
-Only one of the above statements is permitted, However, any number of new archive -classes can be specified as list separated by commas. +
portable_binary_archive.hpp
+To test a new archive, for example, portable binary archives, with the gcc compiler,
+make a header file portable_binary_archive.hpp
and invoke bjam with
-sBOOST_ARCHIVE_LIST=portable_binary_archive.hpp
-This process in encapsulated in the shell script
-run_archive_test whose command line is
+This process in encapsulated in the shell or cmd script
+library_test whose command line is
-run_archive_test <test header file> <toolset> [<boost root>] [<target directory>]
+library_test --toolset=gcc -sBOOST_ARCHIVE_LIST=portable_binary_archive.hpp
polymorphic_iarchive_dispatch.hpp
+polymorphic_iarchive_route.hpp
and
-polymorphic_oarchive_dispatch.hpp.
+polymorphic_oarchive_route.hpp.
As these contain no code specific to the particular implementation archive, they can be used to create
a polymorphic archive implementation from any functioning templated archive implementation.
diff --git a/doc/class_diagram.html b/doc/class_diagram.html
index e6a5f9a5..8d652879 100644
--- a/doc/class_diagram.html
+++ b/doc/class_diagram.html
@@ -52,14 +52,14 @@ common_iarchive<text_iarchive> text_iarchive_impl<text_iarchive> -> polymorphic_iarchive ->
+text_iarchive_impl<text_iarchive> -> polymorphic_iarchive_impl ->
| \ |
| \ |
- | \_____________________________________ |
+ | \_____________________________________ polymorphic_iarchive ->
| \ /
| \ /
| \ /
-text_iarchive -> polymorphic_iarchive_dispatch<text_iarchive_impl<text_iarchive> > ->
+text_iarchive -> polymorphic_iarchive_route<text_iarchive_impl<text_iarchive> > ->
|
|
|
@@ -68,7 +68,7 @@ common_iarchive<text_iarchive> blue
implement loading for a given archive type. (in this case its text archives).
Users include classes in red to load their data from a partcular
@@ -146,11 +146,11 @@ never change. They are in
This class implements the
-Aside from the above, there are a number of issus related to specific platforms.
+Aside from the above, there are a number of issues related to specific platforms.
These are listed in Specific Compiler/Library Issues.
-This will work but may be inconvenient. We don't always know which derived
+
+
-This macro specifies a "Globally Unique IDentifier".
-This is an string which identifies the class to be created when data is loaded.
-Generally a text representation of the class name is sufficient for this purpose,
-but in certain cases it maybe necessary to specify a different string by using
-
-
-Note that the implementation of this functionality depends upon vendor
-specific extensions to the C++ language. So, there is no guarenteed portability
-of programs which use this facility. However, all C++ compilers which
-are tested with boost provide the required extensions. The library
-includes the extra declarations required by each of these compilers.
-It's reasonable to expect that future C++ compilers will support
-these extensions or something equivalent.
-
+
+Note that the implemenation of this functionality requires
+that the
+Note that including
+
+This system has certain implications for placing code in static or shared
+libraries. Placing
+Strictly speaking, export should not be necessary if all pointer serialization
+occurs through the most derived class. However, in order to detect
+what would be catastophic error, the library traps ALL serializations through
+a pointer to a polymorphic which are not exported or otherwise registered.
+So, in practice, be prepared to register or export all classes with one
+or more virtual functions which are serialized through a pointer.
+
+
+Note that the implementation of this functionality depends upon vendor
+specific extensions to the C++ language. So, there is no guarenteed portability
+of programs which use this facility. However, all C++ compilers which
+are tested with boost provide the required extensions. The library
+includes the extra declarations required by each of these compilers.
+It's reasonable to expect that future C++ compilers will support
+these extensions or something equivalent.
+
+For static libraries, this is illustrated by
+For runtime linked libraries this is illustrated by one of the tests:
+
+
+
-Well, not quite.
+However, Writing/Reading different archives simultaneously
+in different tasks is permitted as each archive instance is (almost)
+completely independent from any other archive instance. The only shared
+information are some type tables which have been implemented using a
+lock-free thread-safe
+
+
-There are a couple of global data structures for holding
-information of serializable types. These structures are
-used to dispatch to correct code to handle each pair
-of serializable types and archive types. Since this
-information is shared among all archives, there is
-potential for problems. This has been addressed
-carefully implementing the library so that these
-structures are all initialized before
-
-Well, almost.
-
-With dynamically loaded code - DLLS or Shared Libraries,
-these global data structures can be altered when a library
-is loaded or unloaded. That is, in this case, these
-globa data structures can be altered after
-
-It might not be easy to control this. Is possible that
-some systems may not actually load modules until they
-are actually needed. So even though we think that
-there is not dynamic loading/unloading of such code
-it could be occurring as "help" to manage resources.
-On such systems, access to archive code would have
-to be syncronized with some multi-threading construct
-in order to be functional.
+This singleton implementation guarentees that all of this shared
+information is initialized when the code module which contains
+them is loaded. The serialization library takes care to
+ensure that these data structures are not subsequently
+modified. The only time there could be a problem would
+be if code is loaded/unloaded while another task is
+serializing data. This could only occur for types whose
+serialization is implemented in a dynamically loaded/unload DLL
+or shared library. So if the following is avoided:
+
+Note that if the condition is true, then the macro will generate neither
+code nor data - and the macro can also be used at either namespace,
+class or function scope. When used in a template, the expression x
+will be evaluated at the time the template is instantiated; this is
+particularly useful for validating template parameters.
+
+It is intended that the functioning of © Copyright Robert Ramey 2002-2004.
Distributed under the Boost Software License, Version 1.0. (See
diff --git a/doc/traits.html b/doc/traits.html
index cb127e41..fbc2b717 100644
--- a/doc/traits.html
+++ b/doc/traits.html
@@ -179,7 +179,7 @@ Default tracking traits are:
That is, addresses of addresses are not tracked by default.
© Copyright Robert Ramey 2002-2004 and Matthias Troyer 2006.
Distributed under the Boost Software License, Version 1.0. (See
diff --git a/doc/tutorial.html b/doc/tutorial.html
index b4fd3cdc..8154611f 100644
--- a/doc/tutorial.html
+++ b/doc/tutorial.html
@@ -123,7 +123,7 @@ int main() {
gps_position newg;
{
// create and open an archive for input
- std::ifstream ifs("filename", std::ios::binary);
+ std::ifstream ifs("filename");
boost::archive::text_iarchive ia(ifs);
// read class state from archive
ia >> newg;
diff --git a/doc/void_cast.html b/doc/void_cast.html
index 190964eb..51c0bae3 100644
--- a/doc/void_cast.html
+++ b/doc/void_cast.html
@@ -44,8 +44,8 @@ They are declared in the namespace
template<class Derived, class Base>
const void_cast_detail::void_caster &
void_cast_register(
- const Derived * derived = NULL,
- const Base * base = NULL
+ Derived const * derived = NULL,
+ Base * const base = NULL
)
namespace boost::archive::detail
for all archives present and future.
- polymorphic_iarchive_dispatch<text_iarchive_impl<text_iarchive> >
+ polymorphic_iarchive_route<text_iarchive_impl<text_iarchive> >
polymorphic_iarchive in terms of a specific
- concrete class. Virtual function calls are forwarded to the implementing class. In this example,
+ concrete class. Virtual function calls are routed to the implementing class. In this example,
that implementing class would be text_iarchive_impl.
@@ -158,7 +158,7 @@ never change. They are in namespace boost::archive::detail
polymorphic_iarchive_dispatch<text_iarchive_impl<text_iarchive> >
+ polymorphic_iarchive_route<text_iarchive_impl<text_iarchive> >
diff --git a/doc/codecvt.html b/doc/codecvt.html
index 5ff6c2df..85e9e797 100644
--- a/doc/codecvt.html
+++ b/doc/codecvt.html
@@ -28,7 +28,7 @@ width="277" height="86">
-UTF-8 Codecvt Facet
+utf8_codecvt_facet
diff --git a/doc/contents.html b/doc/contents.html
index a6ea530a..63e34663 100644
--- a/doc/contents.html
+++ b/doc/contents.html
@@ -87,9 +87,10 @@ function initialize() {
@@ -188,7 +189,9 @@ function initialize() {
+
-
extended_type_info
void_cast
- utf8_codecvt_facet
BOOST_STRONG_TYPEDEF
state_saver
smart_cast
BOOST_STATIC_WARNING
+ singleton
+
+
Differences from Boost 1.35
+
+
+
+Differences from Boost 1.34
+
+
+
+Differences from Boost 1.33
+
+
std::streambuf interface.
+ This should result in noticeably faster execution in many cases.
+Differences from Boost 1.32
@@ -66,7 +103,7 @@ at the front of the list of include paths.
-const correctness for save/load operators. Note that this may
produce compile time errors in code which compiled without problem in earlier boost releases.
In most cases the fix is trivial. In other cases, code should be scrutinized to be
- sure that it doesn't use the serializaton system in a way which may introduce subtle bugs in
+ sure that it doesn't use the serialization system in a way which may introduce subtle bugs in
to the program. A fuller explanation of this issue can be found
here.
shared_ptr<T>. This
@@ -78,42 +115,25 @@ at the front of the list of include paths.
needs to load archives created with boost 1.32 libraries, include the above header
before each inclusion of boost/serialization/shared_ptr.hpp.
Differences from Boost 1.33
-
-
-
-std::streambuf interface.
- This should result in noticibly faster execution in many cases.
-Differences from Boost 1.34
-
-
Pending issues
is_virtual_base<T> to automatically
- eliminate redundancy in virtual base class serialization.
new/delete operators.
std::string
and std::wstring contain characters such as
'\0' which cannot be rendered in XML without an escape mechanism. Currently there is
no such escape mechanism implemented.
- std::map
+ std::map
is fixed in this version. Unfortunately, the fix breaks serialization of
std::map for those compilers which do not support
partial template specialization.
-
diff --git a/doc/serialization.html b/doc/serialization.html
index ec9826ae..116cfb3c 100644
--- a/doc/serialization.html
+++ b/doc/serialization.html
@@ -48,12 +48,13 @@ http://www.boost.org/LICENSE_1_0.txt)
serialize
serialize
Primitive Types
@@ -675,8 +677,9 @@ main(){
Note that if the serialization function is split between save and load, both
functions must include the registration. This is required to keep the save
and corresponding load in syncronization.
-Export
+The above will work but may be inconvenient. We don't always know which derived
classes we are going to serialize when we write the code to serialize through
a base class pointer. Every time a new derived class is written we have to
go back to all the places where the base class is serialized and update the
diff --git a/doc/shared_ptr2.html b/doc/shared_ptr2.html
index 3c2ee360..0e831b79 100644
--- a/doc/shared_ptr2.html
+++ b/doc/shared_ptr2.html
@@ -20,7 +20,7 @@ http://www.boost.org/LICENSE_1_0.txt)
@@ -32,7 +32,7 @@ Unfortunately, this way of doing it suffered from some undesirable features
Serialization
-
+ shared_ptr<class T> Revistedshared_ptr<class T> Revisitedshared_ptr.
The shared_ptr interface has been included
in std::tr1 and may someday be included in the standard
- C++ library. An implementation which depends only on the public interface can be guarenteed to
+ C++ library. An implementation which depends only on the public interface can be guaranteed to
function with any other future implementation of shared_ptr.
shared_ptr instances.
- weak_ptr.
diff --git a/doc/special.html b/doc/special.html
index b2e0efed..440e08c8 100644
--- a/doc/special.html
+++ b/doc/special.html
@@ -27,7 +27,6 @@ http://www.boost.org/LICENSE_1_0.txt)
@@ -36,7 +35,9 @@ http://www.boost.org/LICENSE_1_0.txt)
Exporting Class Serialization
-Elsewhere in this manual, we have described
-BOOST_CLASS_EXPORT. This is used to make the serialization library aware
-that code should be instantiated for serialization of a given class even though the
-class hasn't been otherwise referred to by the program. This functionality
-is necessary to implement serialization of pointers through a virtual base
-class pointer. That is, a polymorphic pointer.
-BOOST_CLASS_EXPORT_GUID
-rather than a simple
-BOOST_CLASS_EXPORT.
-
-BOOST_CLASS_EXPORT would usually
-be specified in the same header file as the class declaration to which it
-corresponds. That is, BOOST_CLASS_EXPORT(T)
-is a "trait" of the class T. So a program using this class will look
-something like:
-
-
-
-These headers can be in any order. (In boost versions 1.34
-and earlier, the archive headers had to go before any headers which
-contain
-#include <boost/archive/xml_oarchive.hpp>
-.... // any other archive classes
-#include "my_class.hpp" // which contains BOOST_CLASS_EXPORT(my_class)
-BOOST_CLASS_EXPORT.)
-Any code required to serialize types specified
-by BOOST_CLASS_EXPORT will be
-instantiated for each archive whose header is included. (note that the code
-is instantiated regardless of whether or not it is actually invoked.)
-If no archive headers are included - no code should be instantiated.
-This will permit BOOST_CLASS_EXPORT
-to be a permanent part of the my_class.hpp .
-
-Class Information
By default, for each class serialized, class information is written to the archive.
This information includes version number, implementation level and tracking
@@ -286,7 +238,7 @@ struct my_wrapper {
class my_class {
wchar_t a;
short unsigned b;
- template<<class Archive>
+ template<class Archive>
Archive & serialize(Archive & ar, unsigned int version){
ar & my_wrapper(a);
ar & my_wrapper(b);
@@ -345,13 +297,105 @@ just the value portion of the data is serialized. The name portion is discarded
So by always using name-value pairs, it will
be guarenteed that all data can be serialized to all archive classes with maximum efficiency.
+Exporting Class Serialization
+Elsewhere in this manual, we have described
+BOOST_CLASS_EXPORT.
+Export implies two things:
+
+
+In C++, usage of code not explicitly referred to is implemented via
+virtual functions. Hence, the need for export is implied by the
+usage of a derived class that is manipulated via a pointer or
+reference to it's base class.
+
+BOOST_CLASS_EXPORT in the same
+source module that includes any of the archive class headers will
+instantiate code required to serialize polymorphic pointers of
+the indicated type to the all those archive classes. If no
+archive class headers are included, then no code will be instantiated.
+
+BOOST_CLASS_EXPORT
+macro appear after and the inclusion of any archive
+class headers for which code is to be instantiated.
+So, code that uses BOOST_CLASS_EXPORT
+will look like the following:
+
+This will be true regardless of whether the is part
+of a stand alone executable, a static library or
+a dyanmic or shared library.
+
+#include <boost/archive/text_oarchive.hpp>
+#include <boost/archive/text_oarchive.hpp>
+... // other archives
+
+#include "a.hpp" // header declaration for class a
+BOOST_CLASS_EXPORT(a)
+... // other class headers and exports
+BOOST_CLASS_EXPORT
+in the "a.hpp" header itself as one would do with
+other serialization traits will make it difficult
+or impossible to follow the rule above regarding
+inclusion of archive headers before
+BOOST_CLASS_EXPORT
+is invoked. This is different than other serialization
+traits which would normally be included in same file
+as the class declaration.
+
+BOOST_CLASS_EXPORT
+in library code will have no effect unless archive class headers are
+also included. So when building a library, one should include all headers
+for all the archive classes which he anticipates using. Alternatively,
+one can include headers for just the
+Polymoprhic Archives.
+Also, when making shared libraries, there is currently a restriction
+that only one such library can use BOOST_CLASS_EXPORT
+for any given type. All this will most likely make it inconvenient
+to include BOOST_CLASS_EXPORT
+as part of the header of the class to be serialized. So, the
+best way to use BOOST_CLASS_EXPORT
+is to include it in the same module which implements the class.
+
+DLLS - Serialization and Runtime Linking
Serialization code can be placed in libraries to be linked at runtime. That is,
-code can be placed in DLLS(Windows) or Shared Libraries(*nix).
-Along with the "export" facility, this
-permits a program to written without knowledge of the actual types to be serialized.
-This package doesn't include an example of this technique - but coding would be
-very similar to the example
+code can be placed in DLLS(Windows) Shared Libraries(*nix), or static libraries
+as well as the main executable. As long as
+
+
+BOOST_CLASS_EXPORT
+
+
+is not used, The serialization library imposes no special requirements
+that need be taken into account when distributing code among various modules.
+demo_pimpl.cpp
,
@@ -362,52 +406,91 @@ and
demo_pimpl_A.hpp
-where implementation of serializaton is completely separate
-from the main program.
+where implementation of serializaton is in a static library
+completely separate from the main program.
+
+test_dll_simple
+,
+and
+
+dll_A.cpp
+
+where implementation of serializaton is also completely separate
+from the main program but the code is loaded at runtime. In this
+example, this code is loaded automatically when the program which
+uses it starts up, but it could just as well be loaded and unloaded
+with an OS dependent API call.
+
+Plugins
+In order to implement the library, various facilities for runtime
+manipulation of types are runtime were required. These
+are extended_type_info
+for associating classes with external identifying strings (GUID)
+and void_cast
+for casting between pointers of related types.
+
+To complete the functionality of
+extended_type_info
+the ability to construct and destroy corresponding types has been
+added. In order to use this functionality, one must specify
+how each type is created. This should be done at the time
+a class is exported. So, a more complete example of the code above would be:
+
+
+
+With this in place, one can construct, serialize and destroy
+about which only is know the GUID and a base class.
+
+#include <boost/archive/text_oarchive.hpp>
+#include <boost/archive/text_oarchive.hpp>
+... // other archives
+
+#include "a.hpp" // header declaration for class a
+
+// this class has a default constructor
+BOOST_SERIALIZATION_FACTORY_0(a)
+// as well as one that takes one integer argument
+BOOST_SERIALIZATION_FACTORY_1(a, int)
+
+// specify the GUID for this class
+BOOST_CLASS_EXPORT(a)
+... // other class headers and exports
+Multi-Threading
-The nature of serialization would conflict with multiple thread concurrently
-writing/reading from/to a single open archive. Since each archive is
-independent from ever other one, there should be no problem
-in having multiple open archives from one or more threads.
+The fundamental purpose of serialization would conflict with multiple
+thread concurrently writing/reading from/to a single open archive instance.
+The library implementation presumes that the application avoids such an situtation.
singleton
+
+described elsewhere in this documentation.
main(...)
-is called. From then on they are never altered. So
-there SHOULD be no problem having mulitple archives
-open simultaneously - be it from the same or different
-threads.
-main(...)
-is called. So if a thread is dynamically loading/unloading
-modules which contain serialization code while an
-archive is open there could be problems. Also, if
-such loading/unloading is happening concurrently
-in different threads, there could also be problems.
-
+
+The library should be thread safe.
Optimizations
In performance critical applications that serialize large sets of contiguous data of homogeneous
diff --git a/doc/static_warning.html b/doc/static_warning.html
index 8140c722..d3cf2835 100644
--- a/doc/static_warning.html
+++ b/doc/static_warning.html
@@ -25,7 +25,25 @@ http://www.boost.org/LICENSE_1_0.txt)
-To do.
+
+The header <boost/static_warning.hpp> supplies a single macro
+BOOST_STATIC_WARNING(x), which generates a compile time warning message if
+the integral-constant-expression x is not true.
+BOOST_STATIC_WARNING(x)
+be identical to that of BOOST_STATIC_ASSERT(x)
+except that rather than resulting in a compilation error, it will result in
+a compiler warning. In all other respects it should be the same. So
+for more information on using BOOST_STATIC_WARNING(x)
+consult the documentation for BOOST_STATIC_ASSERT(x)
+here.
+
boost::serialization::nvp,
track_never.
- track_selectivly.
+ track_selectively.
That is addresses of serialized objects are tracked if and only if
one or more of the following is true:
@@ -471,6 +471,34 @@ and template parameters should be assigned according to the following table:
+<<<<<<< .working
+
+IsWrapperis the type a wrapper?mpl::false_
mpl::true_mpl::false_Bitwise serialization
+Some simple classes could be serialized just by directly copying all bits
+of the class. This is, in particular, the case for POD data types containing
+no pointer members, and which are neither versioned nor tracked. Some archives,
+such as non-portable binary archives can make us of this information to
+substantially speed up serialization.
+
+To indicate the possibility of bitwise serialization the type trait defined
+in the header
+file is_bitwise_serializable.hpp
+is used:
+
+is used, and can be specialized for other classes. The specialization
+is made easy by the corresponding macro:
+
+namespace boost { namespace serialization {
+ template
+
+=======
+BOOST_IS_BITWISE_SERIALIZABLE(my_class)
+Bitwise serialization
Some simple classes could be serialized just by directly copying all bits
@@ -497,6 +525,7 @@ is made easy by the corresponding macro:
BOOST_IS_BITWISE_SERIALIZABLE(my_class)
+>>>>>>> .merge-right.r41077