Gitiles
Code Review Sign In
realtimeroboticsgroup.org / RealtimeRoboticsGroup / test / 8867871aeb9c37ba820d65ee7f86a24870425dfc / . / doc / derivation.html
blob: 31a88192b338b58917f17ea03c7721d3757ba14d [file] [log] [blame]
Brian Silverman88678712018-08-04 23:56:48 -0700[diff] [blame^]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 .
5Use, modification and distribution is subject to the Boost Software
6License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
7http://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 - Derivation from an Existing Archive</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">Derivation from an Existing Archive</h2>
24 </td>
25 </tr>
26</table>
27<hr>
28<dl class="page-index">
29</dl>
30
31<h3>Log Archive</h3>
32It may happen that one wants to create a new archive class by derivation from one
33of the included ones. Included is a sample program that shows how to derive a
34new archive from one of the ones included with the library. The first example is
35<a href="../example/demo_log.cpp" target="demo_log_cpp">
36demo_log.cpp</a>.
37<p>
38This derivation from the xml archive writes output in xml without the extra
39information required to read the data back into the application. It might be
40used to export one's data as simple xml for other applications or for logging
41data while debugging.
42<p>
43To this end it is derived from the included xml archive and the save functions for
44some types are specialized for this application.
45<p>
46The serialization library is
47implemented using the <b>C</b>uriously <b>R</b>ecurring <b>T</b>emplate
48<b>P</b>attern (<b>CRTP</b>). Also, all common code is factored out into
49separate modules to minimize code repetition. This makes derivation from
50an existing archive less straightforward than it would otherwise be.
51<p>
52This example illustrates several issues that have to be addressed when doing
53something like this
54<ol>
55 <li><i>It is derived from</i> <code style="white-space: normal">xml_oarchive_impl<log_archive></code>
56 <b>NOT</b> <code style="white-space: normal">xml_oarchive</code> <br>
57As described in the comments in
58<a href="../../../boost/archive/xml_oarchive.hpp" target="xml_oarchive_hpp">xml_oarchive.hpp</a>.
59<code style="white-space: normal">xml_oarchive</code> really a shorthand name for
60<code style="white-space: normal">xml_oarchive_impl&lt;xml_oarchive&gt;</code>. So we should derive
61from <code style="white-space: normal">xml_oarchive_impl&lt;log_archive&gt;</code> rather
62than <code style="white-space: normal">xml_oarchive</code>.
63<pre><code>
64class log_archive :
65 // don't derive from xml_oarchive !!!
66 public xml_oarchive_impl&lt;log_archive&gt;
67{
68...
69</code></pre>
70 <li><i>Note the</i> <code style="white-space: normal">log_archive</code> <i>between the</i> &lt;&gt;
71This is required so that base classes can downcast their <code style="white-space: normal">this</code> pointer
72to the most derived class. This is referred to as <b>C</b>uriously <b>R</b>ecurring
73<b>T</b>emplate <b>P</b>attern (<b>CRTP</b>) <a href="bibliography.html#11">[11]</a>.
74It is used to implement static polymorphism.
75 <li><i>Base classes need to be explicitly given access to the derived class.</i>
76This can be done by making members public or by including friend declarations for
77the base classes.
78<pre><code>
79 friend class detail::common_oarchive&lt;log_archive&gt;;
80 friend class basic_xml_oarchive&lt;log_archive&gt;;
81 friend class boost::serialization::save_access;
82</code></pre>
83
84 <li><i></i>Reread <a target="detail" href="headers.html#archiveinternals">Archive Internals</a>.
85This describes the class hierarchy so that you know what to override.
86 <li><i>Note the usage of PFTO.</i> Some compilers fail to provide support for
87partial function template ordering. The serialization library works around this by
88using <a target="detail" href="implementation.html#functiontemplateordering">
89<b>P</b>artial <b>F</b>unction <b>T</b>emplate <b>O</b>rdering</a> in several places.
90This is done
91in several places, including the archive classes themselves.
92 <li><i>Base class functions will usually need to be explicitly invoked.</i>
93We commonly specialize the function name <code style="white-space: normal">save_override</code>
94for saving primitives. Usage of a function name in a derived class
95"hides" similarly named functions of the base class. That is,
96function name overloading doesn't automatically
97include base classes. To address this, we can use:
98<pre><code>
99 using xml_oarchive_impl&lt;derived_t&gt;::save;
100 void save(const unsigned int t);
101 ...
102</code></pre>
103which should work on conforming compilers. However, I have found
104that the following equivalent works on more compilers.
105<pre><code>
106 // default fall through for any types not specified here
107 template&lt;class T&gt;
108 void save(const T & t){
109 xml_oarchive_impl&lt;derived_t&gt;::save(t);
110 }
111 void save(const unsigned int t);
112 ...
113</code></pre>
114so it's what I use.
115 <li><i>Template definitions of base classes may have to be explicitly instantiated.</i>
116 The demo includes
117<pre><code>
118// explicitly instantiate for this type of binary stream
119#include &lt;boost/archive/basic_binary_oprimitive.ipp&gt;
120</code></pre>
121for just this purpose. Failure to include required template definitions
122will result in undefined symbol errors when the program is linked.
123 <li><i>Without alteration, this class cannot be further derived from.</i><br>
124Base classes using <b>CRTP</b> must be templates with a parameter corresponding to
125the most derived class. As presented here, this class doesn't qualify, so
126it cannot be used as a base class. In order to derive further from this class,
127it would have to be reorganized along the lines of the original <code style="white-space: normal">xml_oarchive</code>.
128Specifically, it would look something like:
129<pre><code>
130template&lt;class Archive&gt;
131class log_archive_impl :
132 // don't derive from xml_oarchive !!!
133 public xml_oarchive_impl&lt;Archive&gt;
134{
135 ...
136);
137
138// do not derive from this class !!!
139class log_archive :
140 public log_archive_impl&lt;log_archive&gt;
141{
142public:
143 log_archive(std::ostream & os, unsigned int flags = 0) :
144 log_archive_impl&lt;xml_oarchive&gt;(os, flags)
145 {}
146};
147</code></pre>
148
149</ol>
150
151<hr>
152<p><i>&copy; Copyright <a href="http://www.rrsd.com">Robert Ramey</a> 2002-2004.
153Distributed under the Boost Software License, Version 1.0. (See
154accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
155</i></p>
156</body>
157</html>