Update of /cvsroot/boost/boost/libs/serialization/doc
In directory sc8-pr-cvs3.sourceforge.net:/tmp/cvs-serv12482
Modified Files:
headers.html special.html contents.html wrappers.html
Log Message:
Added documentation for array wrappers
Index: headers.html
===================================================================
RCS file: /cvsroot/boost/boost/libs/serialization/doc/headers.html,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -d -r1.9 -r1.10
--- headers.html 21 Jul 2005 18:29:48 -0000 1.9
+++ headers.html 4 Jun 2006 01:42:55 -0000 1.10
@@ -7,7 +7,7 @@
http://www.boost.org/LICENSE_1_0.txt)
-->
<head>
-<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+<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 - Code Structure</title>
@@ -122,6 +122,21 @@
</a>
<dd>wide character xml output archive used for saving.</dd>
+<dt><a name="arraybinaryiarchive">
+<a name="array_binary_iarchive"
href="../../../boost/archive/array/binary_iarchive.hpp">
+boost/archive/array/binary_iarchive.hpp
+</a>
+<dd>native binary input archive used for loading, implementing optimizations
+for contiguous arrays of primitive types.</dd>
+
+<dt><a name="arraybinaryoarchive">
+<a target="array_binary_oarchive"
href="../../../boost/archive/array/binary_oarchive.hpp">
+boost/archive/array/binary_oarchive.hpp
+</a>
+<dd>native binary output archive used for saving, implementing optimizations
+for contiguous arrays of primitive types.</dd>
+
+
</dl>
<a name="serializationdeclarations">
Index: special.html
===================================================================
RCS file: /cvsroot/boost/boost/libs/serialization/doc/special.html,v
retrieving revision 1.10
retrieving revision 1.11
diff -u -d -r1.10 -r1.11
--- special.html 11 Dec 2005 06:19:33 -0000 1.10
+++ special.html 4 Jun 2006 01:42:55 -0000 1.11
@@ -7,7 +7,7 @@
http://www.boost.org/LICENSE_1_0.txt)
-->
<head>
-<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+<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 - Special Considerations</title>
@@ -36,6 +36,7 @@
</dl>
<dt><a href="#binary_archives">Binary Archives</a>
<dt><a href="#xml_archives">XML Archives</a>
+ <dt><a href="#optimizations">Optimizations</a>
<dt><a href="exceptions.html">Archive Exceptions</a>
<dt><a href="exception_safety.html">Exception Safety</a>
</dl>
@@ -308,6 +309,16 @@
So its possible that a value could be written that couldn't be represented
by the loading program. This is a
fairly obvious situation and easily handled by using the numeric types in
<a target="cstding"
href="../../../boost/cstdint.hpp"><boost/cstdint.hpp></a>
+<P>
+A special integral type is <code>std::size_t</code> which is a typedef
+of an integral types guaranteed to be large enough
+to hold the size of any collection, but its actual size can differ depending
+on the platform. The
+<a
href="wrappers.html#collection_size_type"><code>collection_size_type</code></a>
+wrapper exists to enable a portable serialization of collection sizes by an
archive.
+Recommended choices for a portable serialization of collection sizes are to
+use either 64-bit or variable length integer representation.
+
<h4><a name="traits">Traits</a></h4>
Another potential problem is illustrated by the following example:
@@ -382,6 +393,26 @@
So by always using <a target="detail" href="wrappers.html#nvp">name-value
pairs</a>, it will
be guarenteed that all data can be serialized to all archive classes with
maximum efficiency.
+<h3><a name="optimizations">Optimizations</a></h3>
+In performance critical applications that serialize large sets of contiguous
data of homogeneous
+types one wants to avoid the overhead of serializing each element
individually, which is
+the motivation for the <a href="wrappers.html#arrays"><code>array</code></a>
+wrapper.
+
+Serialization functions for data types containing contiguous arrays of
homogeneous
+types, such as for <code>std::vector</code>, <code>std::valarray</code> or
+<code>boost::multiarray</code> should serialize them using an
+ <a href="wrappers.html#arrays"><code>array</code></a> wrapper to make use of
+ these optimizations.
+
+Archive types that can provide optimized serialization for contiguous arrays
of
+homogeneous types should implement these by overloading the serialization of
+the <a href="wrappers.html#arrays"><code>array</code></a> wrapper. As an
example
+optimized versions of the binary archives are provided in
+<a
href="headers.html#arraybinaryiarchive">archive/array/binary_iarchive.hpp</a>
+and <a
href="headers.html#arraybinaryoarchive">archive/array/binary_oarchive.hpp</a>
+
+
<h3><a href="exceptions.html">Archive Exceptions</a></h3>
<h3><a href="exception_safety.html">Exception Safety</a></h3>
Index: contents.html
===================================================================
RCS file: /cvsroot/boost/boost/libs/serialization/doc/contents.html,v
retrieving revision 1.19
retrieving revision 1.20
diff -u -d -r1.19 -r1.20
--- contents.html 5 Feb 2006 00:50:48 -0000 1.19
+++ contents.html 4 Jun 2006 01:42:55 -0000 1.20
@@ -7,7 +7,7 @@
http://www.boost.org/LICENSE_1_0.txt)
-->
<head>
-<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<link rel="stylesheet" type="text/css" href="../../../boost.css">
<title>Serialization</title>
@@ -149,13 +149,17 @@
<dt><img style="display:none" src="dot.gif"><a target="detail"
href="serialization.html#instantiation">Instantiation</a>
<dt><img style="display:none" src="dot.gif"><a target="detail"
href="serialization.html#selectivetracking">Selective Tracking</a>
<dt><img style="display:none" src="dot.gif"><a target="detail"
href="serialization.html#runtimecasting">Runtime Casting</a>
- </dl></div></dd>
+ </dl></div></dd>Version:1.0 StartHTML:0000000199 EndHTML:0000001427
StartFragment:0000001342 EndFragment:0000001374
SourceURL:file://localhost/Volumes/iDisk/Documents/Boost%20Consulting/Invoices/Timesheet.xls
+
+
</dl></div></dd>
<dt><img style="display:none" src="dot.gif"><a target="detail"
href="serialization.html#references">References</a>
<dt><img style="display:none" src="plus.gif" id="wrappers"><a
target="detail" href="wrappers.html">Serialization Wrappers</a>
<dd><div id="wrappers_detail"><dl class="page-index">
<dt><img style="display:none" src="dot.gif"><a target="detail"
href="wrappers.html#binaryobjects">Binary Objects</a>
+ <dt><img style="display:none" src="dot.gif"><a target="detail"
href="wrappers.html#arrays">Arrays</a>
<dt><img style="display:none" src="dot.gif"><a target="detail"
href="wrappers.html#strong_type"><code style="white-space:
normal">strong_type</code></a>
+ <dt><img style="display:none" src="dot.gif"><a target="detail"
href="wrappers.html#collection_size_type">Collection Sizes</a>
<dt><img style="display:none" src="dot.gif"><a target="detail"
href="wrappers.html#nvp">Name-Value Pairs</a>
<dt><img style="display:none" src="dot.gif"><a target="detail"
href="wrappers.html#composition">Composition</a>
</dl></div></dd>
@@ -183,6 +187,7 @@
</dl></div></dd>
<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#optimizations">Optimzations</a>
<dt><img style="display:none" src="plus.gif" id="exceptions"><a
target="detail" href="exceptions.html">Archive Exceptions</a>
<dd><div id="exceptions_detail"><dl class="page-index">
<dt><img style="display:none" src="dot.gif"><a target="detail"
href="exceptions.html#unregistered_class"><code>unregistered_class</code></a>
Index: wrappers.html
===================================================================
RCS file: /cvsroot/boost/boost/libs/serialization/doc/wrappers.html,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -d -r1.5 -r1.6
--- wrappers.html 5 Feb 2006 00:50:48 -0000 1.5
+++ wrappers.html 4 Jun 2006 01:42:55 -0000 1.6
@@ -7,7 +7,7 @@
http://www.boost.org/LICENSE_1_0.txt)
-->
<head>
-<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+<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 - Serialization Wrappers</title>
@@ -27,7 +27,9 @@
<hr>
<dl class="page-index">
<dt><a href="#binaryobjects">Binary Objects</a>
+ <dt><a href="#arrays">Arrays</a>
<dt><a href="#strong_type"><code style="white-space:
normal">BOOST_STRONG_TYPEDEF</code></a>
+ <dt><a href="#collection_size_type">Collection Sizes</a>
<dt><a href="#nvp">Name-Value Pairs</a>
<dt><a href="#composition">Composition</a>
</dl>
@@ -56,6 +58,45 @@
Note that it doesn't allocated any storage or create any objects.
Its sole purpose is to pass the data size and address as pair to the archive
class.
+
+<h3><a name="arrays">Arrays</a></h3>
+An array is a contiguous sequence of homogeneous data types, such as a builtin
+C-array, a <code>boost::array<T></code> or a
<code>std::vector<T></code>.
+The purpose of this wrapper is to support archive types (such as binary
+archives) that provide optimized serialization for contiguous sequences of
+objects of the same type.
+
+The header file
+<a href="../../../boost/serialization/array.hpp" target="array_hpp">
+array.hpp
+</a>
+includes the function
+<pre><code>
+template <T>
+boost::serialization::make_array(T* t, std::size_t size);
+</code></pre>
+which will construct a temporary <code>array</code> object
+<pre><code>
+template<class T>
+class array
+{
+public:
+ typedef T value_type;
+ array(value_type* t, std::size_t s);
+ value_type* address() const;
+ std::size_t count() const;
+};
+</code></pre>
+that can be serialized just like any other object.
+Its default serialization is to use serialize each array element.
+Note that it doesn't allocated any storage or create any objects.
+Its sole purpose is to pass the data type, size and address to the archive
class.
+
+Archive types that can provide optimized implementations for contiguous
+arrays of homogeneous data types should overload the serialization of
+<code>array</code>.
+
+
<h3><a name="strong_type"><code style="white-space:
normal">BOOST_STRONG_TYPEDEF</code></h3>
Another example of a serialization wrapper is the
<a href="strong_typedef.html"><code style="white-space:
normal">BOOST_STRONG_TYPEDEF</code></a> template.
@@ -67,6 +108,26 @@
these types are automatically converted to the underlying integer type so the
special overrides used for XML archives aren't needed for other archives.
+
+
+<h3><a name="collection_size_type">Collection Sizes</h3>
+An example of a strong typedef is the <code>collection_size_type</code> in the
+header file
+<a href="../../../boost/serialization/collection_size_type.hpp"
target="collection_size_type_hpp">
+collection_size_type.hpp
+</a>. This type should be used for serializaing the size of a C++ collection,
so
+that the archive can pick the best integral representation for the
serialization
+of collection sizes. This is necessary since, although <code>std::size_t</code>
+is guaranteed to be an integral type large enough to represent the size of
+a collection on a specific platform, the archive might want to serialize
+the size differently than this type. For example, the
<code>collection_size_type</code>
+might be serialized as a variable length integer in a portable binary archive.
+
+
+
+
+
+
<h3><a name="nvp">Name-Value Pairs</h3>
XML archives present a somewhat special case. XML format has a nested
structure that maps well to the "recursive class member visitor" pattern used
@@ -129,6 +190,8 @@
<a href="../example/demo_save.xml" target="demo_save_xml">Here</a>
is example of the XML Archive corresponding to our tutorial example.
+
+
<h3><a name="composition">Composition</h3>
Wrappers should be designed so that they can be composed as necessary.
For example, to pass binary data as a name value pair use:
_______________________________________________
Boost-cvs mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/boost-cvs
