|
|
Boost-Commit : |
Subject: [Boost-commit] svn:boost r60271 - trunk/libs/serialization/doc
From: ramey_at_[hidden]
Date: 2010-03-06 21:41:14
Author: ramey
Date: 2010-03-06 21:41:12 EST (Sat, 06 Mar 2010)
New Revision: 60271
URL: http://svn.boost.org/trac/boost/changeset/60271
Log:
improve documentation
a) enhance explanation of DLLS
b) include demo for trivial archive and demo (simple log archive)
c) fix explanation of archive derivation and demo (log archive)
Text files modified:
trunk/libs/serialization/doc/archive_reference.html | 153 ++++++++++++++++++++-------------------
trunk/libs/serialization/doc/archives.html | 4
trunk/libs/serialization/doc/class_diagram.html | 72 +++++++++---------
trunk/libs/serialization/doc/contents.html | 4
trunk/libs/serialization/doc/derivation.html | 118 ++++++++++++++---------------
trunk/libs/serialization/doc/headers.html | 60 +++++++++++++--
trunk/libs/serialization/doc/release.html | 19 ++++
trunk/libs/serialization/doc/special.html | 42 ++++++++++
8 files changed, 291 insertions(+), 181 deletions(-)
Modified: trunk/libs/serialization/doc/archive_reference.html
==============================================================================
--- trunk/libs/serialization/doc/archive_reference.html (original)
+++ trunk/libs/serialization/doc/archive_reference.html 2010-03-06 21:41:12 EST (Sat, 06 Mar 2010)
@@ -1,7 +1,7 @@
<!doctype HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!--
-(C) Copyright 2002-4 Robert Ramey - http://www.rrsd.com .
+(C) Copyright 2002-10 Robert Ramey - http://www.rrsd.com .
Use, modification and distribution is subject to 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)
@@ -26,85 +26,96 @@
</table>
<hr>
<dl class="page-index">
- <dt>Implementation
+ <dt>Trivial Archive
+ <dt>More Useful Archive Classes
<dt>Usage
<dt>Testing
<dt>Polymorphic Archives
</dl>
-<h3><a name="implementation">Implementation</a></h3>
+
+<h3><a name="trivial">Trivial Archive</a></h3>
The Archive concept specifies the functions that a
class must implement to in order to be used to serialize
<a href="serialization.html"><strong>Serializable</strong></a> types.
-
-The library implements a family of archives appropriate for different purposes.
-This section describes how they have been implemented and one way one
-can implement his own archive class.
+Our discussion will focus on archives used for saving as the hierarchy is exactly analogous
+for archives used for loading data.
-Our discussion will focus on archives used for loading as the hierarchy is exactly analogous
-for archives used for saving data.
+<h4>Minimum Requirments</h4>
+The simplest class which will model the Archive concept specifies the functions that a
+class will look like:
+
+<pre><code>
+#include <cstddef> // std::size_t
+//////////////////////////////////////////////////////////////
+// class trivial_oarchive
+class trivial_oarchive {
+public:
+ //////////////////////////////////////////////////////////
+ // public interface used by programs that use the
+ // serialization library
+ typedef boost::mpl::bool_<true> is_saving;
+ typedef boost::mpl::bool_<false> is_loading;
+ template<class T> register_type(){}
+ template<class T> trivial_oarchive & operator<<(const T & t){
+ return *this;
+ }
+ template<class T> trivial_oarchive & operator&(const T & t){
+ return *this << t;
+ }
+ void save_binary(void *address, std::size_t count){};
+};
+</code></pre>
+The simplest possible input archive class is analogous to the above.
+In the following discussion, only output archives will be addressed.
+Input archives are exactly symmetrical to output archives.
+<p>
+This archive will compile and execute with any types which implement the
+Serializable concept.
+For an example see
+<a href="../example/demo_trivial_archive.cpp" target="demo_trivial_archive">
+<code style="white-space: normal">demo_trivial_archive.cpp</code></a>.
+Of course this program won't produce any output as it is. But it provides
+the starting point for a simple class which can be used to log formated
+output. See the implementation of a <a href="simple_log.html">simple
+log archive</a> to how this has been done.
+
+<h3><a name="implementation">More Useful Archive Classes</a></h3>
+The above example is fine as far as it goes. But it doesn't implement
+useful features such as serialization of pointers, class versioning
+and others. This library implements a family of full featuared archive
+classes appropriate for a variety of purposes.
<p>
Our archives have been factored in to a tree of classes in order to minimize
repetition of code. This is shown in the accompanying
<a target="class_diagram" href="class_diagram.html">class diagram</a>.
-Any class which fullfills the following requirements will function as
-a loading archive.
-
-
-<h4>Minimum Requirments</h4>
-The archive class is derived from:
-<pre><code>
-template<class Archive>
-detail::common_iarchive;
-</code></pre>
-An instance of the this template handles all the "bookkeeping" associated
-with serialization. In order to be a functional only the following additional
-functions <strong>must</strong> be declared:
-<dl>
-<dt><h4><code>void load(T &t);</code></h4></dt>
-<dd>
-This function must be implemented for all primitive data types. This can be
-accomplished through the use of a member template or explicit declarations
-for all primitive types.
-</dd>
-
-<dt><h4><code>void load_binary(void *address, std::size_t size);</code></h4></dt>
-<dd>
-This function should <code style="white-space: normal">size</code> bytes from the archive, and
-copy them in to memory starting at address <code style="white-space: normal">address</code>.
-</dd>
-
-<dt><h4><code>friend class boost::archive::load_access;</code></h4></dt>
-<dd>
-In addition, such a class <strong>must</strong> provide a the following
-friend declaration grant access to the core serialization library to the functions
-of this class.
-</dd>
-
-</dl>
-
-So, the most trivial implementation of an input archive would look like this:
+Any class which fullfills the following requirements will fit into
+this hierarchy and implement all the features we require. Deriving from
+the base class <a href="../../../boost/archive/detail/common_oarchive.hpp" target="common_oarchive_hpp">
+common_oarchive.hpp</a> provides all features we desire which
+are missing from trivial_oarchive above.
<pre><code>
-<a href="../../../boost/archive/detail/common_iarchive.hpp" target="common_iarchive_hpp">
-#include <boost/archive/detail/common_iarchive.hpp>
+<a href="../../../boost/archive/detail/common_oarchive.hpp" target="common_oarchive_hpp">
+#include <cstddef> // std::size_t
+#include <boost/archive/detail/common_oarchive.hpp>
</a>
/////////////////////////////////////////////////////////////////////////
-// class trivial_iarchive - read serialized objects from a input text stream
-class trivial_iarchive :
- public boost::archive::detail::common_iarchive<trivial_iarchive>
+// class complete_oarchive
+class complete_oarchive :
+ public boost::archive::detail::common_oarchive<complete_oarchive>
{
// permit serialization system privileged access to permit
// implementation of inline templates for maximum speed.
- friend class boost::archive::load_access;
+ friend class boost::archive::save_access;
- // member template for loading primitive types.
- // Override for any types/templates that special treatment
+ // member template for saving primitive types.
+ // Specialize for any types/templates that special treatment
template<class T>
- void load(T & t);
+ void save(T & t);
public:
//////////////////////////////////////////////////////////
@@ -112,28 +123,24 @@
// serialization library
// archives are expected to support this function
- void load_binary(void *address, std::size_t count);
+ void save_binary(void *address, std::size_t count);
};
-
</code></pre>
-The simplest possible output archive class is exactly analogous to the above.
-In the following discussion, only input archives will be addressed.
-Output archives are exactly symmetrical to input archives.
-<p>
-Given a suitable definitions of <code style="white-space: normal">load</code>
-and <code style="white-space: normal">load_binary</code>,
+
+Given a suitable definitions of <code style="white-space: normal">save</code>
+and <code style="white-space: normal">save_binary</code>,
any program using serialization with a conforming C++ compiler should compile
and run with this archive class.
<h4>Optional Overrides</h4>
-The <code style="white-space: normal">detail::common_iarchive</code> class contains
+The <code style="white-space: normal">detail::common_oarchive</code> class contains
a number of functions that are used by various parts of the serialization library
to help render the archive in a particular form.
<dl>
-<dt><h4><code>void load_start()</code></h4></dt>
+<dt><h4><code>void save_start()</code></h4></dt>
<dd>
<strong>Default</strong>:Does nothing.<br>
<strong>Purpose</strong>:To inject/retrieve an object name into the archive. Used
@@ -141,7 +148,7 @@
</dd>
<p>
-<dt><h4><code>void load_end()</code></h4></dt>
+<dt><h4><code>void save_end()</code></h4></dt>
<dd>
<strong>Default</strong>:Does nothing.<br>
<strong>Purpose</strong>:To inject/retrieve an object name into the archive. Used
@@ -153,7 +160,7 @@
<dd>
<strong>Default</strong>:Does nothing.<br>
<strong>Purpose</strong>:Called <strong>each time</strong> user data is saved.
-It's not called when archive book keeping data is saved. This is used by XML archives
+It's not called when archive bookkeeping data is saved. This is used by XML archives
to determine when to inject a ">" character at end of XML header. XML output archives
keep their own internal flag indicating that data being written is header data. This
internal flag is reset when an object start tag is written. When
@@ -165,12 +172,12 @@
<p>
<dt><h4><code>
template<class T>
-void load_override(T & t, int);
+void save_override(T & t, int);
</code></h4></dt>
<dd>
-<strong>Default</strong>:Invokes <code style="white-space: normal">archive::load(Archive & ar, t)</code><br>
+<strong>Default</strong>:Invokes <code style="white-space: normal">archive::save(Archive & ar, t)</code><br>
This is the main entry into the serialization library.<br>
-<strong>Purpose</strong>:This can be overridden in cases where the data is to be written
+<strong>Purpose</strong>:This can be specialized in cases where the data is to be written
to the archive in some special way. For example, XML archives implement special handling for
name-value pairs by overriding this function template for name-value pairs.
This replaces the default name-value pair handling, which is just to throw away the name,
@@ -188,14 +195,14 @@
The serialization library injects bookkeeping data into the serialization archive.
This data includes things like object ids, version numbers, class names etc. Each
of these objects is included in a wrapper so that the archive class can override the
-implementation of <code style="white-space: normal">void load_override(T & t, int);</code>.
+implementation of <code style="white-space: normal">void save_override(T & t, int);</code>.
For example, in the XML archive, the override for this type renders an object_id equal to 23 as
"object_id=_23". The following table lists the types defined in the
<code style="white-space: normal">boost::archive namespace</code>
used internally by the serialization library:
<p>
<table border>
-<tr><th align=left>type</th><th align=left><code style="white-space: normal">default<br>serialed as</code></th>
+<tr><th align=left>type</th><th align=left><code style="white-space: normal">default<br>serialized as</code></th>
<tr><td><code style="white-space: normal">version_type</code></td><td><code style="white-space: normal">unsigned int</code></td>
<tr><td><code style="white-space: normal">object_id_type</code></td><td><code style="white-space: normal">unsigned int</code></td>
<tr><td><code style="white-space: normal">object_id_reference_type</code></td><td><code style="white-space: normal">unsigned int</code></td>
@@ -207,7 +214,7 @@
</table>
<p>
All of these are associated with a default serialization defined in terms of primitive types
-so it isn't a requirement to define <code style="white-space: normal">load_override</code>
+so it isn't a requirement to define <code style="white-space: normal">save_override</code>
for these types.
<p>
These are defined in
Modified: trunk/libs/serialization/doc/archives.html
==============================================================================
--- trunk/libs/serialization/doc/archives.html (original)
+++ trunk/libs/serialization/doc/archives.html 2010-03-06 21:41:12 EST (Sat, 06 Mar 2010)
@@ -102,7 +102,7 @@
For more information, see <a target="detail" href="implementation.html#tempatesyntax">Template Invocation syntax</a>
</dd>
<dt><h4><code>
- sa.library_version()
+ sa.get_library_version()
</code></h4></dt>
<dd>
Returns an unsigned integer containing the current version number of the serialization
@@ -172,7 +172,7 @@
For more information, see <a target="detail" href="implementation.html#tempatesyntax">Template Invocation syntax</a>
</dd>
<dt><h4><code>
- la.library_version()
+ la.get_library_version()
</code></h4></dt>
<dd>
Returns an unsigned integer containing the version number of the serialization
Modified: trunk/libs/serialization/doc/class_diagram.html
==============================================================================
--- trunk/libs/serialization/doc/class_diagram.html (original)
+++ trunk/libs/serialization/doc/class_diagram.html 2010-03-06 21:41:12 EST (Sat, 06 Mar 2010)
@@ -1,4 +1,4 @@
-<!doctype HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<!doctype HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<!--
(C) Copyright 2002-4 Robert Ramey - http://www.rrsd.com .
Use, modification and distribution is subject to the Boost Software
@@ -29,136 +29,136 @@
<pre><code>
-basic_iarchive ->
+basic_oarchive ->
|
|
- | interface_iarchive<text_iarchive> ->
+ | interface_oarchive<text_oarchive> ->
| /
| /
| _________/
| /
| /
| /
-common_iarchive<text_iarchive> ->
+common_oarchive<text_oarchive> ->
|
|
-<font color="blue">basic_text_iarchive<text_iarchive></font> ->
+<font color="blue">basic_text_oarchive<text_oarchive></font> ->
|
|
- | <font color="blue">basic_text_iprimitive<basic_istream></font> ->
+ | <font color="blue">basic_text_oprimitive<basic_ostream></font> ->
| /
| /
- | _________/ interface_iarchive<polymorphic_iarchive> ->
+ | _________/ interface_oarchive<polymorphic_oarchive> ->
| / |
| / |
| / |
-<font color="blue">text_iarchive_impl<text_iarchive></font> -> polymorphic_iarchive_impl ->
+<font color="blue">text_oarchive_impl<text_oarchive></font> -> polymorphic_oarchive_impl ->
| \ |
| \ |
- | \_____________________________________ <font color="red">polymorphic_iarchive</font> ->
+ | \_____________________________________ <font color="red">polymorphic_oarchive</font> ->
| \ /
| \ /
| \ /
-<font color="red">text_iarchive</font> -> polymorphic_iarchive_route<text_iarchive_impl<text_iarchive> > ->
+<font color="red">text_oarchive</font> -> polymorphic_oarchive_route<text_oarchive_impl<text_oarchive> > ->
|
|
|
- <font color="red">polymorphic_text_iarchive</font> ->
+ <font color="red">polymorphic_text_oarchive</font> ->
</code></pre>
-This diagram shows the relationship between the various classes that implement loading (input
-serialization) for text files. The hierachy and organization is similar for saving and for
+This diagram shows the relationship between the various classes that implement saving (output
+serialization) for text archives. The hierachy and organization is similar for loading and for
other types of archives as well. In the diagram, classes written in <font color="blue">blue</font>
-implement loading for a given archive type. (in this case its text archives).
-Users include classes in <font color="red">red</font> to load their data from a partcular
+implement saving for a given archive type. (in this case its text archives).
+Users include classes in <font color="red">red</font> to save their data from a partcular
type of archive. Other classes whose names are in black implement the library and should
never change. They are in <code>namespace boost::archive::detail</code>
<dl>
<dt><code>
- basic_iarchive
+ basic_oarchive
</code></dt>
<dd>
Implements the core library functions for class export, versioning, and object tracking. It is compiled
into the library as it has no template parameters.
</dd>
<p><dt><code>
- interface_iarchive<text_iarchive>
+ interface_oarchive<text_oarchive>
</code></dt>
<dd>
A class that declares the standard archive interface. This has been factored out so that it
- can be used as a base class for <code style="white-space: normal">polymorphic_iarchive</code>
+ can be used as a base class for <code style="white-space: normal">polymorphic_oarchive</code>
as well as for archive implementations.
<p><dt><code>
- common_iarchive<text_iarchive>
+ common_oarchive<text_oarchive>
</code></dt>
<dd>
The function of this class is to make the connection between the virtual function
- interface used by <code>basic_iarchive</code> and the template interface used by archive
+ interface used by <code>basic_oarchive</code> and the template interface used by archive
class implementations.
<p><dt><code>
- basic_text_iarchive<text_iarchive>
+ basic_text_oarchive<text_oarchive>
</code></dt>
<dd>
- Implements the basic functionality for simple text archives. The primitive load functions have been
+ Implements the basic functionality for simple text archives. The primitive save functions have been
factored out so it can be used in other text based archives like XML archives.
<p><dt><code>
- basic_text_iprimitive<basic_istream>
+ basic_text_oprimitive<basic_ostream>
</code></dt>
<dd>
- Implements the save overloads for all primitive types. This is a template with a parameter
+ Implements the save oversaves for all primitive types. This is a template with a parameter
which describes the stream.
<p><dt><code>
- text_iarchive_impl<text_iarchive>
+ text_oarchive_impl<text_oarchive>
</code></dt>
<dd>
Inherits from the above two classes to implement text archives.
</dd>
<p><dt><code>
- text_iarchive
+ text_oarchive
</code></dt>
<dd>
- This is just a short hand for <code style="white-space: normal">text_iarchive_impl<text_iarchive></code> .
+ This is just a short hand for <code style="white-space: normal">text_oarchive_impl<text_oarchive></code> .
We can't use <code style="white-space: normal">typedef</code> because a
<code style="white-space: normal">typedef</code> can't refer to it self in its definition.
This is the class name that is used to serialize to a text archive.
</dd>
<p><dt><code>
- interface_iarchive<polymorphic_iarchive>
+ interface_oarchive<polymorphic_oarchive>
</code></dt>
<dd>
Same template as above. However, this time the Archive parameter refers to the polymorphic archive
with a virtual function interface rather than that the template interface that
- <code style="white-space: normal">common_iarchive</code> uses.
+ <code style="white-space: normal">common_oarchive</code> uses.
<p><dt><code>
- polymorphic_iarchive
+ polymorphic_oarchive
</code></dt>
<dd>
- A class with a list of virtual <code style="white-space: normal">load(T &t)</code>
+ A class with a list of virtual <code style="white-space: normal">save(T &t)</code>
for all primitive types T. This is the class that is used to do pre-compile serialization of classes
for all archives present and future.
<p><dt><code>
- polymorphic_iarchive_route<text_iarchive_impl<text_iarchive> >
+ polymorphic_oarchive_route<text_oarchive_impl<text_oarchive> >
</code></dt>
<dd><p>
- This class implements the <code style="white-space: normal">polymorphic_iarchive</code> in terms of a specific
+ This class implements the <code style="white-space: normal">polymorphic_oarchive</code> in terms of a specific
concrete class. Virtual function calls are routed to the implementing class. In this example,
- that implementing class would be text_iarchive_impl.
+ that implementing class would be text_oarchive_impl.
<p><dt><code>
- polymorphic_text_iarchive
+ polymorphic_text_oarchive
</code></dt>
<dd>
this is just a typedef so we can write polymorphic_text_archive rather than
- <code style="white-space: normal">polymorphic_iarchive_route<text_iarchive_impl<text_iarchive> ></code>
+ <code style="white-space: normal">polymorphic_oarchive_route<text_oarchive_impl&'t;text_oarchive> ></code>
</dl>
<hr>
Modified: trunk/libs/serialization/doc/contents.html
==============================================================================
--- trunk/libs/serialization/doc/contents.html (original)
+++ trunk/libs/serialization/doc/contents.html 2010-03-06 21:41:12 EST (Sat, 06 Mar 2010)
@@ -232,7 +232,8 @@
</dl></div></dd>
<dt><img style="display:none" src="plus.gif" id="archive_reference"><a target="detail" href="archive_reference.html">Archive Class Reference</a>
<dd><div id="archive_reference_detail"><dl class="page-index">
- <dt><img style="display:none" src="dot.gif"><a target="detail" href="archive_reference.html#implementation">Implementation</a>
+ <dt><img style="display:none" src="dot.gif"><a target="detail" href="archive_reference.html#trivial">Trivial Archive</a>
+ <dt><img style="display:none" src="dot.gif"><a target="detail" href="archive_reference.html#implementation">More Useful Archive Classes</a>
<dt><img style="display:none" src="dot.gif"><a target="detail" href="archive_reference.html#usage">Usage</a>
<dt><img style="display:none" src="dot.gif"><a target="detail" href="archive_reference.html#testing">Testing</a>
<dt><img style="display:none" src="dot.gif"><a target="detail" href="archive_reference.html#polymorphic">Polymorphic Archives</a>
@@ -282,6 +283,7 @@
<dt><img style="display:none" src="dot.gif"><a target="detail" href="shared_ptr.html">Template serialization - <code>shared_ptr<class T></code></a>
<dt><img style="display:none" src="dot.gif"><a target="detail" href="shared_ptr2.html"><code>shared_ptr<class T></code>Revisited</a>
<dt><img style="display:none" src="dot.gif"><a target="detail" href="pimpl.html">PIMPL</a>
+ <dt><img style="display:none" src="dot.gif"><a target="detail" href="simple_log.html">A Simple Logging Archive Class</a>
<dt><img style="display:none" src="dot.gif"><a target="detail" href="derivation.html">Derivation from an Existing Archive Class</a>
</dl></div></dd>
<dt><img style="display:none" src="plus.gif" id="otherclasses">Other Classes
Modified: trunk/libs/serialization/doc/derivation.html
==============================================================================
--- trunk/libs/serialization/doc/derivation.html (original)
+++ trunk/libs/serialization/doc/derivation.html 2010-03-06 21:41:12 EST (Sat, 06 Mar 2010)
@@ -26,42 +26,48 @@
</table>
<hr>
<dl class="page-index">
- <dt>Portable Binary Archives
- <dt>Fast Binary Archives
</dl>
-<a name=portable_archives>
-<h3>Portable Binary Archives</h3>
+<h3>Log Archive</h3>
It may happen that one wants to create a new archive class by derivation from one
of the included ones. Included is a sample program that shows how to derive a
new archive from one of the ones included with the library. The first example is
-demo_portable_archive.cpp.
-This binary archive save/loads integers in a portable format. To this end
-it is derived from the native binary archive and the save/load functions for
-integers are overridden with special versions which convert to big endian
-format if necessary. It also implements an exception for the case where an
-integer saved on one platform is too large for the platform which is loading
-the archive. This example doesn't address floating point types.
-This examples illustrates several issues that have to be addressed when doing
-something like this. The discussion below refers to the output archive only but it
-applies equally to input archives as well.
+<a href="../example/demo_log.cpp" target="demo_log_cpp">
+demo_log.cpp</a>.
+<p>
+This derivation from the xml archive writes output in xml without the extra
+information required to read the data back into the application. It might be
+used to export one's data as simple xml for other applications or for logging
+data while debugging.
+<p>
+To this end it is derived from the included xml archive and the save functions for
+some types are specialized for this application.
+<p>
+The serialization library is
+implemented using the <b>C</b>uriously <b>R</b>ecurring <b>T</b>emplate
+<b>P</b>attern (<b>CRTP</b>). Also, all common code is factored out into
+separate modules to minimize code repetition. This makes derivation from
+an existing archive less straight forward than it would otherwise be.
+<p>
+This example illustrates several issues that have to be addressed when doing
+something like this
<ol>
- <li><i>It is derived from</i> <code style="white-space: normal">binary_oarchive_impl<portable_binary_oarchive></code>
- <b>NOT</b> <code style="white-space: normal">binary_oarchive</code> <br>
+ <li><i>It is derived from</i> <code style="white-space: normal">xml_oarchive_impl<log_archive></code>
+ <b>NOT</b> <code style="white-space: normal">xml_oarchive</code> <br>
As described in the comments in
-binary_oarchive.hpp.
-<code style="white-space: normal">binary_oarchive</code> really a shorthand name for
-<code style="white-space: normal">binary_oarchive_impl<binary_oarchive></code>. So we should derive
-from <code style="white-space: normal">binary_oarchive_impl<portable_binary_oarchive></code> rather
-than <code style="white-space: normal">binary_oarchive</code>.
-<pre><code>
-class portable_binary_oarchive :
- // don't derive from binary_oarchive !!!
- public binary_oarchive_impl<portable_binary_oarchive>
+xml_oarchive.hpp.
+<code style="white-space: normal">xml_oarchive</code> really a shorthand name for
+<code style="white-space: normal">xml_oarchive_impl<xml_oarchive></code>. So we should derive
+from <code style="white-space: normal">xml_oarchive_impl<log_archive></code> rather
+than <code style="white-space: normal">xml_oarchive</code>.
+<pre><code>
+class log_archive :
+ // don't derive from xml_oarchive !!!
+ public xml_oarchive_impl<log_archive>
{
...
</code></pre>
- <li><i>Note the</i> <code style="white-space: normal">portable_binary_oarchive</code> <i>between the</i> <>
+ <li><i>Note the</i> <code style="white-space: normal">log_archive</code> <i>between the</i> <>
This is required so that base classes can downcast their <code style="white-space: normal">this</code> pointer
to the most derived class. This is referred to as <b>C</b>uriously <b>R</b>ecurring
<b>T</b>emplate <b>P</b>attern (<b>CRTP</b>) [11].
@@ -70,24 +76,28 @@
This can be done by making members public or by including friend declarations for
the base classes.
<pre><code>
- typedef portable_binary_oarchive derived_t;
- friend class detail::common_oarchive<derived_t>;
- friend class basic_binary_oarchive<derived_t>;
- friend class basic_binary_oprimitive<
- derived_t,
- std::ostream::char_type,
- std::ostream::traits_type
- >;
+ friend class detail::common_oarchive<log_archive>;
+ friend class basic_xml_oarchive<log_archive>;
friend class boost::serialization::save_access;
</code></pre>
+
+ <li><i></i>Reread <a target="detail" href="headers.html#archiveinternals">Archive Internals</a>.
+This describes the class hierarchy so that you know what to override.
+ <li><i>Note the usage of PFTO.</i> Some compilers fail to provide support for
+partial function template ordering. The serialization library works around by
+using <a target="detail" href="implementation.html#functiontemplateordering">
+<b>P</b>artial <b>F</b>unction <b>T</b>emplate <b>O</b>rdering</a> in several places.
+In archive classes, this takes
+. This is done
+in several places, including the archive classes themselves.
<li><i>Base class functions will usually need to be explicitly invoked</i>
-We commonly overload the function name <code style="white-space: normal">save</code> for saving primitives.
-This is very convenient. Usage of a function name in a derived class
+We commonly specialize the function name <code style="white-space: normal">save_override</code>
+for saving primitives. Usage of a function name in a derived class
"hides" similarly named functions of the base class. That is,
function name overloading doesn't automatically
include base classes. To address this, we can use:
<pre><code>
- using binary_oarchive_impl<derived_t>::save;
+ using xml_oarchive_impl<derived_t>::save;
void save(const unsigned int t);
...
</code></pre>
@@ -97,13 +107,13 @@
// default fall through for any types not specified here
template<class T>
void save(const T & t){
- binary_oarchive_impl<derived_t>::save(t);
+ xml_oarchive_impl<derived_t>::save(t);
}
void save(const unsigned int t);
...
</code></pre>
so it's what I use.
- <li><i>Template definitions of base classes may have to be included.</i>
+ <li><i>Template definitions of base classes may have to be explicitly instantiated.</i>
The demo includes
<pre><code>
// explicitly instantiate for this type of binary stream
@@ -115,44 +125,30 @@
Base classes using <b>CRTP</b> must be templates with a parameter corresponding to
the most derived class. As presented here, this class doesn't qualify, so
it cannot be used as a base class. In order to derive further from this class,
-it would have to be reorganized along the lines of the original <code style="white-space: normal">binary_oarchive</code>.
+it would have to be reorganized along the lines of the original <code style="white-space: normal">xml_oarchive</code>.
Specifically, it would look something like:
<pre><code>
template<class Archive>
-class portable_binary_oarchive_impl :
- // don't derive from binary_oarchive !!!
- public binary_oarchive_impl<Archive>
+class log_archive_impl :
+ // don't derive from xml_oarchive !!!
+ public xml_oarchive_impl<Archive>
{
...
);
// do not derived from this class !!!
-class portable_binary_oarchive :
- public portable_binary_oarchive_impl<portable_binary_oarchive>
+class log_archive :
+ public log_archive_impl<log_archive>
{
public:
- portable_binary_oarchive(std::ostream & os, unsigned int flags = 0) :
- portable_binary_oarchive_impl<binary_oarchive>(os, flags)
+ log_archive(std::ostream & os, unsigned int flags = 0) :
+ log_archive_impl<xml_oarchive>(os, flags)
{}
};
</code></pre>
</ol>
-<a name=fast_archives>
-<h3>Fast Binary Archives</h3>
-The second example
-demo_fast_archive.cpp.
-is similar to the first one. The difference is that it intercepts the serialization before
-the default serialization is invoked. In this case we want to replace the default
-serialization of C arrays of integers with a faster one. The default version
-will invoke serialization of each element of the array. If its an array of
-integers, and we're not concerned with the archive being portable to another platform
-we can just save/load the whole array as a binary string of bytes. This should
-be faster than the default element by element method.
-<p>
-The same considerations that applied when overriding the the save/load of primitives
-above apply here, and the code is very similar.
<hr>
<p><i>© Copyright Robert Ramey 2002-2004.
Distributed under the Boost Software License, Version 1.0. (See
Modified: trunk/libs/serialization/doc/headers.html
==============================================================================
--- trunk/libs/serialization/doc/headers.html (original)
+++ trunk/libs/serialization/doc/headers.html 2010-03-06 21:41:12 EST (Sat, 06 Mar 2010)
@@ -1,4 +1,4 @@
-<!doctype HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<!doctype HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!--
(C) Copyright 2002-4 Robert Ramey - http://www.rrsd.com .
@@ -207,7 +207,7 @@
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.
<p>
-By convention, these header files are named:
+By convention' these header files are named:
boost/serialization/xxx.hpp
@@ -303,7 +303,7 @@
<dt><a target="basic_text_oarchive" href="../../../boost/archive/basic_text_oarchive.hpp">
boost/archive/basic_text_oarchive.hpp
</a>
-<dt><a target="basic_text_iarchive" href="../../../boost/archive/basic_text_iarchive.hpp">
+<dt><a target="basic_te't_iarchive" href="../../../boost/archive/basic_text_iarchive.hpp">
boost/archive/basic_text_iarchive.hpp
</a>
</dt>
@@ -337,11 +337,55 @@
<a name="archiveinternals">
<h4>Archive Internals</h4>
-The header files in the directory
-<a target="basic_xml_iarchive" href="../../../boost/archive/detail">boost/archive/detail</a>
-implement parts of the library itself. The should never need to be changed by users
+
+The interface (see <a target="detail" href="archives.html">Archive Concepts</a>)
+and implementation are factored out into separate classes to minimize code duplication.
+
+These files are found in the directory
+<a target="boost_archive_detail" href="../../../boost/archive/detail">boost/archive/detail</a>.
+These are included as necessary by the archive class implemenations listed above.
+This has the unfortunate side effect of making the implementation less transparent.
of the library in order to implement either a class serialization or a new
-archive type.
+archive type. Users should never find it necessary to change these files.
+<p>
+The following discussion is based on the
+<a target="class_diagram" href="class_diagram.html">class diagram</a>.
+<p>
+<dt><a target="interface_iarchive" href="../../../boost/archive/detail/interface_iarchive.hpp">
+boost/archive/detail/interface_iarchive.hpp</a>
+<dt><a target="interface_iarchive" href="../../../boost/archive/detail/interface_iarchive.hpp">
+boost/archive/detail/interface_iarchive.hpp</a>
+<dd>
+Here are the declarations and definitions which for the
+archive_concept. This class redirects calls to the
+archive interface to a function named <code>save_override</code> in the most derived
+archive class.
+</dd>
+<code>save_override</code> is declared and implemented in each class in
+the archive hierarchy.
+
+<pre><code>
+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
+</code></pre>
+
+Note the usage of
+<a target="detail" href="implementation.html#functiontemplateordering">Partial Function Template Ordering</a>
+to permit the correct save implementation to be selected.
+</dd>
<a name="codemodules">
<h4>Archive Library Code Modules</h4>
@@ -381,7 +425,7 @@
<h4>Dataflow Iterators</h4>
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, implementing to/from base64 conversion among
+escaping and unescaping xml text, implementi'g to/from base64 conversion among
others.
<p>
This is a ripe topic in itself. Its touched upon by the
Modified: trunk/libs/serialization/doc/release.html
==============================================================================
--- trunk/libs/serialization/doc/release.html (original)
+++ trunk/libs/serialization/doc/release.html 2010-03-06 21:41:12 EST (Sat, 06 Mar 2010)
@@ -29,6 +29,7 @@
</table>
<hr>
<dl class="index">
+ <dt>Differences from version 1.42</dt>
<dt>Differences from version 1.41</dt>
<dt>Differences from version 1.40</dt>
<dt>Differences from version 1.39</dt>
@@ -42,6 +43,24 @@
As of this writing, there are no known bugs. However, due to compiler/library
quirks and or bugs, some tests fail with some combinations of compilers and
libraries.
+<h2><a name="differences_1_42"></a>Differences from Boost 1.42</h2>
+<ul>
+ <li>fixed failure of shared_ptr serialization when serializing pointers
+created from enable_shared_from_this.
+ <li>added example for a simple archive which can be used as a debug log.
+This example illustrates the implemenation of the archive concept to aid
+understanding required to create one's own archive classes. The resulting
+archive is useful for debugging in that it only 160 lines of code and is
+header only - that is, it doesn't required linking to the serialization library.
+ <li>replaced example used to show how to derive from an existing archive.
+This example creates an XML archive class which doesn't include serialization
+traits such as class_id, class_version, etc. It might be useful for exporting
+one's class information to osme XML processor and/or debugging programs.
+ <li>compile time warnings have been implemented to detect practices which
+ though correct, will result in operation or side effects different than
+ a user probably intends.
+ <li>Some memory leaks associated with void_cast have been fixed.
+</ul>
<h2><a name="differences_1_41"></a>Differences from Boost 1.41</h2>
<ul>
<li>adjustments have been made to minimize compile time warnings.
Modified: trunk/libs/serialization/doc/special.html
==============================================================================
--- trunk/libs/serialization/doc/special.html (original)
+++ trunk/libs/serialization/doc/special.html 2010-03-06 21:41:12 EST (Sat, 06 Mar 2010)
@@ -451,6 +451,48 @@
</a>
which are similar to the above but include tests of the export
and no_rtti facilities in the context of DLLS.
+<p>
+For best results, write your code to conform to the following
+guidelines:
+<ul>
+ <li>Don't include <code>inline</code> code in classes used in DLLS.
+This will generate duplicate code in the DLLS and mainline. This
+needlessly duplicates code. Worse, it makes is possible for
+different versions of the same code exist simultaneously. This
+type of error turns out to be excruciatingly difficult to debug.
+Finally, it opens the possibility that module being referred to
+might be explictly unloaded which would (hopefully) result in
+a runtime error. This is another bug that is not always
+reproducible or easy to find. For class member templates use something like
+
+<pre><code>
+template<class Archive>
+void serialize(Archive & ar, const unsigned int version);
+</code></pre>
+in the header, and
+
+<pre><code>
+template<class Archive>
+void myclass::serialize(Archive & ar, const unsigned int version){
+ ...
+}
+
+BOOST_EXPORT_CLASS_IMPLEMENT(my_class)
+
+#include <boost/archive/text_oarchive>
+#include <boost/archive/text_iarchive<
+template myclass::serialize(boost::archive::text_oarchive & ar, const unsigned int version);
+template myclass::serialize(boost::archive::text_iarchive & ar, const unsigned int version);
+... // repeat for each archive class to be used.
+</code></pre>
+in the implementation file. This will result in generation of all code
+required in only one place. The library does not detect this type of error for you.
+ <li>If DLLS are to be loaded an unloaded explicitly (e.g. using <code>dlopen</code> in *nix or
+<code>LoadLibrary</code> in Windows). Try to arrange that they are unloaded in the reverse
+sequence. This should guarentee that problems are avoided even if the
+above guidline hasn't been followed.
+
+</ul>
<h3><a name="plugins">Plugins</a></h3>
In order to implement the library, various facilities for runtime
Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk