ceph/src/boost/libs/flyweight/doc/reference/locking.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 - Locking 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="factories.html">
  10 <link rel="up" href="index.html">
  11 <link rel="next" href="tracking.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 Locking policies reference</h1>
  18
  19 <div class="prev_link"><a href="holders.html"><img src="../prev.gif" alt="holders" border="0"><br>
  20 Holders
  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="tracking.html"><img src="../next.gif" alt="tracking policies" border="0"><br>
  26 Tracking policies
  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="#locking">Locking policies</a></li>
  36   <li><a href="#locking_tag_synopsis">Header
  37     <code>"boost/flyweight/locking_tag.hpp"</code> synopsis</a>
  38     <ul>
  39       <li><a href="#is_locking">Class template <code>is_locking</code></a></li>
  40       <li><a href="#locking_construct">Class template <code>locking</code></a></li>
  41     </ul>
  42   </li>
  43   <li><a href="#simple_locking_fwd_synopsis">Header
  44     <code>"boost/flyweight/simple_locking_fwd.hpp"</code> synopsis</a>
  45   </li>
  46   <li><a href="#simple_locking_synopsis">Header
  47     <code>"boost/flyweight/simple_locking.hpp"</code> synopsis</a>
  48     <ul>
  49       <li><a href="#simple_locking">Class <code>simple_locking</code></a></li>
  50     </ul>
  51   </li>
  52   <li><a href="#no_locking_fwd_synopsis">Header
  53     <code>"boost/flyweight/no_locking_fwd.hpp"</code> synopsis</a>
  54   </li>
  55   <li><a href="#no_locking_synopsis">Header
  56     <code>"boost/flyweight/no_locking.hpp"</code> synopsis</a>
  57     <ul>
  58       <li><a href="#no_locking">Class <code>no_locking</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>mutex</i> is a type whose objects can be in either of two states, called
  67 locked and unlocked, with the property that when a thread A has locked a
  68 mutex <code>m</code> and a different thread B tries to lock <code>m</code>,
  69 B is blocked until A unlocks <code>m</code>. Additionally, a mutex is said to
  70 support <i>recursive locking</i> if a thread can succesfully invoke the locking
  71 operation for a mutex already locked by this same thread; in this case, it is
  72 required that the thread execute as many unlock operations as lock
  73 operations it has performed for the mutex to become effectively unlocked.
  74 A <i>scoped lock</i> is a
  75 type associated to some mutex type whose objects do the locking/unlocking
  76 of a mutex on construction/destruction time.
  77 </p>
  78
  79 <p>
  80 In the following table, <code>Mutex</code> is a mutex type, <code>m</code>
  81 is an object of type <code>Mutex</code>, <code>Lock</code> is a scoped lock
  82 associated to <code>Mutex</code> and <code>lk</code> is a value of
  83 <code>Lock</code>.
  84
  85 <p align="center">
  86 <table cellspacing="0">
  87   <caption><b>Mutex and Scoped Lock requirements.</b></caption>
  88 <tr>
  89   <th align="center">expression</th>
  90   <th align="center">return type</th>
  91   <th align="center">assertion/note<br>pre/post-condition</th>
  92 </tr>
  93 <tr>
  94   <td><code>Mutex m;</code></td>
  95   <td>&nbsp;</td>
  96   <td>Post: <code>m</code> is unlocked.
  97   </td>
  98 </tr>
  99 <tr class="odd_tr">
 100   <td><code>(&amp;m)->~Mutex();</code></td>
 101   <td><code>void</code></td>
 102   <td>Pre: <code>m</code> is unlocked.</td>
 103 </tr>
 104 <tr>
 105   <td><code>Lock lk(m);</code></td>
 106   <td>&nbsp;</td>
 107   <td>Associates <code>m</code> to <code>lk</code> and locks <code>m</code>.</td>
 108 </tr>
 109 <tr class="odd_tr">
 110   <td><code>(&amp;lk)->~Lock();</code></td>
 111   <td><code>void</code></td>
 112   <td>Unlocks the mutex associated to <code>lk</code>.</td>
 113 </tr>
 114 </table>
 115 </p>
 116
 117 <p>
 118 These concepts are very similar, but not entirely equivalent, to
 119 the homonym ones described in the
 120 <a href="../../../../doc/html/thread/synchronization.html#thread.synchronization.mutex_concepts">Boost Thread
 121 Library</a>.
 122 </p>
 123
 124 <h2><a name="locking">Locking policies</a></h2>
 125
 126 <p>
 127 <i>Locking policies</i> describe a mutex type and an associated
 128 scoped lock type.
 129 <a href="flyweight.html#flyweight"><code>flyweight</code></a> uses a given locking
 130 policy to synchronize the access to its internal
 131 <a href="factories.html#factory">factory</a>.
 132 </p>
 133
 134 <p>
 135 A type <code>Locking</code> is a locking policy if:
 136 <ul>
 137   <li>One of the following conditions is satisfied:
 138     <ol type="a">
 139       <li><a href="#is_locking"><code>is_locking&lt;Locking&gt;::type</code></a> is
 140       <a href="../../../mpl/doc/refmanual/bool.html"><code>boost::mpl::true_</code></a>,</li>
 141       <li><code>Locking</code> is of the form
 142       <a href="#locking_construct"><code>locking&lt;Locking'&gt;</code></a>.</li>
 143     </ol>
 144   </li>
 145   <li>The type <code>Locking::mutex_type</code> (or
 146     <code>Locking'::mutex_type</code> if (b) applies) is a
 147     model of <a href="#preliminary"><code>Mutex</code></a>
 148     and supports recursive locking.
 149   </li>
 150   <li>The type <code>Locking::lock_type</code> (or
 151     <code>Locking'::lock_type</code> if (b) applies) is a
 152     <a href="#preliminary"><code>Scoped Lock</code></a> of
 153     the mutex referred to above.
 154   </li>
 155 </ul>
 156 </p>
 157
 158 <h2><a name="locking_tag_synopsis">Header
 159 <a href="../../../../boost/flyweight/locking_tag.hpp"><code>"boost/flyweight/locking_tag.hpp"</code></a> synopsis</a></h2>
 160
 161 <blockquote><pre>
 162 <span class=keyword>namespace</span> <span class=identifier>boost</span><span class=special>{</span>
 163
 164 <span class=keyword>namespace</span> <span class=identifier>flyweights</span><span class=special>{</span>
 165
 166 <span class=keyword>struct</span> <span class=identifier>locking_marker</span><span class=special>;</span>
 167
 168 <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>
 169 <span class=keyword>struct</span> <span class=identifier>is_locking</span>
 170
 171 <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>
 172 <span class=keyword>struct</span> <span class=identifier>locking</span><span class=special>;</span>
 173
 174 <span class=special>}</span> <span class=comment>// namespace boost::flyweights</span>
 175
 176 <span class=special>}</span> <span class=comment>// namespace boost</span>
 177 </pre></blockquote>
 178
 179 <h3><a name="is_locking">Class template <code>is_locking</code></a></h3>
 180
 181 <p>
 182 Unless specialized by the user, <code>is_locking&lt;T&gt;::type</code> is
 183 <a href="../../../mpl/doc/refmanual/bool.html"><code>boost::mpl::true_</code></a>
 184 if <code>T</code> is derived from <code>locking_marker</code>, and it is
 185 <a href="../../../mpl/doc/refmanual/bool.html"><code>boost::mpl::false_</code></a>
 186 otherwise.
 187 </p>
 188
 189 <h3><a name="locking_construct">Class template <code>locking</code></a></h3>
 190
 191 <p>
 192 <code>locking&lt;T&gt;</code> is a syntactic construct meant to indicate
 193 that <code>T</code> is a locking policy without resorting to the
 194 mechanisms provided by the <code>is_locking</code> class template.
 195 </p>
 196
 197 <h2><a name="simple_locking_fwd_synopsis">Header
 198 <a href="../../../../boost/flyweight/simple_locking_fwd.hpp"><code>"boost/flyweight/simple_locking_fwd.hpp"</code></a> synopsis</a></h2>
 199
 200 <blockquote><pre>
 201 <span class=keyword>namespace</span> <span class=identifier>boost</span><span class=special>{</span>
 202
 203 <span class=keyword>namespace</span> <span class=identifier>flyweights</span><span class=special>{</span>
 204
 205 <span class=keyword>struct</span> <span class=identifier>simple_locking</span><span class=special>;</span>
 206
 207 <span class=special>}</span> <span class=comment>// namespace boost::flyweights</span>
 208
 209 <span class=special>}</span> <span class=comment>// namespace boost</span>
 210 </pre></blockquote>
 211
 212 <p>
 213 <code>simple_locking_fwd.hpp</code> forward declares the class
 214 <a href="#simple_locking"><code>simple_locking</code></a>.
 215 </p>
 216
 217 <h2><a name="simple_locking_synopsis">Header
 218 <a href="../../../../boost/flyweight/simple_locking.hpp"><code>"boost/flyweight/simple_locking.hpp"</code></a> synopsis</a></h2>
 219
 220 <h3><a name="simple_locking">Class <code>simple_locking</code></a></h3>
 221
 222 <p>
 223 <a href="#locking"><code>Locking Policy</code></a> that specifies a basic
 224 mutex type based on the simplest synchronization mechanisms provided by
 225 the environment; When no threading capabilities are available,
 226 <code>simple_locking</code> specifies a dummy type without actual
 227 synchronization capabilities.
 228 </p>
 229
 230 <h2><a name="no_locking_fwd_synopsis">Header
 231 <a href="../../../../boost/flyweight/no_locking_fwd.hpp"><code>"boost/flyweight/no_locking_fwd.hpp"</code></a> synopsis</a></h2>
 232
 233 <blockquote><pre>
 234 <span class=keyword>namespace</span> <span class=identifier>boost</span><span class=special>{</span>
 235
 236 <span class=keyword>namespace</span> <span class=identifier>flyweights</span><span class=special>{</span>
 237
 238 <span class=keyword>struct</span> <span class=identifier>no_locking</span><span class=special>;</span>
 239
 240 <span class=special>}</span> <span class=comment>// namespace boost::flyweights</span>
 241
 242 <span class=special>}</span> <span class=comment>// namespace boost</span>
 243 </pre></blockquote>
 244
 245 <p>
 246 <code>no_locking_fwd.hpp</code> forward declares the class
 247 <a href="#no_locking"><code>no_locking</code></a>.
 248 </p>
 249
 250 <h2><a name="no_locking_synopsis">Header
 251 <a href="../../../../boost/flyweight/no_locking.hpp"><code>"boost/flyweight/no_locking.hpp"</code></a> synopsis</a></h2>
 252
 253 <h3><a name="no_locking">Class <code>no_locking</code></a></h3>
 254
 255 <p>
 256 Null <a href="#locking"><code>Locking Policy</code></a>: it specifies a dummy
 257 type that satisfies the formal requirements for the
 258 <a href="#preliminary"><code>Mutex</code></a> concept but does not perform
 259 thread blocking. <code>no_locking</code> should only be used in single-threaded
 260 environments.
 261 </p>
 262
 263 <hr>
 264
 265 <div class="prev_link"><a href="holders.html"><img src="../prev.gif" alt="holders" border="0"><br>
 266 Holders
 267 </a></div>
 268 <div class="up_link"><a href="index.html"><img src="../up.gif" alt="Boost.Flyweight reference" border="0"><br>
 269 Boost.Flyweight reference
 270 </a></div>
 271 <div class="next_link"><a href="tracking.html"><img src="../next.gif" alt="tracking policies" border="0"><br>
 272 Tracking policies
 273 </a></div><br clear="all" style="clear: all;">
 274
 275 <br>
 276
 277 <p>Revised March 9th 2010</p>
 278
 279 <p>&copy; Copyright 2006-2010 Joaqu&iacute;n M L&oacute;pez Mu&ntilde;oz.
 280 Distributed under the Boost Software
 281 License, Version 1.0. (See accompanying file <a href="../../../../LICENSE_1_0.txt">
 282 LICENSE_1_0.txt</a> or copy at <a href="http://www.boost.org/LICENSE_1_0.txt">
 283 http://www.boost.org/LICENSE_1_0.txt</a>)
 284 </p>
 285
 286 </body>
 287 </html>