[ceph.git] / ceph / src / boost / libs / serialization / doc / extended_type_info.html

<!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 . 
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)
-->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<link rel="stylesheet" type="text/css" href="../../../boost.css">
<link rel="stylesheet" type="text/css" href="style.css">
<title>Serialization - extended_type_info</title>
</head>
<body link="#0000ff" vlink="#800080">
<table border="0" cellpadding="7" cellspacing="0" width="100%" summary="header">
  <tr> 
    <td valign="top" width="300"> 
      <h3><a href="../../../index.htm"><img height="86" width="277" alt="C++ Boost" src="../../../boost.png" border="0"></a></h3>
    </td>
    <td valign="top"> 
      <h1 align="center">Serialization</h1>
      <h2 align="center"><code style="white-space: normal">extended_type_info</code></h2>
    </td>
  </tr>
</table>
<hr>
<dl class="page-index">
  <dt><a href="#motivation">Motivation</a>
  <dt><a href="#runtime">Runtime Interface</a>
  <dt><a href="#requirements">Requirements</a>
  <dt><a href="#models">Models</a>
  <dt><a href="#example">Example</a>
</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
the following functions
<ol>
  <li>
     given a pointer to a type T discover the true type pointed to.
  <li>
     given an "external" key - determine what type of object to create.
</ol>
<h3>The problem with <code style="white-space: normal">std::type_info</code></h3>
<ul>
  <li>
    The main function we require - <code style="white-space: normal">std::typeid()</code>
    is not available in all environments. Support for this function depends upon
    runtime typing(RTTI) support from the compiler.  This may be non-existent
    or not enabled for reasons such as a percieved inefficiency.
  <li>
    <code style="white-space: normal">std::type_info</code> includes a string
    containing type name.  This would seem to satisfy 2) above.
    But the format of this string is not consistent accross compilers, libraries, 
    and operating systems. This makes it unusable for support of portable archives.
  <li>
    Even if the type name string could somehow be made portable, there is no 
    guarantee that class headers would be included in the same namespace accross 
    different applications. In fact, including different headers in different
    namespaces is an accepted method used to avoid namespace conflicts.
    Thus the namespace::class_name can't be used as a key.
  <li>
    There exists the possibility that different classes use different type id 
    mechanisms.  The class header might include this information. If we want to 
    import class headers accross applications, it's convenient that the type id
    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
of <code style="white-space: normal">std::type_info</code> functionality with the 
following features:
<ul>
  <li>
    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
    serialized.
  <li>
    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.  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>

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">
namespace boost { 
namespace serialization {

class extended_type_info
{
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(
        const unsigned int type_info_key,
        const char * key
    );
    ~extended_type_info();
    void key_register();
    void key_unregister();
public:
    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 {
        return !(operator==(rhs));
    }
    // for plugins
    virtual void * construct(unsigned int count = 0, ...) const;
    virtual void destroy(void const * const p) const;
    static const extended_type_info * find(const char *key);
};

} // namespace serialization 
} // namespace boost
</code></pre>
<p>
Generally, there will be one and only one
<code style="white-space: normal"><a target="extended_type_info.hpp" href = "../../../boost/serialization/extended_type_info.hpp">extended_type_info</a></code>
instance created for each type.  However, this is enforced only at the executable
module level.  That is, if a program includes some shared libraries or DLLS,
there may be more than one instance of this class correponding to a particular type.
For this reason the comparison functions below can't just compare the addresses of 
this instance but rather must be programmed to compare the actual information 
the instances contain.
<dl>

<dt><h4><pre><code>
extended_type_info(unsigned int type_info_key, const char *key);
</code></pre></h4></dt>
<dd>
This constructor should be called by all derived classes.
The first argument should be the particular implementation. 
For this default implementation base on typeid(), this is the 
value 1.  Each system must have its own integer.  This value
is used to permit the inter-operability of different typeinfo
systems.
<p>
The second argument is a const string which is the external
name of the type to which this record corresponds.  
It may sometimes be referred to as a GUID - a <b>G</b>lobal <b>U</b>nique <b>ID</b>entifier.
It is passed through archives from one program invocation to
another to uniquely identify the types that the archive contains.
If the "export" facility is not going to be used, 
this value may be NULL.
</dd>

<dt><h4><pre><code>
void key_register();
void key_unregister();
</code></pre></h4></dt>
<dd>
This system maintains a global table which relates
external strings to 
<code style="white-space: normal">extended_type_info</code> records.
This table is used when loading pointers to objects serialized
through a base class pointer.  In this case, the archive 
contains a string which is looked up in this table to
determine which <code style="white-space: normal">extended_type_info</code>
to use for creating a new object.
<p>
These functions are called by constructors and
destructors of classes which implement 
<code style="white-space: normal">extended_type_info</code>
to add and remove entries from this table.
</dd>

<dt><h4><pre><code>
const char *get_key() const;
</code></pre></h4></dt>
<dd>
Retrieves the key for <code style="white-space: normal"><a target="extended_type_info.hpp" href = "../../../boost/serialization/extended_type_info.hpp">extended_type_info</a></code>
instance.  If no key has been associated with the instance, then a NULL is returned.
</dd>

<dt><h4><pre><code>
bool operator<(const extended_type_info & rhs) const;
bool operator==(const extended_type_info & rhs) const;
bool operator!=(const extended_type_info & rhs) const;
</code></pre></h4></dt>
<dd>
These functions are used to compare
<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 impose a strict total ordering on all
<code style="white-space: normal">extended_type_info</code> records.
</dd>

<dt><h4><pre><code>
virtual void * construct(unsigned int count = 0, ...) const;
</code></pre></h4></dt>
<dd>
Construct a new instance of the type to which this
<a target="extended_type_info.hpp" href = "../../../boost/serialization/extended_type_info.hpp">
<code style="white-space: normal">
extended_type_info
</code>
</a>
record corresponds. This function takes a variable list of up to 4 arguments
of any type.  These arguments are passed to the type's constructor
at runtime.  In order to use the facility, 
one must declare a type sequence for the constructor arguments.  
Arguments for this function must match in number and type
with those specified when the type was exported.  
This function permits one to create instances of
any exported type given only the exported <strong>GUID</strong> assigned
with BOOST_CLASS_EXPORT.  
If these types are defined in DLLS or shared libraries loaded at runtime, 
these constructors can be called until the module is unloaded.  
Such modules are referred to as <b>plugins</b>. 
</code>
</dd>

<dt><h4><pre><code>
virtual void destroy(void const * const p) const;
</code></pre></h4></dt>
<dd>
Destroy an instance created by the above constructor.
</dd>

<dt><h4><pre><code>
static const extended_type_info * find(const char *key);
</code></pre></h4></dt>
<dd>
Given a character string key or <strong>GUID</strong>, return the address of a 
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. 

</dl>

<h3><a name="requirements">Requirements for an Implementation</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 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;
const extended_type_info *
ETI::get_derived_extended_type_info(const T & t) const;
</pre></code></h4></dt>
<dd>
Return a pointer to the 
<code style="white-space: normal">extended_type_info</code>
instance that corresponds to
the "true type" of the type T.  The "true type" is the lowest type in the
hierarchy of classes.  The type T can always be cast to the "true type" with
a static cast.  Implementation of this function will vary among type id systems
and sometimes will make presumptions about the type T than can be identified
with a particular <code style="white-space: normal">extended_type_info</code> implementation.
</dd>

<dt><h4><code style="white-space: normal"><pre>
virtual bool ETI::is_less_than(const extended_type_info &rhs) const;
</pre></code></h4></dt>
<dd>
Compare this instance to another one using the same
<code style="white-space: normal">extended_type_info</code> implementation.
</dd>

<dt><h4><code style="white-space: normal"><pre>
virtual bool ETI::is_equal(const extended_type_info &rhs) const;
</pre></code></h4></dt>
<dd>
Compare this instance to another one using the same
<code style="white-space: normal">extended_type_info</code> implementation.
Return <code style="white-space: normal">true</code> if the types referred
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>
The serialization library includes two distinct
<code style="white-space: normal"><a target="extended_type_info.hpp" href="../../../boost/serialization/extended_type_info.hpp">extended_type_info</a></code>
implementations.
<p>
<code style="white-space: normal"><h4><a target="extended_type_info_typeid.hpp" href = "../../../boost/serialization/extended_type_info_typeid.hpp">
extended_type_info_typeid</a></h4></code>is implemented in terms of the standard typeid(). It presumes that RTTI support is enabled
by the compiler.
<p>
<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.
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:

<code><pre>
virtual const char * get_key();
</pre></code>
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.

<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">
extended_type_info</a></code> API above to return the export key associated with the class.  
This requires that non-abstract types be exported. It also demonstrates the
inter-operability between two different implementations of
<code style="white-space: normal">extended_type_info</code>.

<h3><a name="type_requirements">Requirements for Each Type</a></h3>
Each type to be managed by the system must be
"registered" individually. This is accomplished by instantiating
templates.  For example, if the type T is to use the type_info system
one would include the following code:

<code style="white-space: normal"><pre>
namespace boost {
namespace serialization {
template
struct extended_type_info_typeid&gt;T&gt;;
template
struct extended_type_info_typeid&gt;const T&gt;;
} // serialization
} // boost
</pre></code>

For those using the serialization library, this step can be skipped
as it is done automatically.  The serialization library includes
the macro:

<code style="white-space: normal"><pre>
BOOST_CLASS_TYPE_INFO(
    my_type, 
    extended_type_info_typeid&gt;my_class&gt;
)
</pre></code>

which is used to specify which <code>extended_type_info</code> system is to 
be used for a given type.
<p>
<code>extended_type_info</code> includes a facility for constructing
instances of types without knowing what the exact types are. This is done
with the function 
<code>
virtual void * extended_type_info::construct(unsigned int count = 0, ...) const;
</code>
. For example:
<br>
<code><pre>
struct base {
...
};
struct derived : public base {
...
};
...
extended_type_info *eti = extended_type_info::find("my_class")
base * b = eti->construct(...);
</pre></code>
<br>
The <code>construct</code> takes an argument count and up to
four parameters of any type.  The arguments are passed to the
constructor of "my_class".


