projects / ceph.git / blame
| Commit | Line | Data |
|---|---|---|
| 7c673cae FG |
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> </td> | |
| 96 | <td>Post: <code>m</code> is unlocked. | |
| 97 | </td> | |
| 98 | </tr> | |
| 99 | <tr class="odd_tr"> | |
| 100 | <td><code>(&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> </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>(&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<Locking>::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<Locking'></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><</span><span class=keyword>typename</span> <span class=identifier>T</span><span class=special>></span> | |
| 169 | <span class=keyword>struct</span> <span class=identifier>is_locking</span> | |
| 170 | ||
| 171 | <span class=keyword>template</span><span class=special><</span><span class=keyword>typename</span> <span class=identifier>T</span><span class=special>></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<T>::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<T></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>© Copyright 2006-2010 Joaquín M López Muñ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> |