|
|
Boost-Commit : |
Subject: [Boost-commit] svn:boost r59848 - in sandbox/tokenmap/libs/tokenmap/doc: . html html/tokenmap
From: sl_at_[hidden]
Date: 2010-02-22 19:29:33
Author: sl_
Date: 2010-02-22 19:29:33 EST (Mon, 22 Feb 2010)
New Revision: 59848
URL: http://svn.boost.org/trac/boost/changeset/59848
Log:
expanded rationale
Text files modified:
sandbox/tokenmap/libs/tokenmap/doc/html/index.html | 4 ++--
sandbox/tokenmap/libs/tokenmap/doc/html/tokenmap/examples_.html | 2 +-
sandbox/tokenmap/libs/tokenmap/doc/html/tokenmap/quick_tutorial.html | 2 +-
sandbox/tokenmap/libs/tokenmap/doc/html/tokenmap/rationale_.html | 27 +++++++++++++++++++++------
sandbox/tokenmap/libs/tokenmap/doc/html/tokenmap/reference.html | 10 +++++-----
sandbox/tokenmap/libs/tokenmap/doc/tokenmap.qbk | 19 ++++++++++++++-----
6 files changed, 44 insertions(+), 20 deletions(-)
Modified: sandbox/tokenmap/libs/tokenmap/doc/html/index.html
==============================================================================
--- sandbox/tokenmap/libs/tokenmap/doc/html/index.html (original)
+++ sandbox/tokenmap/libs/tokenmap/doc/html/index.html 2010-02-22 19:29:33 EST (Mon, 22 Feb 2010)
@@ -27,7 +27,7 @@
</h3></div></div>
<div><p class="copyright">Copyright © 2009 Slawomir Lisznianski</p></div>
<div><div class="legalnotice">
-<a name="id555037"></a><p>
+<a name="id494314"></a><p>
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)
</p>
@@ -66,7 +66,7 @@
</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
-<td align="left"><p><small>Last revised: February 21, 2010 at 20:33:57 GMT</small></p></td>
+<td align="left"><p><small>Last revised: February 23, 2010 at 00:29:04 GMT</small></p></td>
<td align="right"><div class="copyright-footer"></div></td>
</tr></table>
<hr>
Modified: sandbox/tokenmap/libs/tokenmap/doc/html/tokenmap/examples_.html
==============================================================================
--- sandbox/tokenmap/libs/tokenmap/doc/html/tokenmap/examples_.html (original)
+++ sandbox/tokenmap/libs/tokenmap/doc/html/tokenmap/examples_.html 2010-02-22 19:29:33 EST (Mon, 22 Feb 2010)
@@ -32,7 +32,7 @@
them:
</p>
<div class="table">
-<a name="id565290"></a><p class="title"><b>Table 1.1. Tutorial examples</b></p>
+<a name="id504567"></a><p class="title"><b>Table 1.1. Tutorial examples</b></p>
<div class="table-contents"><table class="table" summary="Tutorial examples">
<colgroup>
<col>
Modified: sandbox/tokenmap/libs/tokenmap/doc/html/tokenmap/quick_tutorial.html
==============================================================================
--- sandbox/tokenmap/libs/tokenmap/doc/html/tokenmap/quick_tutorial.html (original)
+++ sandbox/tokenmap/libs/tokenmap/doc/html/tokenmap/quick_tutorial.html 2010-02-22 19:29:33 EST (Mon, 22 Feb 2010)
@@ -27,7 +27,7 @@
<a name="tokenmap.quick_tutorial"></a><a class="link" href="quick_tutorial.html" title="Quick tutorial">Quick tutorial</a>
</h2></div></div></div>
<p>
- Start by including a convenience header avaiable in the boost directory:
+ Start by including the convenience header available in the boost directory:
</p>
<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">tokenmap</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span>
</pre>
Modified: sandbox/tokenmap/libs/tokenmap/doc/html/tokenmap/rationale_.html
==============================================================================
--- sandbox/tokenmap/libs/tokenmap/doc/html/tokenmap/rationale_.html (original)
+++ sandbox/tokenmap/libs/tokenmap/doc/html/tokenmap/rationale_.html 2010-02-22 19:29:33 EST (Mon, 22 Feb 2010)
@@ -27,12 +27,27 @@
<a name="tokenmap.rationale_"></a><a class="link" href="rationale_.html" title="Rationale">Rationale </a>
</h2></div></div></div>
<p>
- Network applications often require keeping track of sessions where a "session
- key" is exchanged between a server and a client. The server then keeps
- track of the client's state by having the session key mapped to an in-memory
- "session object". Today, developers often use <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">map</span></code> for
- this purpose, which has sub-optimal performance and requires users to come
- up with sufficiently hard to guess random keys.
+ Network applications based on various stateless protocols (UDP, HTTP) often
+ require keeping track of sessions where a "session key" is exchanged
+ between a server and a client. The server then maintains the client's state
+ by having the session key mapped to an in-memory session object. Today, developers
+ often use <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">map</span></code> for the purpose of such mapping, which
+ has sub-optimal performance and requires users to come up with sufficiently
+ hard to guess random keys.
+ </p>
+<p>
+ Another example is that of an API of a shared library. Consider a library which
+ internally manages resources on behave of its users. As an API author, you
+ may wish not to share certain implementation details, such as pointers or iterators,
+ with your users yet you would like to efficiently dispatch API calls. When
+ you use <code class="computeroutput"><span class="identifier">tokenmap</span></code> generated
+ keys, you are not sharing any such implementation details, ensuring users cannot
+ corrupt your internally managed state.
+ </p>
+<p>
+ Additionally, since we're not dereferencing tokens, unlike pointers, it is
+ perfectly OK for them to outlive the mapped-to-objects without the usual consequences
+ of accessing stale pointers.
</p>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
Modified: sandbox/tokenmap/libs/tokenmap/doc/html/tokenmap/reference.html
==============================================================================
--- sandbox/tokenmap/libs/tokenmap/doc/html/tokenmap/reference.html (original)
+++ sandbox/tokenmap/libs/tokenmap/doc/html/tokenmap/reference.html 2010-02-22 19:29:33 EST (Mon, 22 Feb 2010)
@@ -27,7 +27,7 @@
<a name="tokenmap.reference"></a><a class="link" href="reference.html" title="Reference">Reference</a>
</h2></div></div></div>
<a name="tokenmap.reference.headers"></a><h4>
-<a name="id564285"></a>
+<a name="id503562"></a>
<a class="link" href="reference.html#tokenmap.reference.headers">Headers</a>
</h4>
<p>
@@ -36,7 +36,7 @@
to boost namespace.
</p>
<a name="tokenmap.reference.synopsis"></a><h4>
-<a name="id564312"></a>
+<a name="id503589"></a>
<a class="link" href="reference.html#tokenmap.reference.synopsis">Synopsis</a>
</h4>
<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span>
@@ -83,15 +83,15 @@
</span><span class="special">}</span> <span class="comment">// namespace boost
</span></pre>
<a name="tokenmap.reference.class_template_tokenmap"></a><h4>
-<a name="id564899"></a>
+<a name="id504176"></a>
<a class="link" href="reference.html#tokenmap.reference.class_template_tokenmap">Class template tokenmap</a>
</h4>
<a name="tokenmap.reference.nested_types"></a><h4>
-<a name="id564914"></a>
+<a name="id504191"></a>
<a class="link" href="reference.html#tokenmap.reference.nested_types">Nested types</a>
</h4>
<a name="tokenmap.reference.constructors__copy_and_assignment"></a><h4>
-<a name="id564928"></a>
+<a name="id504205"></a>
<a class="link" href="reference.html#tokenmap.reference.constructors__copy_and_assignment">Constructors,
copy and assignment</a>
</h4>
Modified: sandbox/tokenmap/libs/tokenmap/doc/tokenmap.qbk
==============================================================================
--- sandbox/tokenmap/libs/tokenmap/doc/tokenmap.qbk (original)
+++ sandbox/tokenmap/libs/tokenmap/doc/tokenmap.qbk 2010-02-22 19:29:33 EST (Mon, 22 Feb 2010)
@@ -114,7 +114,7 @@
[section Quick tutorial]
-Start by including a convenience header avaiable in the boost directory:
+Start by including the convenience header available in the boost directory:
#include <boost/tokenmap.hpp>
@@ -249,12 +249,21 @@
[section Rationale ]
-Network applications often require keeping track of sessions where a "session key" is
-exchanged between a server and a client. The server then keeps track of the client's
-state by having the session key mapped to an in-memory "session object".
-Today, developers often use `std::map` for this purpose, which has sub-optimal
+Network applications based on various stateless protocols (UDP, HTTP) often require keeping
+track of sessions where a "session key" is exchanged between a server and a client. The server
+then maintains the client's state by having the session key mapped to an in-memory session object.
+Today, developers often use `std::map` for the purpose of such mapping, which has sub-optimal
performance and requires users to come up with sufficiently hard to guess random keys.
+Another example is that of an API of a shared library. Consider a library which internally manages
+resources on behave of its users. As an API author, you may wish not to share certain
+implementation details, such as pointers or iterators, with your users yet you would
+like to efficiently dispatch API calls. When you use `tokenmap` generated keys, you are not sharing
+any such implementation details, ensuring users cannot corrupt your internally managed state.
+
+Additionally, since we're not dereferencing tokens, unlike pointers, it is perfectly OK for them
+to outlive the mapped-to-objects without the usual consequences of accessing stale pointers.
+
[endsect]
[section Acknowledgements ]
Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk