Subject: [Boost-commit] svn:boost r56241 - trunk/libs/serialization/doc
From: ramey_at_[hidden]
Date: 2009-09-16 00:49:21
Author: ramey
Date: 2009-09-16 00:49:20 EDT (Wed, 16 Sep 2009)
New Revision: 56241
URL: http://svn.boost.org/trac/boost/changeset/56241
Log:
Updated documentation to explain compile-time errors and warnings
Text files modified:
trunk/libs/serialization/doc/contents.html | 1
trunk/libs/serialization/doc/rationale.html | 220 ----------------------------------------
2 files changed, 0 insertions(+), 221 deletions(-)
Modified: trunk/libs/serialization/doc/contents.html
==============================================================================
--- trunk/libs/serialization/doc/contents.html (original)
+++ trunk/libs/serialization/doc/contents.html 2009-09-16 00:49:20 EDT (Wed, 16 Sep 2009)
@@ -317,7 +317,6 @@
<dt><img style="display:none" src="dot.gif"><a target="detail" href="rationale.html#serialization">The term "serialization" is preferred to "persistence"</a></dt>
<dt><img style="display:none" src="dot.gif"><a target="detail" href="rationale.html#archives">Archives are not streams</a></dt>
<dt><img style="display:none" src="dot.gif"><a target="detail" href="rationale.html#typeid"><code style="white-space: normal">typeid</code> information is not included in archives</a></dt>
- <dt><img style="display:none" src="dot.gif"><a target="detail" href="rationale.html#trap">Compile time trap when saving a non-const value</a></dt>
</dl></div></dd>
<dt><img style="display:none" src="plus.gif" id="todo"><a target="detail" href="todo.html">To Do</a></dt>
Modified: trunk/libs/serialization/doc/rationale.html
==============================================================================
--- trunk/libs/serialization/doc/rationale.html (original)
+++ trunk/libs/serialization/doc/rationale.html 2009-09-16 00:49:20 EDT (Wed, 16 Sep 2009)
@@ -110,226 +110,6 @@
In effect, <code style="white-space: normal">export</code> generates a portable equivalent to
<code style="white-space: normal">typeid</code> information.
-<h2><a name="trap"></a>Compile time trap when saving a non-const value</h2>
-</p>
-The following code will fail to compile. The failure will occur on a line with a
-<code style="white-space: normal">BOOST_STATIC_ASSERT</code>.
-Here, we refer to this as a compile time trap.
-<code style="white-space: normal"><pre>
-T t;
-ar << t;
-</pre></code>
-
-unless the tracking_level serialization trait is set to "track_never". The following
-will compile without problem:
-
-<code style="white-space: normal"><pre>
-const T t
-ar << t;
-</pre></code>
-
-Likewise, the following code will trap at compile time:
-
-<code style="white-space: normal"><pre>
-T * t;
-ar >> t;
-</pre></code>
-
-if the tracking_level serialization trait is set to "track_never".
-<p>
-
-This behavior has been contraversial and may be revised in the future. The criticism
-is that it will flag code that is in fact correct and force users to insert
-<code style="white-space: normal">const_cast</code>. My view is that:
-<ul>
- <li>The trap is useful in detecting a certain class of programming errors.
- <li>Such errors would otherwise be difficult to detect.
- <li>The incovenience caused by including this trap is very small in relation
- to its benefits.
-</ul>
-
-The following case illustrates my position. It was originally used as an example in the
-mailing list by Peter Dimov.
-
-<code style="white-space: normal"><pre>
-class construct_from
-{
- ...
-};
-
-void main(){
- ...
- Y y;
- construct_from x(y);
- ar << x;
-}
-</pre></code>
-
-Suppose that there is no trap as described above.
-<ol>
- <li>this example compiles and executes fine. No tracking is done because
- construct_from has never been serialized through a pointer. Now some time
- later, the next programmer(2) comes along and makes an enhancement. He
- wants the archive to be sort of a log.
-
-<code style="white-space: normal"><pre>
-void main(){
- ...
- Y y;
- construct_from x(y);
- ar << x;
- ...
- x.f(); // change x in some way
- ...
- ar << x
-}
-</pre></code>
- <p>
- Again no problem. He gets two different of copies in the archive, each one is different.
- That is he gets exactly what he expects and is naturally delighted.
- <p>
- <li>Now sometime later, a third programmer(3) sees construct_from and says -
- oh cool, just what I need. He writes a function in a totally disjoint
- module. (The project is so big, he doesn't even realize the existence of
- the original usage) and writes something like:
-
-<code style="white-space: normal"><pre>
-class K {
- shared_ptr <construct_from> z;
- template <class Archive>
- void serialize(Archive & ar, const unsigned version){
- ar << z;
- }
-};
-</pre></code>
-
- <p>
- He builds and runs the program and tests his new functionality. It works
- great and he's delighted.
- <p>
- <li>Things continue smoothly as before. A month goes by and it's
- discovered that when loading the archives made in the last month (reading the
- log). Things don't work. The second log entry is always the same as the
- first. After a series of very long and increasingly acrimonius email exchanges,
-its discovered
- that programmer (3) accidently broke programmer(2)'s code .This is because by
- serializing via a pointer, the "log" object now being tracked. This is because
- the default tracking behavior is "track_selectively". This means that class
- instances are tracked only if they are serialized through pointers anywhere in
- the program. Now multiple saves from the same address result in only the first one
- being written to the archive. Subsequent saves only add the address - even though the
- data might have been changed. When it comes time to load the data, all instances of the log record show the same data.
- In this way, the behavior of a functioning piece of code is changed due the side
- effect of a change in an otherwise disjoint module.
- Worse yet, the data has been lost and cannot not be now recovered from the archives.
- People are really upset and disappointed with boost (at least the serialization system).
- <p>
- <li>
- After a lot of investigation, it's discovered what the source of the problem
- and class construct_from is marked "track_never" by including:
-<code style="white-space: normal"><pre>
-BOOST_CLASS_TRACKING(construct_from, track_never)
-</pre></code>
- <li>Now everything works again. Or - so it seems.
- <p>
- <li><code style="white-space: normal">shared_ptr<construct_from></code>
-is not going to have a single raw pointer shared amongst the instances. Each loaded
-<code style="white-space: normal">shared_ptr<construct_from></code> is going to
-have its own distinct raw pointer. This will break
-<code style="white-space: normal">shared_ptr</code> and cause a memory leak. Again,
-The cause of this problem is very far removed from the point of discovery. It could
-well be that the problem is not even discovered until after the archives are loaded.
-Now we not only have difficult to find and fix program bug, but we have a bunch of
-invalid archives and lost data.
-</ol>
-
-Now consider what happens when the trap is enabled:.
-
-<ol>
- <p>
- <li>Right away, the program traps at
-<code style="white-space: normal"><pre>
-ar << x;
-</pre></code>
- <p>
- <li>The programmer curses (another %^&*&* hoop to jump through). If he's in a
- hurry (and who isn't) and would prefer not to <code style="white-space: normal">const_cast</code>
- - because it looks bad. So he'll just make the following change an move on.
-<code style="white-space: normal"><pre>
-Y y;
-const construct_from x(y);
-ar << x;
-</pre></code>
- <p>
- Things work fine and he moves on.
- <p>
- <li>Now programer (2) wants to make his change - and again another
- annoying const issue;
-<code style="white-space: normal"><pre>
-Y y;
-const construct_from x(y);
-...
-x.f(); // change x in some way ; compile error f() is not const
-...
-ar << x
-</pre></code>
- <p>
- He's mildly annoyed now he tries the following:
- <ul>
- <li>He considers making f() a const - but presumable that shifts the const
- error to somewhere else. And his doesn't want to fiddle with "his" code to
- work around a quirk in the serializaition system
- <p>
- <li>He removes the <code style="white-space: normal">const</code>
- from <code style="white-space: normal">const construct_from</code> above - damn now he
- gets the trap. If he looks at the comment code where the
- <code style="white-space: normal">BOOST_STATIC_ASSERT</code>
- occurs, he'll do one of two things
- <ol>
- <p>
- <li>This is just crazy. Its making my life needlessly difficult and flagging
- code that is just fine. So I'll fix this with a <code style="white-space: normal">const_cast</code>
- and fire off a complaint to the list and mabe they will fix it.
- In this case, the story branches off to the previous scenario.
- <p>
- <li>Oh, this trap is suggesting that the default serialization isn't really
- what I want. Of course in this particular program it doesn't matter. But
- then the code in the trap can't really evaluate code in other modules (which
- might not even be written yet). OK, I'll add the following to my
- construct_from.hpp to solve the problem.
-<code style="white-space: normal"><pre>
-BOOST_CLASS_TRACKING(construct_from, track_never)
-</pre></code>
- </ol>
- </ul>
- <p>
- <li>Now programmer (3) comes along and make his change. The behavior of the
- original (and distant module) remains unchanged because the
- <code style="white-space: normal">construct_from</code> trait has been set to
- "track_never" so he should always get copies and the log should be what we expect.
- <p>
- <li>But now he gets another trap - trying to save an object of a
- class marked "track_never" through a pointer. So he goes back to
- construct_from.hpp and comments out the
- <code style="white-space: normal">BOOST_CLASS_TRACKING</code> that
- was inserted. Now the second trap is avoided, But damn - the first trap is
- popping up again. Eventually, after some code restructuring, the differing
- requirements of serializating <code style="white-space: normal">construct_from</code>
- are reconciled.
-</ol>
-Note that in this second scenario
-<ul>
- <li>all errors are trapped at compile time.
- <li>no invalid archives are created.
- <li>no data is lost.
- <li>no runtime errors occur.
-</ul>
-
-It's true that these traps may sometimes flag code that is currently correct and
-that this may be annoying to some programmers. However, this example illustrates
-my view that these traps are useful and that any such annoyance is small price to
-pay to avoid particularly vexing programming errors.
-
<!--
<h2><a name="footnotes"></a>Footnotes</h2>
<dl>