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 17Locking policies reference</h1> 18 19<div class="prev_link"><a href="holders.html"><img src="../prev.gif" alt="holders" border="0"><br> 20Holders 21</a></div> 22<div class="up_link"><a href="index.html"><img src="../up.gif" alt="Boost.Flyweight reference" border="0"><br> 23Boost.Flyweight reference 24</a></div> 25<div class="next_link"><a href="tracking.html"><img src="../next.gif" alt="tracking policies" border="0"><br> 26Tracking 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> 66A <i>mutex</i> is a type whose objects can be in either of two states, called 67locked and unlocked, with the property that when a thread A has locked a 68mutex <code>m</code> and a different thread B tries to lock <code>m</code>, 69B is blocked until A unlocks <code>m</code>. Additionally, a mutex is said to 70support <i>recursive locking</i> if a thread can succesfully invoke the locking 71operation for a mutex already locked by this same thread; in this case, it is 72required that the thread execute as many unlock operations as lock 73operations it has performed for the mutex to become effectively unlocked. 74A <i>scoped lock</i> is a 75type associated to some mutex type whose objects do the locking/unlocking 76of a mutex on construction/destruction time. 77</p> 78 79<p> 80In the following table, <code>Mutex</code> is a mutex type, <code>m</code> 81is an object of type <code>Mutex</code>, <code>Lock</code> is a scoped lock 82associated 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> 118These concepts are very similar, but not entirely equivalent, to 119the homonym ones described in the 120<a href="../../../../doc/html/thread/synchronization.html#thread.synchronization.mutex_concepts">Boost Thread 121Library</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 128scoped lock type. 129<a href="flyweight.html#flyweight"><code>flyweight</code></a> uses a given locking 130policy to synchronize the access to its internal 131<a href="factories.html#factory">factory</a>. 132</p> 133 134<p> 135A 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> 182Unless 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> 184if <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> 186otherwise. 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 193that <code>T</code> is a locking policy without resorting to the 194mechanisms 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 224mutex type based on the simplest synchronization mechanisms provided by 225the environment; When no threading capabilities are available, 226<code>simple_locking</code> specifies a dummy type without actual 227synchronization 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> 256Null <a href="#locking"><code>Locking Policy</code></a>: it specifies a dummy 257type that satisfies the formal requirements for the 258<a href="#preliminary"><code>Mutex</code></a> concept but does not perform 259thread blocking. <code>no_locking</code> should only be used in single-threaded 260environments. 261</p> 262 263<hr> 264 265<div class="prev_link"><a href="holders.html"><img src="../prev.gif" alt="holders" border="0"><br> 266Holders 267</a></div> 268<div class="up_link"><a href="index.html"><img src="../up.gif" alt="Boost.Flyweight reference" border="0"><br> 269Boost.Flyweight reference 270</a></div> 271<div class="next_link"><a href="tracking.html"><img src="../next.gif" alt="tracking policies" border="0"><br> 272Tracking 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. 280Distributed under the Boost Software 281License, Version 1.0. (See accompanying file <a href="../../../../LICENSE_1_0.txt"> 282LICENSE_1_0.txt</a> or copy at <a href="http://www.boost.org/LICENSE_1_0.txt"> 283http://www.boost.org/LICENSE_1_0.txt</a>) 284</p> 285 286</body> 287</html> 288
