[Boost-commit] svn:boost r39566 - branches/serialization_next_release/boost/libs/serialization/doc

From: ramey_at_[hidden]
Date: 2007-09-27 00:05:26

Author: ramey
Date: 2007-09-27 00:05:25 EDT (Thu, 27 Sep 2007)
New Revision: 39566
URL: http://svn.boost.org/trac/boost/changeset/39566

Log:
improvements to extended type info system - unfortunately, these break the export.
Text files modified: 
   branches/serialization_next_release/boost/libs/serialization/doc/codecvt.html            |     2                                         
   branches/serialization_next_release/boost/libs/serialization/doc/contents.html           |     2                                         
   branches/serialization_next_release/boost/libs/serialization/doc/extended_type_info.html |   131 +++++++++++++++------------------------ 
   branches/serialization_next_release/boost/libs/serialization/doc/serialization.html      |     5                                         
   4 files changed, 56 insertions(+), 84 deletions(-)

Modified: branches/serialization_next_release/boost/libs/serialization/doc/codecvt.html
==============================================================================
--- branches/serialization_next_release/boost/libs/serialization/doc/codecvt.html	(original)
+++ branches/serialization_next_release/boost/libs/serialization/doc/codecvt.html	2007-09-27 00:05:25 EDT (Thu, 27 Sep 2007)
@@ -28,7 +28,7 @@
 <a name="sec:utf8-codecvt-facet-class"></a>
 
 
-<h1>UTF-8 Codecvt Facet</h1>
+<h1><code>utf8_codecvt_facet</code></h1>
 
 
 <pre>

Modified: branches/serialization_next_release/boost/libs/serialization/doc/contents.html
==============================================================================
--- branches/serialization_next_release/boost/libs/serialization/doc/contents.html	(original)
+++ branches/serialization_next_release/boost/libs/serialization/doc/contents.html	2007-09-27 00:05:25 EDT (Thu, 27 Sep 2007)
@@ -272,7 +272,7 @@
         <dt><img style="display:none" src="dot.gif"><a target="detail" href="extended_type_info.html#models">Models</a>
       </dl></div></dd>
       <dt><img style="display:none" src="dot.gif"><a target="detail" href="void_cast.html"><code>void_cast</code></a>
-      <dt><img style="display:none" src="dot.gif"><a target="detail" href="codecvt.html">utf-8 code_cvt</a>
+      <dt><img style="display:none" src="dot.gif"><a target="detail" href="codecvt.html"><code>utf8_codecvt_facet</code></a>
       <dt><img style="display:none" src="dot.gif"><a target="detail" href="strong_typedef.html"><code>BOOST_STRONG_TYPEDEF</code></a>
       <dt><img style="display:none" src="dot.gif"><a target="detail" href="state_saver.html"><code>state_saver</code></a>
       <dt><img style="display:none" src="dot.gif"><a target="detail" href="dataflow.html">Dataflow Iterators</a>

Modified: branches/serialization_next_release/boost/libs/serialization/doc/extended_type_info.html
==============================================================================
--- branches/serialization_next_release/boost/libs/serialization/doc/extended_type_info.html	(original)
+++ branches/serialization_next_release/boost/libs/serialization/doc/extended_type_info.html	2007-09-27 00:05:25 EDT (Thu, 27 Sep 2007)
@@ -33,7 +33,6 @@
   <dt>Example
 </dl>
 
-
 <h3><a name="motivation">Motivation</a></h3>
 The serialization library needs a system like 
 <code style="white-space: normal">type_info/typeid()</code> to perform
@@ -74,47 +73,31 @@
     mechanism support inter-operability accross different type id systems.
 </ul>
 <h3>Features</h3>
-<code style="white-space: normal"><a target="extended_type_info.hpp" href = "../../../boost/serialization/extended_type_info.hpp">extended_type_info</a></code> is an implementation
+<code style="white-space: normal"><a target="extended_type_info.hpp" href = "../../../boost/serialization/extended_type_info.hpp">
+extended_type_info</a></code> is an implementation
 of <code style="white-space: normal">std::type_info</code> functionality with the 
 following features:
 <ul>
   <li>
-    Maintains a global table of <code style="white-space: normal"><a target="extended_type_info.hpp" href = "../../../boost/serialization/extended_type_info.hpp">extended_type_info</a></code> records - one for each type known
+    Builds a set of <a target="extended_type_info.hpp" href = "../../../boost/serialization/extended_type_info.hpp">
+    <code style="white-space: normal">extended_type_info</a></code> records - one for each type known
     to the program.
   <li>
