ceph/src/boost/libs/flyweight/doc/reference/tracking.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0.1 Transitional//EN">
   2
   3 <html>
   4 <head>
   5 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
   6 <title>Boost.Flyweight Documentation - Tracking policies reference</title>
   7 <link rel="stylesheet" href="../style.css" type="text/css">
   8 <link rel="start" href="../index.html">
   9 <link rel="prev" href="locking.html">
  10 <link rel="up" href="index.html">
  11 <link rel="next" href="../performance.html">
  12 </head>
  13
  14 <body>
  15 <h1><img src="../../../../boost.png" alt="Boost logo" align=
  16 "middle" width="277" height="86">Boost.Flyweight
  17 Tracking policies reference</h1>
  18
  19 <div class="prev_link"><a href="locking.html"><img src="../prev.gif" alt="locking policies" border="0"><br>
  20 Locking policies
  21 </a></div>
  22 <div class="up_link"><a href="index.html"><img src="../up.gif" alt="Boost.Flyweight reference" border="0"><br>
  23 Boost.Flyweight reference
  24 </a></div>
  25 <div class="next_link"><a href="../performance.html"><img src="../next.gif" alt="performance" border="0"><br>
  26 Performance
  27 </a></div><br clear="all" style="clear: all;">
  28
  29 <hr>
  30
  31 <h2>Contents</h2>
  32
  33 <ul>
  34   <li><a href="#preliminary">Preliminary concepts</a></li>
  35   <li><a href="#tracking">Tracking policies</a></li>
  36   <li><a href="#tracking_tag_synopsis">Header
  37     <code>"boost/flyweight/tracking_tag.hpp"</code> synopsis</a>
  38     <ul>
  39       <li><a href="#is_tracking">Class template <code>is_tracking</code></a></li>
  40       <li><a href="#tracking_construct">Class template <code>tracking</code></a></li>
  41     </ul>
  42   </li>
  43   <li><a href="#refcounted_fwd_synopsis">Header
  44     <code>"boost/flyweight/refcounted_fwd.hpp"</code> synopsis</a>
  45   </li>
  46   <li><a href="#refcounted_synopsis">Header
  47     <code>"boost/flyweight/refcounted.hpp"</code> synopsis</a>
  48     <ul>
  49       <li><a href="#refcounted">Class <code>refcounted</code></a></li>
  50     </ul>
  51   </li>
  52   <li><a href="#no_tracking_fwd_synopsis">Header
  53     <code>"boost/flyweight/no_tracking_fwd.hpp"</code> synopsis</a>
  54   </li>
  55   <li><a href="#no_tracking_synopsis">Header
  56     <code>"boost/flyweight/no_tracking.hpp"</code> synopsis</a>
  57     <ul>
  58       <li><a href="#no_tracking">Class <code>no_tracking</code></a></li>
  59     </ul>
  60   </li>
  61 </ul>
  62
  63 <h2><a name="preliminary">Preliminary concepts</a></h2>
  64
  65 <p>
  66 A <i>tracking policy helper</i> provides access to some of the functionality
  67 of a <a href="factories.html#factory">factory</a> so as to be used
  68 in the implementation of an associated <a href="#tracking"><code>Tracking Policy</code></a>.
  69 In the following table, <code>TrackingHelper</code> is a tracking policy
  70 helper associated to a <a href="factories.html#factory">factory</a> type
  71 <code>Factory</code> of elements of type <code>Entry</code>, <code>h</code>
  72 is a value of
  73 <code>Factory::handle_type</code> associated to a <code>Factory</code> <code>f</code>
  74 and <code>check</code> is a value of
  75 a <a href="http://www.sgi.com/tech/stl/Predicate.html"><code>Predicate</code></a>
  76 type <code>Checker</code> with argument of type <code>Factory::handle_type</code>.
  77 </p>
  78
  79 <p align="center">
  80 <table cellspacing="0">
  81   <caption><b>Tracking Policy Helper requirements.</b></caption>
  82 <tr>
  83   <th align="center">expression</th>
  84   <th align="center">return type</th>
  85   <th align="center">assertion/note<br>pre/post-condition</th>
  86 </tr>
  87 <tr>
  88   <td><code>TrackingHelper::entry(h);</code></td>
  89   <td><code>const Entry&amp;</code></td>
  90   <td>Returns <code>f.entry(h)</code>.</td>
  91 </tr>
  92 <tr class="odd_tr">
  93   <td><code>TrackingHelper::erase(h,check);</code></td>
  94   <td><code>void</code></td>
  95   <td>If <code>check(h)</code>, invokes <code>f.erase(h)</code>.</td>
  96 </tr>
  97 </table>
  98 </p>
  99
 100 <p>
 101 The execution of <code>TrackingHelper::erase</code> (including the
 102 invocation of <code>check(h)</code>) is done in a
 103 synchronized manner so as to prevent any other thread of execution from
 104 simultaneously accessing the factory's insertion or deletion facilities.
 105 </p>
 106
 107 <h2><a name="tracking">Tracking policies</a></h2>
 108
 109 <p>
 110 A <i>tracking policy</i> defines the strategy to be followed by a
 111 <a href="flyweight.html#flyweight"><code>flyweight</code></a> instantiation when
 112 all the flyweight objects associated to a given value are destroyed.
 113 The tracking policy contributes some type information necessary for the
 114 definition of the <code>flyweight</code> internal
 115 <a href="factories.html#factory">factory</a>.
 116 </p>
 117
 118 <p>
 119 A type <code>Tracking</code> is a tracking policy if:
 120 <ul>
 121   <li>One of the following conditions is satisfied:
 122     <ol type="a">
 123       <li><a href="#is_tracking"><code>is_tracking&lt;Tracking&gt;::type</code></a> is
 124       <a href="../../../mpl/doc/refmanual/bool.html"><code>boost::mpl::true_</code></a>,</li>
 125       <li><code>Tracking</code> is of the form
 126       <a href="#tracking_construct"><code>tracking&lt;Tracking'&gt;</code></a>.</li>
 127     </ol>
 128   </li>
 129   <li>The expression <code>Tracking::entry_type</code> (or
 130     <code>Tracking'::entry_type</code> if (b) applies) is an
 131     <a href="../../../mpl/doc/refmanual/lambda-expression.html"><code>MPL Lambda
 132     Expression</code></a> that resolves, when invoked with different types
 133     (<code>Value</code>,<code>Key</code>) such that <code>Value</code> is
 134     <a href="http://www.sgi.com/tech/stl/Assignable.html"><code>Assignable</code></a>
 135     and implicitly convertible to <code>const Key&amp;</code>, to an
 136     <a href="http://www.sgi.com/tech/stl/Assignable.html"><code>Assignable</code></a>
 137     type <code>Entry</code> implicitly convertible to both <code>const Value&amp;</code>
 138     and <code>const Key&amp;</code>.
 139   </li>
 140   <li>The expression <code>Tracking::handle_type</code> (or
 141     <code>Tracking'::handle_type</code> if (b) applies) is an
 142     <a href="../../../mpl/doc/refmanual/lambda-expression.html"><code>MPL Lambda
 143     Expression</code></a>; this expression, when invoked with types
 144     (<code>InternalHandle</code>,<a href="#preliminary"><code>TrackingHelper</code></a>),
 145     with <code>InternalHandle</code> being
 146     <a href="http://www.sgi.com/tech/stl/Assignable.html"><code>Assignable</code></a>
 147     and providing the nothrow guarantee for copy and assignment,
 148     resolves to an
 149     <a href="http://www.sgi.com/tech/stl/Assignable.html"><code>Assignable</code></a>
 150     type <code>Handle</code> which also provides the nothrow guarantee for
 151     copy and assignment and is constructible from and implicitly
 152     convertible to <code>InternalHandle</code>.
 153     <code>TrackingHelper</code> is an incomplete type at the time of
 154     invocation of <code>Tracking::handle_type</code>.
 155   </li>
 156 </ul>
 157 <code>Tracking::handle_type</code> is parameterized by a helper that provides
 158 access to some of the functionality of the factory associated to the
 159 tracking policy. This factory's associated entry and handle types are the types
 160 <code>Entry</code> and <code>Handle</code> defined above, respectively.
 161 </p>
 162
 163 <h2><a name="tracking_tag_synopsis">Header
 164 <a href="../../../../boost/flyweight/tracking_tag.hpp"><code>"boost/flyweight/tracking_tag.hpp"</code></a> synopsis</a></h2>
 165
 166 <blockquote><pre>
 167 <span class=keyword>namespace</span> <span class=identifier>boost</span><span class=special>{</span>
 168
 169 <span class=keyword>namespace</span> <span class=identifier>flyweights</span><span class=special>{</span>
 170
 171 <span class=keyword>struct</span> <span class=identifier>tracking_marker</span><span class=special>;</span>
 172
 173 <span class=keyword>template</span><span class=special>&lt;</span><span class=keyword>typename</span> <span class=identifier>T</span><span class=special>&gt;</span>
 174 <span class=keyword>struct</span> <span class=identifier>is_tracking</span>
 175
 176 <span class=keyword>template</span><span class=special>&lt;</span><span class=keyword>typename</span> <span class=identifier>T</span><span class=special>&gt;</span>
 177 <span class=keyword>struct</span> <span class=identifier>tracking</span><span class=special>;</span>
 178
 179 <span class=special>}</span> <span class=comment>// namespace boost::flyweights</span>
 180
 181 <span class=special>}</span> <span class=comment>// namespace boost</span>
 182 </pre></blockquote>
 183
 184 <h3><a name="is_tracking">Class template <code>is_tracking</code></a></h3>
 185
 186 <p>
 187 Unless specialized by the user, <code>is_tracking&lt;T&gt;::type</code> is
 188 <a href="../../../mpl/doc/refmanual/bool.html"><code>boost::mpl::true_</code></a>
 189 if <code>T</code> is derived from <code>tracking_marker</code>, and it is
 190 <a href="../../../mpl/doc/refmanual/bool.html"><code>boost::mpl::false_</code></a>
 191 otherwise.
 192 </p>
 193
 194 <h3><a name="tracking_construct">Class template <code>tracking</code></a></h3>
 195
 196 <p>
 197 <code>tracking&lt;T&gt;</code> is a syntactic construct meant to indicate
 198 that <code>T</code> is a tracking policy without resorting to the
 199 mechanisms provided by the <code>is_tracking</code> class template.
 200 </p>
 201
 202 <h2><a name="refcounted_fwd_synopsis">Header
 203 <a href="../../../../boost/flyweight/refcounted_fwd.hpp"><code>"boost/flyweight/refcounted_fwd.hpp"</code></a> synopsis</a></h2>
 204
 205 <blockquote><pre>
 206 <span class=keyword>namespace</span> <span class=identifier>boost</span><span class=special>{</span>
 207
 208 <span class=keyword>namespace</span> <span class=identifier>flyweights</span><span class=special>{</span>
 209
 210 <span class=keyword>struct</span> <span class=identifier>refcounted</span><span class=special>;</span>
 211
 212 <span class=special>}</span> <span class=comment>// namespace boost::flyweights</span>
 213
 214 <span class=special>}</span> <span class=comment>// namespace boost</span>
 215 </pre></blockquote>
 216
 217 <p>
 218 <code>refcounted_fwd.hpp</code> forward declares the class
 219 <a href="#refcounted"><code>refcounted</code></a>.
 220 </p>
 221
 222 <h2><a name="refcounted_synopsis">Header
 223 <a href="../../../../boost/flyweight/refcounted.hpp"><code>"boost/flyweight/refcounted.hpp"</code></a> synopsis</a></h2>
 224
 225 <h3><a name="refcounted">Class <code>refcounted</code></a></h3>
 226
 227 <p>
 228 <a href="#tracking"><code>Tracking Policy</code></a> providing
 229 <a href="flyweight.html#flyweight"><code>flyweight</code></a>
 230 instantiations with reference counting semantics: when all the flyweight objects
 231 associated to a given value are destroyed, the corresponding entry is
 232 erased from <code>flyweight</code>'s internal
 233 <a href="factories.html#factory">factory</a>.
 234 </p>
 235
 236 <h2><a name="no_tracking_fwd_synopsis">Header
 237 <a href="../../../../boost/flyweight/no_tracking_fwd.hpp"><code>"boost/flyweight/no_tracking_fwd.hpp"</code></a> synopsis</a></h2>
 238
 239 <blockquote><pre>
 240 <span class=keyword>namespace</span> <span class=identifier>boost</span><span class=special>{</span>
 241
 242 <span class=keyword>namespace</span> <span class=identifier>flyweights</span><span class=special>{</span>
 243
 244 <span class=keyword>struct</span> <span class=identifier>no_tracking</span><span class=special>;</span>
 245
 246 <span class=special>}</span> <span class=comment>// namespace boost::flyweights</span>
 247
 248 <span class=special>}</span> <span class=comment>// namespace boost</span>
 249 </pre></blockquote>
 250
 251 <p>
 252 <code>no_tracking_fwd.hpp</code> forward declares the class
 253 <a href="#no_tracking"><code>no_tracking</code></a>.
 254 </p>
 255
 256 <h2><a name="no_tracking_synopsis">Header
 257 <a href="../../../../boost/flyweight/no_tracking.hpp"><code>"boost/flyweight/no_tracking.hpp"</code></a> synopsis</a></h2>
 258
 259 <h3><a name="no_tracking">Class <code>no_tracking</code></a></h3>
 260
 261 <p>
 262 Null <a href="#tracking"><code>Tracking Policy</code></a>: elements inserted
 263 into <code>flyweight</code>'s internal <a href="factories.html#factory">factory</a>
 264 are not erased until program termination.
 265 </p>
 266
 267 <hr>
 268
 269 <div class="prev_link"><a href="locking.html"><img src="../prev.gif" alt="locking policies" border="0"><br>
 270 Locking policies
 271 </a></div>
 272 <div class="up_link"><a href="index.html"><img src="../up.gif" alt="Boost.Flyweight reference" border="0"><br>
 273 Boost.Flyweight reference
 274 </a></div>
 275 <div class="next_link"><a href="../performance.html"><img src="../next.gif" alt="performance" border="0"><br>
 276 Performance
 277 </a></div><br clear="all" style="clear: all;">
 278
 279 <br>
 280
 281 <p>Revised August 18th 2008</p>
 282
 283 <p>&copy; Copyright 2006-2008 Joaqu&iacute;n M L&oacute;pez Mu&ntilde;oz.
 284 Distributed under the Boost Software
 285 License, Version 1.0. (See accompanying file <a href="../../../../LICENSE_1_0.txt">
 286 LICENSE_1_0.txt</a> or copy at <a href="http://www.boost.org/LICENSE_1_0.txt">
 287 http://www.boost.org/LICENSE_1_0.txt</a>)
 288 </p>
 289
 290 </body>
 291 </html>