A complete example of this can be found
<a target="test_dll_plugin.cpp" href="../test/test_dll_plugin.cpp">here</a>
<hr>
<p><i>&copy; Copyright <a href="http://www.rrsd.com">Robert Ramey</a> 2005-2009. 
Distributed 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>
</html>
Commit	Line	Data
7c673cae FG	1	<!doctype HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
	2	<html>
	3	<!--
	4	(C) Copyright 2002-4 Robert Ramey - http://www.rrsd.com .
	5	Use, modification and distribution is subject to the Boost Software
	6	License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
	7	http://www.boost.org/LICENSE_1_0.txt)
	8	-->
	9	<head>
	10	<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
	11	<link rel="stylesheet" type="text/css" href="../../../boost.css">
	12	<link rel="stylesheet" type="text/css" href="style.css">
	13	<title>Serialization - extended_type_info</title>
	14	</head>
	15	<body link="#0000ff" vlink="#800080">
	16	<table border="0" cellpadding="7" cellspacing="0" width="100%" summary="header">
	17	<tr>
	18	<td valign="top" width="300">
	19	<h3><a href="../../../index.htm"><img height="86" width="277" alt="C++ Boost" src="../../../boost.png" border="0"></a></h3>
	20	</td>
	21	<td valign="top">
	22	<h1 align="center">Serialization</h1>
	23	<h2 align="center"><code style="white-space: normal">extended_type_info</code></h2>
	24	</td>
	25	</tr>
	26	</table>
	27	<hr>
	28	<dl class="page-index">
	29	<dt><a href="#motivation">Motivation</a>
	30	<dt><a href="#runtime">Runtime Interface</a>
	31	<dt><a href="#requirements">Requirements</a>
	32	<dt><a href="#models">Models</a>
	33	<dt><a href="#example">Example</a>
	34	</dl>
	35
	36	<h3><a name="motivation">Motivation</a></h3>
	37	The serialization library needs a system like
	38	<code style="white-space: normal">type_info/typeid()</code> to perform
	39	the following functions
	40	<ol>
	41	<li>
	42	given a pointer to a type T discover the true type pointed to.
	43	<li>
	44	given an "external" key - determine what type of object to create.
	45	</ol>
	46	<h3>The problem with <code style="white-space: normal">std::type_info</code></h3>
	47	<ul>
	48	<li>
	49	The main function we require - <code style="white-space: normal">std::typeid()</code>
	50	is not available in all environments. Support for this function depends upon
	51	runtime typing(RTTI) support from the compiler. This may be non-existent
	52	or not enabled for reasons such as a percieved inefficiency.
	53	<li>
	54	<code style="white-space: normal">std::type_info</code> includes a string
	55	containing type name. This would seem to satisfy 2) above.
	56	But the format of this string is not consistent accross compilers, libraries,
	57	and operating systems. This makes it unusable for support of portable archives.
	58	<li>
	59	Even if the type name string could somehow be made portable, there is no
	60	guarantee that class headers would be included in the same namespace accross
	61	different applications. In fact, including different headers in different
	62	namespaces is an accepted method used to avoid namespace conflicts.
	63	Thus the namespace::class_name can't be used as a key.
	64	<li>