-    permits association of an arbitrary key with a type.  Often this key would
+    permits association of an arbitrary string key with a type.  Often this key would
     be the class name - but it doesn't have to be.  This key is referred to as
     a GUID - Globally Unique IDentifier.  Presumably it should be unique in the universe.
     Typically this GUID would be in header files and be used to match type accross
-    applications.
+    applications.  The macro BOOST_CLASS_EXPORT can be invoked to associate a string
+    key with any known type.  We'll refer to these types as "exported types"
   <li>
     permits the "mixing" of type info systems.  For example, one class might use 
     <code style="white-space: normal">typeid()</code> to find the external identifier 
     of a class while another might not.
 </ul>
-The serialization system maintains two global tables.
-<ul>
-  <li>The first is a global type table. it has an entry for each type used.
-  Each entry is an instance of a class derived from 
-  <code style="white-space: normal"><a target="extended_type_info.hpp" href = "../../../boost/serialization/extended_type_info.hpp">extended_type_info</a></code>. This table is used
-  to retrieve the unique <code style="white-space: normal"><a target="extended_type_info.hpp" href = "../../../boost/serialization/extended_type_info.hpp">extended_type_info</a></code>
-  information for any given type.
-  <li>The second is global key table. It has an entry for each type which has been assigned a GUID string key.
-  This table is used to retrieve the unique 
-  <code style="white-space: normal"><a target="extended_type_info.hpp" href = "../../../boost/serialization/extended_type_info.hpp">extended_type_info</a></code> given its GUID.
-</ul>
-This library includes two different type id systems:
-<ul>
-  <li>
-    <code style="white-space: normal"><a target="extended_type_info_typeid.hpp" href = "../../../boost/serialization/extended_type_info_typeid.hpp">extended_type_info_typeid</a></code>
-    which is implemented in terms of the standard
-    <code style="white-space: normal">typeid()</code>.
-  <li>
-    <code style="white-space: normal"><a target="extended_type_info_no_rtti.hpp" href="../../../boost/serialization/extended_type_info_no_rtti.hpp">extended_type_info_no_rtti</a></code>
-    which is implemented in a way that doesn't rely on the existence
-    RTTI.  However, it does require that all classes for which type id is to be used
-    be explictly assigned an external key - which otherwise would be optional.
-</ul>
+
+Exported types are maintained in a global table so that given a string key, the
+corresponding type can be found.  This facility is used by the serialization library
+in order to construct types serialized through a base class pointer.
 
 <h3><a name="runtime">Runtime Interface</a></h3>
 <pre><code">
@@ -125,20 +108,22 @@
     private boost::noncopyable 
 {
 protected:
+    // this class can't be used as is. It's just the 
+    // common functionality for all type_info replacement
+    // systems.  Hence, make these protected
+    extended_type_info();
+    ~extended_type_info();
+    const char * m_key;
     extended_type_info(const char * type_info_key);
 public:
-    void self_register();
     void key_register(const char *key);
     const char * get_key() const;
-
-    bool operator<(const extended_type_info &rhs) const;
-    bool operator==(const extended_type_info &rhs) const;
-    bool operator!=(const extended_type_info &rhs) const;
-
     static const extended_type_info * find(const char *key);
-    static const extended_type_info * find(const extended_type_info * t);
 };
 
+bool operator<(const extended_type_info &rhs) const;
+bool operator==(const extended_type_info &rhs) const;
+
 } // namespace serialization 
 } // namespace boost
 </code></pre>
@@ -152,19 +137,7 @@
 <dt><h4><pre><code>
 extended_type_info(const char * type_info_key);</code></pre></h4></dt>
 <dd>
-This constructor should be called by all derived classes. It should be passed
-a pointer to a const string which identifies the type id system being used.  This
-type id is used to distinguish among the various type id system that might be used
-and allow them to interoperate.
-</dd>
-
-<dt><h4><pre><code>
-void self_register();
-</code></pre></h4></dt>
-<dd>
-This function adds entry for an entry to the global type table.  It would usually be 
-called from the constructor of the derived class which implements the 
-<code style="white-space: normal"><a target="extended_type_info.hpp" href = "../../../boost/serialization/extended_type_info.hpp">extended_type_info</a></code> functionality.
+This constructor should be called by all derived classes.
 </dd>
 
 <dt><h4><pre><code>
@@ -189,13 +162,28 @@
 </dd>
 
 <dt><h4><pre><code>
