[ceph.git] / ceph / src / boost / libs / serialization / doc / overview.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 - Overview</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">Overview</h2>
    </td>
  </tr>
</table>
<hr>
<dl class="index">
  <dt><a href="#Requirements">Requirements</a></dt>
  <dt><a href="#otherimplementations">Other Implementations</a></dt>
</dl>
<p>Here, we use the term <strong>"serialization"</strong> to mean
the reversible deconstruction of an arbitrary set of C++ data structures
to a sequence of bytes.  Such a system can be used to reconstitute
an equivalent structure in another program context.  Depending on
the context, this might used implement object persistence, remote
parameter passing or other facility. In this system we use the term
<strong>"archive"</strong> to refer to a specific rendering of this
stream of bytes.  This could be a file of binary data, text data, 
XML, or some other created by the user of this library.
<h2><a name="Requirements"></a>Our goals for such a system are:</h2>
   <ol>
      <li>Code portability - depend only on ANSI C++ facilities.

      <li>Code economy - exploit features of C++ such as RTTI,
      templates, and multiple inheritance, etc. where appropriate to
      make code shorter and simpler to use.

      <li>Independent versioning for each class definition. That
      is, when a class definition changed, older files can still be
      imported to the new version of the class.

      <li>Deep pointer save and restore. That is, save and restore
      of pointers saves and restores the data pointed to.

      <li>Proper restoration of pointers to shared data.

      <li>Serialization of STL containers and other commonly used
      templates.

      <li>Data Portability - Streams of bytes created on one platform
      should be readable on any other.

      <li>Orthogonal specification of class serialization and archive format.
      That is, any file format should be able to store serialization
      of any arbitrary set of C++ data structures without having to
      alter the serialization of any class.

      <li>Non-intrusive. Permit serialization to be applied to
      unaltered classes. That is, don't require that classes to be
      serialized be derived from a specific base class or implement
      specified member functions. This is necessary to easily
      permit serialization to be applied to classes from class
      libraries that we cannot or don't want to have to alter.

      <li> The <strong>archive</strong> interface must be simple
      enough to easily permit creation of a new type of archive.

      <li> The <strong>archive</strong> interface must be rich
      enough to permit the creation of an <strong>archive</strong>
      that presents serialized data as XML in a useful manner.
   </ol>

<h2><a name="otherimplementations"></a>Other implementations</h2>
    Before getting started I searched around for current
    implementations. I found several. 

    <ul>
      <li><u>MFC</u> This is the one that I am very familiar with.
      I have used it for several years and have found it very useful.
      However it fails requirements 1, 2, 3, 6, 7, and 9. In spite
      of all the requirements not fulfilled, this is the most
      useful implementation I've found. It turns out that class
      versioning - partially implemented in MFC - really is
      indispensable for my applications. Inevitably, version 1.x of
      a shipping program needs to store more information in files
      than was originally provided for. MFC is the only one of these
      implementations that supports this - though only for the most
      derived class. Still it's better than nothing and does the
      job. MFC doesn't implement serialization of STL collections.
      Though it does so for MFC collections.

      <li><u>CommonC++ libraries</u> <a href="bibliography.html#1">[1]</a>
      As far as I can tell, this
      closely follows the MFC implementation but does address a few
      of the issues. It is portable and creates portable archives but
      skips versioning. It does support proper and complete
      restoration of pointers and STL collections. It does address
      compression though not in the way that I would prefer. The
      package would also benefit from having better documentation.
      So it fails to address 2, 3, 7, 8, and 9.

      <li><u>Eternity</u> <a href="bibliography.html#2">[2]</a> 
      This is a bare bones package. It
      seems well coded but it really needs documentation and
      examples. It's not obvious how to use it without time
      consuming study of the source code. Recent versions do support
      files in XML format.  This Fails 3, 6, 7?, 8, and 9. 

      <li><u>Holub's implementation</u> <a href="bibliography.html#3">[3]</a> This is the article that
      first got me thinking about my own requirements for
      a serialization implementation. Interesting and worth
      the read if you can overlook the arrogant tone of the prose.
      This implementation fails 2, 3, 4, 5, and 6.

      <li><u>s11n</u> <a href="bibliography.html#13">[13]</a>
      This library has similar goals to this one. Some aspects of the
      implemenation are also similar.  As of this writing, it would seem that:
      <ul>
          <li>Portability(1) is guarenteed only for recent versions of GCC.
          <li>Versioning(3) of class definitions is not explicitly supported by
          the library.
          <li>it doesn't seem to automatically account for shared pointers(5).
          I concluded this from the documentation as well as the statement that
          serialization of graph like structures is not supported.
      </ul>
      Its has lots of differences - and lots in common with this implementation. 
    </ul>
<hr>
<p>Revised 1 November, 2004 
<p><i>&copy; Copyright <a href="http://www.rrsd.com">Robert Ramey</a> 2002-2004. 
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 - Overview</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">Overview</h2>
	24	</td>
	25	</tr>
	26	</table>
	27	<hr>
	28	<dl class="index">
	29	<dt><a href="#Requirements">Requirements</a></dt>
	30	<dt><a href="#otherimplementations">Other Implementations</a></dt>
	31	</dl>
	32	<p>Here, we use the term <strong>"serialization"</strong> to mean
	33	the reversible deconstruction of an arbitrary set of C++ data structures
	34	to a sequence of bytes. Such a system can be used to reconstitute
	35	an equivalent structure in another program context. Depending on
	36	the context, this might used implement object persistence, remote
	37	parameter passing or other facility. In this system we use the term
	38	<strong>"archive"</strong> to refer to a specific rendering of this
	39	stream of bytes. This could be a file of binary data, text data,
	40	XML, or some other created by the user of this library.
	41	<h2><a name="Requirements"></a>Our goals for such a system are:</h2>
	42	<ol>
	43	<li>Code portability - depend only on ANSI C++ facilities.
	44
	45	<li>Code economy - exploit features of C++ such as RTTI,
	46	templates, and multiple inheritance, etc. where appropriate to
	47	make code shorter and simpler to use.
	48
	49	<li>Independent versioning for each class definition. That
	50	is, when a class definition changed, older files can still be
	51	imported to the new version of the class.
	52
	53	<li>Deep pointer save and restore. That is, save and restore
	54	of pointers saves and restores the data pointed to.
	55
	56	<li>Proper restoration of pointers to shared data.
	57
	58	<li>Serialization of STL containers and other commonly used
	59	templates.
	60
	61	<li>Data Portability - Streams of bytes created on one platform
	62	should be readable on any other.
	63
	64	<li>Orthogonal specification of class serialization and archive format.
65	That is, any file format should be able to store serialization
66	of any arbitrary set of C++ data structures without having to
67	alter the serialization of any class.
68
69	<li>Non-intrusive. Permit serialization to be applied to
70	unaltered classes. That is, don't require that classes to be
71	serialized be derived from a specific base class or implement
72	specified member functions. This is necessary to easily
73	permit serialization to be applied to classes from class
74	libraries that we cannot or don't want to have to alter.
75
76	<li> The <strong>archive</strong> interface must be simple
77	enough to easily permit creation of a new type of archive.
78
79	<li> The <strong>archive</strong> interface must be rich
80	enough to permit the creation of an <strong>archive</strong>
81	that presents serialized data as XML in a useful manner.
82	</ol>
83
84	<h2><a name="otherimplementations"></a>Other implementations</h2>
85	Before getting started I searched around for current
86	implementations. I found several.
87
88	<ul>
89	<li><u>MFC</u> This is the one that I am very familiar with.
90	I have used it for several years and have found it very useful.
91	However it fails requirements 1, 2, 3, 6, 7, and 9. In spite
92	of all the requirements not fulfilled, this is the most
93	useful implementation I've found. It turns out that class
94	versioning - partially implemented in MFC - really is
95	indispensable for my applications. Inevitably, version 1.x of
96	a shipping program needs to store more information in files
97	than was originally provided for. MFC is the only one of these
98	implementations that supports this - though only for the most
99	derived class. Still it's better than nothing and does the
100	job. MFC doesn't implement serialization of STL collections.
101	Though it does so for MFC collections.
102
103	<li><u>CommonC++ libraries</u> <a href="bibliography.html#1">[1]</a>
104	As far as I can tell, this
105	closely follows the MFC implementation but does address a few
106	of the issues. It is portable and creates portable archives but
107	skips versioning. It does support proper and complete
108	restoration of pointers and STL collections. It does address
109	compression though not in the way that I would prefer. The
110	package would also benefit from having better documentation.
111	So it fails to address 2, 3, 7, 8, and 9.
112
113	<li><u>Eternity</u> <a href="bibliography.html#2">[2]</a>
114	This is a bare bones package. It
115	seems well coded but it really needs documentation and
116	examples. It's not obvious how to use it without time
117	consuming study of the source code. Recent versions do support
118	files in XML format. This Fails 3, 6, 7?, 8, and 9.
119
120	<li><u>Holub's implementation</u> <a href="bibliography.html#3">[3]</a> This is the article that
121	first got me thinking about my own requirements for
122	a serialization implementation. Interesting and worth
123	the read if you can overlook the arrogant tone of the prose.
124	This implementation fails 2, 3, 4, 5, and 6.
125
126	<li><u>s11n</u> <a href="bibliography.html#13">[13]</a>
127	This library has similar goals to this one. Some aspects of the
128	implemenation are also similar. As of this writing, it would seem that:
129	<ul>
130	<li>Portability(1) is guarenteed only for recent versions of GCC.
131	<li>Versioning(3) of class definitions is not explicitly supported by
132	the library.
133	<li>it doesn't seem to automatically account for shared pointers(5).
134	I concluded this from the documentation as well as the statement that
135	serialization of graph like structures is not supported.
136	</ul>
137	Its has lots of differences - and lots in common with this implementation.
138	</ul>
139	<hr>
140	<p>Revised 1 November, 2004
141	<p><i>© Copyright <a href="http://www.rrsd.com">Robert Ramey</a> 2002-2004.
142	Distributed under the Boost Software License, Version 1.0. (See
143	accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
144	</i></p>
145	</body>
146	</html>