|
|
Boost-Commit : |
Subject: [Boost-commit] svn:boost r55743 - trunk/libs/serialization/doc
From: ramey_at_[hidden]
Date: 2009-08-23 17:50:53
Author: ramey
Date: 2009-08-23 17:50:53 EDT (Sun, 23 Aug 2009)
New Revision: 55743
URL: http://svn.boost.org/trac/boost/changeset/55743
Log:
Refine documentation for EXPORT
Refine documentation for extended_type_info.html
Text files modified:
trunk/libs/serialization/doc/contents.html | 13 +++--
trunk/libs/serialization/doc/extended_type_info.html | 31 ++++++++++++-
trunk/libs/serialization/doc/special.html | 87 ++++++++++++++++++++++++++-------------
trunk/libs/serialization/doc/traits.html | 82 ++++++++++++++++++------------------
4 files changed, 133 insertions(+), 80 deletions(-)
Modified: trunk/libs/serialization/doc/contents.html
==============================================================================
--- trunk/libs/serialization/doc/contents.html (original)
+++ trunk/libs/serialization/doc/contents.html 2009-08-23 17:50:53 EDT (Sun, 23 Aug 2009)
@@ -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 .
@@ -143,7 +143,7 @@
<dt><img style="display:none" src="dot.gif"><a target="detail" href="serialization.html#templates">Templates</a>
</dl></div></dd>
<dt><img style="display:none" src="dot.gif"><a target="detail" href="serialization.html#versioning">Versioning</a>
- <dt><img style="display:none" src="dot.gif"><a target="detail" href="serialization.html#splitting">Splitting <code>serialize</code> into <code>save/load</code></a>
+ <dt><img style="display:none" s'c="dot.gif"><a target="detail" href="serialization.html#splitting">Splitting <code>serialize</code> into <code>save/load</code></a>
</dl></div></dd>
<dt><img style="display:none" src="plus.gif" id="pointers"><a target="detail" href="serialization.html#pointeroperators">Pointers</a>
<dd><div id="pointers_detail"><dl class="page-index">
@@ -180,7 +180,7 @@
</dl></div></dd>
<dt><img style="display:none" src="dot.gif"><a target="detail" href="serialization.html#models">Models - Serialization Implementations Included in the Library</a>
</dl></div></dd>
- <dt><img style="display:none" src="plus.gif" id="special"><a target="detail" href="special.html">Special Considerations</a>
+ <dt><img style="display:none" src="plus.gif" id="special"><a target="detail" 'ref="special.html">Special Considerations</a>
<dd><div id="special_detail"><dl class="page-index">
<dt><img style="display:none" src="dot.gif"><a target="detail" href="special.html#objecttracking">Object Tracking</a>
<dt><img style="display:none" src="dot.gif"><a target="detail" href="special.html#classinfo">Class Information</a>
@@ -192,6 +192,7 @@
<dt><img style="display:none" src="dot.gif"><a target="detail" href="special.html#binary_archives">Binary Archives</a>
<dt><img style="display:none" src="dot.gif"><a target="detail" href="special.html#xml_archives">XML Archives</a>
<dt><img style="display:none" src="dot.gif"><a target="detail" href="special.html#export">Exporting Class Serialization</a>
+ <dt><img style="display:none" src="dot.gif"><a target="detail" href="special.html#static_libraries">Static Libraries and Serialization</a>
<dt><img style="display:none" src="dot.gif"><a target="detail" href="special.html#dlls">DLLS - Serialization and Runtime Linking</a>
<dt><img style="display:none" src="dot.gif"><a target="detail" href="special.html#plugins">Plugins</a>
<dt><img style="display:none" src="dot.gif"><a target="detail" href="special.html#multi_threading">Multi-Threading</a>
@@ -213,7 +214,7 @@
</dl></div></dd>
<dt><img style="display:none" src="dot.gif"><a target="detail" href="exception_safety.html">Exception Safety</a>
</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>
+ <dt><img style="display:none" src="plus.gif" id="archive_reference"><a target="detail" href="archive_reference.html">Archive Class Reference</'>
<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#usage">Usage</a>
@@ -248,7 +249,7 @@
<div id="userincludes_detail"><dl class="page-index">
<dt><img style="display:none" src="dot.gif"><a target="detail" href="headers.html#archiveimplementations">Archive Implementations</a>
<dt><img style="display:none" src="dot.gif"><a target="detail" href="headers.html#serializationdeclarations">Serialization Declarations</a>
- <dt><img style="display:none" src="dot.gif"><a target="detail" href="headers.html#serializationimplementations">Serialization Implementations</a>
+ <dt><img style="display:none" 'rc="dot.gif"><a target="detail" href="headers.html#serializationimplementations">Serialization Implementations</a>
</dl></div>
<dt><img style="display:none" src="plus.gif" id="libraryimplementation"><a target="detail" href="headers.html#libraryimplementation">Files Which Implement the Library</a>
<div id="libraryimplementation_detail"><dl class="page-index">
@@ -287,7 +288,7 @@
<dd><div id="singleton_detail"><dl class="page-index">
<dt><img style="display:none" src="dot.gif"><a target="detail" href="singleton.html#motivation">Motivation</a>
<dt><img style="display:none" src="dot.gif"><a target="detail" href="singleton.html#features">Features</a>
- <dt><img style="display:none" src="dot.gif"><a target="detail" href="singleton.html#classinterface">Class Interface</a>
+ <dt><img style="display:none" src="dot.gif"><a target="detail" href="singleton.html#classinterface">Class Interfac'</a>
<dt><img style="display:none" src="dot.gif"><a target="detail" href="singleton.html#requirements">Requirements</a>
<dt><img style="display:none" src="dot.gif"><a target="detail" href="singleton.html#examples">Examples</a>
<dt><img style="display:none" src="dot.gif"><a target="detail" href="singleton.html#multithreading">Multi-Threading</a>
Modified: trunk/libs/serialization/doc/extended_type_info.html
==============================================================================
--- trunk/libs/serialization/doc/extended_type_info.html (original)
+++ trunk/libs/serialization/doc/extended_type_info.html 2009-08-23 17:50:53 EDT (Sun, 23 Aug 2009)
@@ -281,7 +281,6 @@
Compare this instance to another one using the same
<code style="white-space: normal">extended_type_info</code> implementation.
</dd>
-</dl>
<dt><h4><code style="white-space: normal"><pre>
virtual bool ETI::is_equal(const extended_type_info &rhs) const;
@@ -293,6 +292,30 @@
to are the same. Otherwise return
<code style="white-space: normal">false</code>
</dd>
+
+<dt><h4><code style="white-space: normal"><pre>
+const char ETI::get_key() const;
+</pre></code></h4></dt>
+<dd>
+Retrieve the external key (aka GUID) for this class.
+</dd>
+
+<dt><h4><code style="white-space: normal"><pre>
+virtual void * construct(unsigned int count, ...) const;
+</pre></code></h4></dt>
+<dd>
+Construct an instance of the corresponding type
+with the include argument list.
+</dd>
+
+<dt><h4><code style="white-space: normal"><pre>
+virtual void * destroy(void const * const ptr ) ) const;
+</pre></code></h4></dt>
+<dd>
+Destroy an instance of this type. This calls the
+proper destructor and recovers allocated memory.
+</dd>
+
</dl>
<h3><a name="models">Models</a></h3>
@@ -307,7 +330,8 @@
<code style="white-space: normal"><h4><a target="extended_type_info_no_rtti.hpp" href="../../../boost/serialization/extended_type_info_no_rtti.hpp">
extended_type_info_no_rtti</a></h4></code>
is implemented in a way that doesn't rely on the existence RTTI.
-However, if the export facility is to be used to serialize types
+Instead, it requires that all polymorphic types be explictly exported.
+In addition, if the export facility is to be used to serialize types
through base class pointers, those types are required to implement
a virtual function with the signature:
@@ -317,7 +341,8 @@
which returns a unique string the most derived object this class.
This function must be virtual in order to implement the functionality required by
<code style="white-space: normal">ETI::get_derived_extended_type_info</code>
-as described above.
+as described above.
+
<h3><a name="example">Example</a></h3>
The test program <code style="white-space: normal"><a target="test_no_rtti" href="../test/test_no_rtti.cpp">test_no_rtti</a></code>
implements this function in terms of the <code style="white-space: normal"><a target="extended_type_info_no_rtti.hpp" href="../../../boost/serialization/extended_type_info_no_rtti.hpp">
Modified: trunk/libs/serialization/doc/special.html
==============================================================================
--- trunk/libs/serialization/doc/special.html (original)
+++ trunk/libs/serialization/doc/special.html 2009-08-23 17:50:53 EDT (Sun, 23 Aug 2009)
@@ -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 .
@@ -36,6 +36,7 @@
<dt>Binary Archives
<dt>XML Archives
<dt>Exporting Class Serialization
+ <dt>Static Libraries and Serialization
<dt>DLLS - Serialization and Runtime Linking
<dt>Plugins
<dt>Multi-Threading
@@ -176,7 +177,7 @@
archives. Including the class information in the archive assures us
that they will be readable in the future even if the class definition
is revised. A light weight structure such as display pixel might be
-declared in a header like this:
+declared in a header l'ke this:
<pre><code>
#include <boost/serialization/serialization.hpp>
@@ -264,7 +265,7 @@
information for instantiations of this template is never serialized. This
process is described <a target="detail" href="traits.html#templates">above</a> and
has been used for <a target="detail" href="wrappers.html#nvp"><strong>Name-Value Pairs</strong></a>.
-Wrappers would typically be assigned such traits.
+Wrappers would typically be assigned'such traits.
<p>
Another way to avoid this problem is to assign serialization traits
to all specializations of the template <code style="white-space: normal">my_wrapper</code>
@@ -339,16 +340,18 @@
of a stand alone executable, a static library or
a dyanmic or shared library.
<p>
-Note that including
+Including
<code style="white-space: normal">BOOST_CLASS_EXPORT</code>
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
<code style="white-space: normal">BOOST_CLASS_EXPORT</code>
-is invoked. This is different than other serialization
-traits which would normally be included in same file
-as the class declaration.
+is invoked. This can best be addressed by using
+<code style="white-space: normal">BOOST_CLASS_EXPORT_KEY</code>
+in the header declarations and
+<code style="white-space: normal">BOOST_CLASS_EXPORT_IMPLEMENT</code>
+in the class definition file.
<p>
This system has certain implications for placing code in static or shared
@@ -358,13 +361,6 @@
for all the archive classes which he anticipates using. Alternatively,
one can include headers for just the
<a href="archive_reference.html#polymorphic">Polymoprhic Archives</a>.
-Also, when making shared libraries, there is currently a restriction
-that only one such library can use <code style="white-space: normal">BOOST_CLASS_EXPORT</code>
-for any given type. All this will most likely make it inconvenient
-to include <code style="white-space: normal">BOOST_CLASS_EXPORT</code>
-as part of the header of the class to be serialized. So, <b>the
-best way to use <code style="white-space: normal">BOOST_CLASS_EXPORT</code>
-is to include it in the same module which implements the class</b>.
<p>
Strictly speaking, export should not be necessary if all pointer serialization
@@ -383,19 +379,33 @@
It's reasonable to expect that future C++ compilers will support
these extensions or something equivalent.
-<h3><a name="dlls">DLLS - Serialization and Runtime Linking</a></h3>
-Serialization code can be placed in libraries to be linked at runtime. That is,
-code can be placed in DLLS(Windows) Shared Libraries(*nix), or static libraries
-as well as the main executable. As long as
-
-<a target="detail" href="serialization.html#export">
-<code style="white-space: normal">BOOST_CLASS_EXPORT</code>
-</a>
-
-is not used, The serialization library imposes no special requirements
-that need be taken into account when distributing code among various modules.
-<p>
-For static libraries, this is illustrated by
+<h3><a name="static_libraries">Static Libraries and Serialization</a></h3>
+Code for serialization of data types can be saved in libraries
+just as it can for the rest of the type implementation.
+This works well, and can save huge amount of compilation time.
+<ul>
+<li>Only compile serialization definitions in the library.
+<li>Explicitly instantiate serialization code for ALL
+archive classes you intend to use in the library.
+<li>For exported types, only use <code style="white-space: normal">BOOST_CLASS_EXPORT_KEY</code>
+in headers.
+<li>For exported types, only use <code style="white-space: normal">BOOST_CLASS_EXPORT_IMPLEMENT</code>
+in definitions compiled in the library. For any particular type,
+there should be only one file which contains
+<code style="white-space: normal">BOOST_CLASS_EXPORT_IMPLEMENT</code>
+for that type. This ensures that only one copy
+of serialization code will exist within the program. It avoids
+wasted space and the possibility of having different
+versions of the serialization code in the same program.
+Including
+<code style="white-space: normal">BOOST_CLASS_EXPORT_IMPLEMENT</code>
+in multiple files could result in a failure
+to link due to duplicated symbols or the throwing
+of a runtime exception.
+<li> Code for serialization should be only in the library,
+<li>Familiarize yourself with the <b>PIMPL</b> idiom.
+</ul>
+This is illustrated by
<a href = "../example/demo_pimpl.cpp" target="demo_pimpl">
<code style="white-space: normal">demo_pimpl.cpp</code>
</a>,
@@ -409,8 +419,14 @@
where implementation of serializaton is in a static library
completely separate from the main program.
+<h3><a name="dlls">DLLS - Serialization and Runtime Linking</a></h3>
+Serialization code can be placed in libraries to be linked at runtime. That is,
+code can be placed in DLLS(Windows) Shared Libraries(*nix), or static libraries
+as well as the main executable. The best technique is the
+same as that described above for libraries. The serialization
+library test suite includes the following programs
+to illustrate how this works:
<p>
-For runtime linked libraries this is illustrated by one of the tests:
<a href = "../test/test_dll_simple.cpp" target="test_dll_simple">
<code style="white-space: normal">test_dll_simple</code>
@@ -423,7 +439,18 @@
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.
+with an OS depende't API call.
+<p>
+Also included are
+<a href = "../test/test_dll_exported.cpp" target="test_dll_exported">
+<code style="white-space: normal">test_dll_exported.cpp</code>
+</a>,
+and
+<a href = "../test/polymorphic_derived2.cpp" target="polymorphic_derived2">
+<code style="white-space: normal">polymorphic_derived2.cpp</code>
+</a>
+which are similar to the above but include tests of the export
+and no_rtti facilities in the context of DLLS.
<h3><a name="plugins">Plugins</a></h3>
In order to implement the library, various facilities for runtime
@@ -515,7 +542,7 @@
<hr>
<p><i>© Copyright Robert Ramey 2002-2004.
-Distributed under the Boost Software License, Version 1.0. (See
+Dist'ibuted 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)
</i></p>
</body>
Modified: trunk/libs/serialization/doc/traits.html
==============================================================================
--- trunk/libs/serialization/doc/traits.html (original)
+++ trunk/libs/serialization/doc/traits.html 2009-08-23 17:50:53 EDT (Sun, 23 Aug 2009)
@@ -202,13 +202,23 @@
situation is demonstrated by
<a href="../test/test_diamond.cpp" target="test_diamond_cpp">test_diamond.cpp</a>
included with the library.
+
<h3><a name="export">Export Key</a></h3>
-When serializing a derived class through a base class pointer, it
-may be convenient to define an external name by which the
-derived class can be identified.
-<i>(<a target="detail" href="special.html#export">Elsewhere</a>
-in this manual, the
-serialization of derived classes is addressed in detail.)</i>
+
+When serializing a derived class through a virtual base class pointer,
+two issues may arise.
+<ul>
+<li> The code in the derived class might never be explicitly
+referred to. Such code will never be instantiated.
+<p>
+This is addressed by invoking
+<code style="white-space: normal">BOOST_CLASS_EXPORT_IMPLEMENT(T)</code>
+in the file which defines (implements) the class T.
+This ensures that code for the derived class T will
+be explicity instantiated.
+<li> There needs to be some sort of identifier which can
+be used to select the code to be invoked when the object
+is loaded.
Standard C++ does implement <code style="white-space: normal">typeid()</code> which can be
used to return a unique string for the class. This is not entirely
statisfactory for our purposes for the following reasons:
@@ -222,46 +232,36 @@
<li>There might be classes with different names that we want to
consider equivalent for purposes of of serialization.
</ul>
-So the header file
-export.hpp
-includes macro definitions to specify the external string used
-to identify the class.
-<i>(<b>GUID</b> stands for <b>G</b>lobally <b>U</b>nique <b>ID</b>entfier.)</i>
-<pre><code>
-BOOST_CLASS_EXPORT_GUID(my_class, "my_class_external_identifier")
-</code></pre>
+<p>
+So in the serialization library, this is addressed by invoking
+<code style="white-space: normal">BOOST_CLASS_EXPORT_KEY2(my_class, "my_class_external_identifier")</code>
+in the header file which declares he class.
In a large majority of applications, the class name works just fine
for the external identifier string so the following short cut is
-defined
-<pre><code>
-BOOST_CLASS_EXPORT(my_class)
-</code></pre>
-which expands to:
-<pre><code>
-BOOST_CLASS_EXPORT_GUID(my_class, "my_class")
-</code></pre>
-Failure to export a type which requires it will result in an
-exception being thrown at runtime.
+defined -
+<code style="white-space: normal">BOOST_CLASS_EXPORT_KEY(my_class)</code>.
+</ul>
+For programs which consist of only one module - that is
+programs which do not use DLLS, one can specify
+<code style="white-space: normal">BOOST_CLASS_EXPORT(my_class)</code>
+or
+<code style="white-space: normal">BOOST_CLASS_EXPORT_GUID(my_class, "my_class_external_identifier")</code>
+in either he declaration header or definition. These macros
+expand to invocation of the of both of the macros described above.
+<i>(<b>GUID</b> stands for <b>G</b>lobally <b>U</b>nique <b>ID</b>entfier.)</i>
+<p>
+<i>(<a target="detail" href="special.html#export">Elsewhere</a>
+in this manual, the serialization of derived classes is addressed in detail.)</i>
<p>
-This above macros
+The header file
+export.hpp
+contains all macro definitions described here.
+The library will throw a runtime exception if
<ul>
-<li> Add and access entries into two static global tables.
- <ul>
- <li> key->type
- <li> type->key
- </ul>
-<li> Explicitly instantiate code to serialize pointers to types
-never serialized by name.
+<li> A type not explicitly referred to is not exported.
+<li> Serialization code for the same type is instantiated
+in more than one module (or DLL).
</ul>
-These declarations can be placed in either header or implementation
-files. However, in some cases, namely the creation of DLLS, placment
-in header files will result code being generated in both
-the mainline and DLL. This shouldn't create a problem, but
-it will result in the duplication of code. It would also be
-possible that the code in the DLL might evolve so that the
-implemenations are not longer compatible. So, placing
-these macros in a header used by DLLS and the mainline
-would seem to defeat the purpose of using a DLL in the first place.
<h3><a name="abstract">Abstract</a></h3>
When serializing an object through a pointer to its base class,
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