-bool operator&lt;(const extended_type_info &rhs) const;
-bool operator==(const extended_type_info &rhs) const;
-bool operator!=(const extended_type_info &rhs) const;
+// in order
+bool operator==(
+    const extended_type_info & lhs, 
+    const extended_type_info & rhs
+);
+bool operator<(
+    const extended_type_info & lhs, 
+    const extended_type_info & rhs
+);
+
+} // namespace serialization 
+} // namespace boost
 </code></pre></h4></dt>
 <dd>
-These functions are used to compare two <code style="white-space: normal"><a target="extended_type_info.hpp" href = "../../../boost/serialization/extended_type_info.hpp">extended_type_info</a></code> objects.
-Among other things, these are used for lookup in the tables.
+These non-member functions are used to compare two 
+<a target="extended_type_info.hpp" href = "../../../boost/serialization/extended_type_info.hpp">
+<code style="white-space: normal">
+extended_type_info
+</code> 
+</a>
+objects. They a strict total ordering on all instances of this class and
+are used to implement the following.
 
 <dt><h4><pre><code>
 static const extended_type_info * find(const char *key);
@@ -205,40 +193,23 @@
 unique corresponding <code style="white-space: normal"><a target="extended_type_info.hpp" href = "../../../boost/serialization/extended_type_info.hpp">extended_type_info</a></code>
 object. 
 
-<dt><h4><pre><code>
-static const extended_type_info * find(const extended_type_info * t);
-</code></pre></h4></dt>
-<dd>
-Given a pointer to an
-<code style="white-space: normal"><a target="extended_type_info.hpp" href = "../../../boost/serialization/extended_type_info.hpp">extended_type_info</a></code>,
-return the address of the instance of the same type in the main table.
-That is the argument t is used as a search argment to find the main
-table entry for a given type. It would be used like this:
-<code><pre>
-// return the global type entry for our type T
-return find(some_extended_type_info_implementation&lt;T&gt;())
-</pre></code>
-
 </dl>
 
 <h3><a name="requirements">Requirements</a></h3>
 In order to be used by the serialization library, an implementation of
 <code style="white-space: normal">extended_type_info</code>, 
-(referred to as ETI here), must implement the following:
+(referred to as ETI here), must be derived from 
+<a target="extended_type_info.hpp" href = "../../../boost/serialization/extended_type_info.hpp">
+<code style="white-space: normal">
+extended_type_info
+</code> 
+</a>
+and also implement the following:
 
 <dl>
 
 <dt><h4><code style="white-space: normal"><pre>
 template&lt;class ETI&gt;
-virtual bool
-ETI::less_than(const extended_type_info &rhs) const;
-</pre></code></h4></dt>
-<dd>
-Impose a strict total ordering on all instances of the class ETI.
-</dd>
-
-<dt><h4><code style="white-space: normal"><pre>
-template&lt;class ETI&gt;
 static const extended_type_info *
 ETI::get_derived_extended_type_info(const T & t);
 </pre></code></h4></dt>
@@ -256,7 +227,7 @@
 <dt><h4><code style="white-space: normal"><pre>
 template&lt;class ETI&gt;
 static extended_type_info *
-ETI::get_instance();
+ETI::find();
 </pre></code></h4></dt>
 <dd>
 Return a pointer to the instance of
@@ -266,9 +237,9 @@
 </dd>
 
 <dt><h4><code style="white-space: normal"><pre>
-static void
 template&lt;class ETI&gt;
-ETI::export_register(const char * key);
+static void 
+ETI::key_register(const char * key);
 </pre></code></h4></dt>
 <dd>
 The main function is to invoke key_register to add the GUID to the

Modified: branches/serialization_next_release/boost/libs/serialization/doc/serialization.html
==============================================================================
--- branches/serialization_next_release/boost/libs/serialization/doc/serialization.html	(original)
+++ branches/serialization_next_release/boost/libs/serialization/doc/serialization.html	2007-09-27 00:05:25 EDT (Thu, 27 Sep 2007)
@@ -48,7 +48,7 @@
         <dt>Free Functions
       </dl>
   </dl>
-  <dt>Pointers
+  <dt>Pointers
     <dl class="page-index">
       <dt>Non-Default Constructors
       <dt>Pointers to Objects of Derived Classes
@@ -77,7 +77,8 @@
     <a target="detail" href="traits.html#Traits">serialization traits</a>,
     any user type can also be designated as "primitive"
     so that it is handled in this way.
-  <li>It is a class type and one of the following has been declared:
+  <li>It is a class type and one of the following has been declared according
+    to the prototypes detailed below:
     <ul>
     <li>a class member function <code style="white-space: normal">serialize</code>
     <li>a global function <code style="white-space: normal">serialize</code>