65	There exists the possibility that different classes use different type id
66	mechanisms. The class header might include this information. If we want to
67	import class headers accross applications, it's convenient that the type id
68	mechanism support inter-operability accross different type id systems.
69	</ul>
70	<h3>Features</h3>
71	<code style="white-space: normal"><a target="extended_type_info.hpp" href = "../../../boost/serialization/extended_type_info.hpp">
72	extended_type_info</a></code> is an implementation
73	of <code style="white-space: normal">std::type_info</code> functionality with the
74	following features:
75	<ul>
76	<li>
77	Builds a set of <a target="extended_type_info.hpp" href = "../../../boost/serialization/extended_type_info.hpp">
78	<code style="white-space: normal">extended_type_info</a></code> records - one for each type
79	serialized.
80	<li>
81	permits association of an arbitrary string key with a type. Often this key would
82	be the class name - but it doesn't have to be. This key is referred to as
83	a GUID - Globally Unique IDentifier. Presumably it should be unique in the universe.
84	Typically this GUID would be in header files and be used to match type accross
85	applications. The macro BOOST_CLASS_EXPORT can be invoked to associate a string
86	key with any known type. We'll refer to these types as "exported types"
87	<li>
88	permits the "mixing" of type info systems. For example, one class might use
89	<code style="white-space: normal">typeid()</code> to find the external identifier
90	of a class while another might not.
91	</ul>
92
93	Exported types are maintained in a global table so that given a string key, the
94	corresponding type can be found. This facility is used by the serialization library
95	in order to construct types serialized through a base class pointer.
96
97	<h3><a name="runtime">Runtime Interface</a></h3>
98	<pre><code">
99	namespace boost {
100	namespace serialization {
101
102	class extended_type_info
103	{
104	protected:
105	// this class can't be used as is. It's just the
106	// common functionality for all type_info replacement
107	// systems. Hence, make these protected
108	extended_type_info(
109	const unsigned int type_info_key,
110	const char * key
111	);
112	~extended_type_info();
113	void key_register();
114	void key_unregister();
115	public:
116	const char * get_key() const;
117	bool operator<(const extended_type_info &rhs) const;
118	bool operator==(const extended_type_info &rhs) const;
119	bool operator!=(const extended_type_info &rhs) const {
120	return !(operator==(rhs));
121	}
122	// for plugins
123	virtual void * construct(unsigned int count = 0, ...) const;
124	virtual void destroy(void const * const p) const;
125	static const extended_type_info * find(const char *key);
126	};
127
128	} // namespace serialization
129	} // namespace boost
130	</code></pre>
131	<p>
132	Generally, there will be one and only one
133	<code style="white-space: normal"><a target="extended_type_info.hpp" href = "../../../boost/serialization/extended_type_info.hpp">extended_type_info</a></code>
134	instance created for each type. However, this is enforced only at the executable
135	module level. That is, if a program includes some shared libraries or DLLS,
136	there may be more than one instance of this class correponding to a particular type.
137	For this reason the comparison functions below can't just compare the addresses of
138	this instance but rather must be programmed to compare the actual information
139	the instances contain.
140	<dl>
141
142	<dt><h4><pre><code>
143	extended_type_info(unsigned int type_info_key, const char *key);
144	</code></pre></h4></dt>
145	<dd>
146	This constructor should be called by all derived classes.
147	The first argument should be the particular implementation.
148	For this default implementation base on typeid(), this is the
149	value 1. Each system must have its own integer. This value
150	is used to permit the inter-operability of different typeinfo
151	systems.
152	<p>
153	The second argument is a const string which is the external
154	name of the type to which this record corresponds.
155	It may sometimes be referred to as a GUID - a <b>G</b>lobal <b>U</b>nique <b>ID</b>entifier.
156	It is passed through archives from one program invocation to
157	another to uniquely identify the types that the archive contains.
158	If the "export" facility is not going to be used,
159	this value may be NULL.
160	</dd>
161
162	<dt><h4><pre><code>
163	void key_register();
164	void key_unregister();
165	</code></pre></h4></dt>
166	<dd>
167	This system maintains a global table which relates
168	external strings to
169	<code style="white-space: normal">extended_type_info</code> records.
170	This table is used when loading pointers to objects serialized
171	through a base class pointer. In this case, the archive
172	contains a string which is looked up in this table to
173	determine which <code style="white-space: normal">extended_type_info</code>
174	to use for creating a new object.
175	<p>
176	These functions are called by constructors and
177	destructors of classes which implement
178	<code style="white-space: normal">extended_type_info</code>
179	to add and remove entries from this table.
180	</dd>
181
182	<dt><h4><pre><code>
183	const char *get_key() const;
184	</code></pre></h4></dt>
185	<dd>
186	Retrieves the key for <code style="white-space: normal"><a target="extended_type_info.hpp" href = "../../../boost/serialization/extended_type_info.hpp">extended_type_info</a></code>
187	instance. If no key has been associated with the instance, then a NULL is returned.
188	</dd>
189
190	<dt><h4><pre><code>
191	bool operator<(const extended_type_info & rhs) const;
192	bool operator==(const extended_type_info & rhs) const;
193	bool operator!=(const extended_type_info & rhs) const;
194	</code></pre></h4></dt>
195	<dd>
196	These functions are used to compare
197	<a target="extended_type_info.hpp" href = "../../../boost/serialization/extended_type_info.hpp">
198	<code style="white-space: normal">
199	extended_type_info
200	</code>
201	</a>
202	objects. They impose a strict total ordering on all
203	<code style="white-space: normal">extended_type_info</code> records.
204	</dd>
205
206	<dt><h4><pre><code>
207	virtual void * construct(unsigned int count = 0, ...) const;
208	</code></pre></h4></dt>
209	<dd>
210	Construct a new instance of the type to which this
211	<a target="extended_type_info.hpp" href = "../../../boost/serialization/extended_type_info.hpp">
212	<code style="white-space: normal">
213	extended_type_info
214	</code>
215	</a>
216	record corresponds. This function takes a variable list of up to 4 arguments
217	of any type. These arguments are passed to the type's constructor
218	at runtime. In order to use the facility,
219	one must declare a type sequence for the constructor arguments.
220	Arguments for this function must match in number and type
221	with those specified when the type was exported.
222	This function permits one to create instances of
223	any exported type given only the exported <strong>GUID</strong> assigned
224	with BOOST_CLASS_EXPORT.
225	If these types are defined in DLLS or shared libraries loaded at runtime,
226	these constructors can be called until the module is unloaded.
227	Such modules are referred to as <b>plugins</b>.
228	</code>
229	</dd>
230
231	<dt><h4><pre><code>
232	virtual void destroy(void const * const p) const;
233	</code></pre></h4></dt>
234	<dd>
235	Destroy an instance created by the above constructor.
236	</dd>
237
238	<dt><h4><pre><code>
239	static const extended_type_info * find(const char *key);
240	</code></pre></h4></dt>
241	<dd>
242	Given a character string key or <strong>GUID</strong>, return the address of a
243	corresponding <code style="white-space: normal"><a target="extended_type_info.hpp" href = "../../../boost/serialization/extended_type_info.hpp">extended_type_info</a></code>
244	object.
245
246	</dl>
247
248	<h3><a name="requirements">Requirements for an Implementation</a></h3>
249	In order to be used by the serialization library, an implementation of
250	<code style="white-space: normal">extended_type_info</code>,
251	(referred to as ETI here), must be derived from
252	<a target="extended_type_info.hpp" href = "../../../boost/serialization/extended_type_info.hpp">
253	<code style="white-space: normal">
254	extended_type_info
255	</code>
256	</a>
257	and also implement the following:
258
259	<dl>
260
261	<dt><h4><code style="white-space: normal"><pre>
262	template<class ETI>
263	const extended_type_info *
264	ETI::get_derived_extended_type_info(const T & t) const;
265	</pre></code></h4></dt>
266	<dd>
267	Return a pointer to the
268	<code style="white-space: normal">extended_type_info</code>
269	instance that corresponds to
270	the "true type" of the type T. The "true type" is the lowest type in the
271	hierarchy of classes. The type T can always be cast to the "true type" with
272	a static cast. Implementation of this function will vary among type id systems
273	and sometimes will make presumptions about the type T than can be identified
274	with a particular <code style="white-space: normal">extended_type_info</code> implementation.
275	</dd>
276
277	<dt><h4><code style="white-space: normal"><pre>
278	virtual bool ETI::is_less_than(const extended_type_info &rhs) const;
279	</pre></code></h4></dt>
280	<dd>
281	Compare this instance to another one using the same
282	<code style="white-space: normal">extended_type_info</code> implementation.
283	</dd>
284
285	<dt><h4><code style="white-space: normal"><pre>
286	virtual bool ETI::is_equal(const extended_type_info &rhs) const;
287	</pre></code></h4></dt>
288	<dd>
289	Compare this instance to another one using the same
290	<code style="white-space: normal">extended_type_info</code> implementation.
291	Return <code style="white-space: normal">true</code> if the types referred
292	to are the same. Otherwise return
293	<code style="white-space: normal">false</code>
294	</dd>
295
296	<dt><h4><code style="white-space: normal"><pre>
297	const char ETI::get_key() const;
298	</pre></code></h4></dt>
299	<dd>
300	Retrieve the external key (aka GUID) for this class.
301	</dd>
302
303	<dt><h4><code style="white-space: normal"><pre>
304	virtual void * construct(unsigned int count, ...) const;
305	</pre></code></h4></dt>
306	<dd>
307	Construct an instance of the corresponding type
308	with the include argument list.
309	</dd>
310
311	<dt><h4><code style="white-space: normal"><pre>
312	virtual void * destroy(void const * const ptr ) const;
313	</pre></code></h4></dt>
314	<dd>
315	Destroy an instance of this type. This calls the
316	proper destructor and recovers allocated memory.
317	</dd>
318
319	</dl>
320
321	<h3><a name="models">Models</a></h3>
322	The serialization library includes two distinct
323	<code style="white-space: normal"><a target="extended_type_info.hpp" href="../../../boost/serialization/extended_type_info.hpp">extended_type_info</a></code>
324	implementations.
325	<p>
326	<code style="white-space: normal"><h4><a target="extended_type_info_typeid.hpp" href = "../../../boost/serialization/extended_type_info_typeid.hpp">
327	extended_type_info_typeid</a></h4></code>is implemented in terms of the standard typeid(). It presumes that RTTI support is enabled
328	by the compiler.
329	<p>
330	<code style="white-space: normal"><h4><a target="extended_type_info_no_rtti.hpp" href="../../../boost/serialization/extended_type_info_no_rtti.hpp">
331	extended_type_info_no_rtti</a></h4></code>
332	is implemented in a way that doesn't rely on the existence RTTI.
333	Instead, it requires that all polymorphic types be explictly exported.
334	In addition, if the export facility is to be used to serialize types
335	through base class pointers, those types are required to implement
336	a virtual function with the signature:
337
338	<code><pre>
339	virtual const char * get_key();
340	</pre></code>
341	which returns a unique string the most derived object this class.
342	This function must be virtual in order to implement the functionality required by
343	<code style="white-space: normal">ETI::get_derived_extended_type_info</code>
344	as described above.
345
346	<h3><a name="example">Example</a></h3>
347	The test program <code style="white-space: normal"><a target="test_no_rtti" href="../test/test_no_rtti.cpp">test_no_rtti</a></code>
348	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">
349	extended_type_info</a></code> API above to return the export key associated with the class.
350	This requires that non-abstract types be exported. It also demonstrates the
351	inter-operability between two different implementations of
352	<code style="white-space: normal">extended_type_info</code>.
353
354	<h3><a name="type_requirements">Requirements for Each Type</a></h3>
355	Each type to be managed by the system must be
356	"registered" individually. This is accomplished by instantiating
357	templates. For example, if the type T is to use the type_info system
358	one would include the following code:
359
360	<code style="white-space: normal"><pre>
361	namespace boost {
362	namespace serialization {
363	template
364	struct extended_type_info_typeid>T>;
365	template
366	struct extended_type_info_typeid>const T>;
367	} // serialization
368	} // boost
369	</pre></code>
370
371	For those using the serialization library, this step can be skipped
372	as it is done automatically. The serialization library includes
373	the macro:
374
375	<code style="white-space: normal"><pre>
376	BOOST_CLASS_TYPE_INFO(
377	my_type,
378	extended_type_info_typeid>my_class>
379	)
380	</pre></code>
381
382	which is used to specify which <code>extended_type_info</code> system is to
383	be used for a given type.
384	<p>
385	<code>extended_type_info</code> includes a facility for constructing
386	instances of types without knowing what the exact types are. This is done
387	with the function
388	<code>
389	virtual void * extended_type_info::construct(unsigned int count = 0, ...) const;
390	</code>
391	. For example:
392	<br>
393	<code><pre>
394	struct base {
395	...
396	};
397	struct derived : public base {
398	...
399	};
400	...
401	extended_type_info *eti = extended_type_info::find("my_class")
402	base * b = eti->construct(...);
403	</pre></code>
404	<br>
405	The <code>construct</code> takes an argument count and up to
406	four parameters of any type. The arguments are passed to the
407	constructor of "my_class".
408
409
410	A complete example of this can be found
411	<a target="test_dll_plugin.cpp" href="../test/test_dll_plugin.cpp">here</a>
412	<hr>
413	<p><i>© Copyright <a href="http://www.rrsd.com">Robert Ramey</a> 2005-2009.
414	Distributed under the Boost Software License, Version 1.0. (See
415	accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
416	</i></p>
417	</body>
418	</html>