1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> 2<html> 3<head> 4<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 5<title>Synchronization mechanisms</title> 6<link rel="stylesheet" href="../../../doc/src/boostbook.css" type="text/css"> 7<meta name="generator" content="DocBook XSL Stylesheets V1.79.1"> 8<link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset"> 9<link rel="up" href="../interprocess.html" title="Chapter 18. Boost.Interprocess"> 10<link rel="prev" href="offset_ptr.html" title="Mapping Address Independent Pointer: offset_ptr"> 11<link rel="next" href="managed_memory_segments.html" title="Managed Memory Segments"> 12</head> 13<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> 14<table cellpadding="2" width="100%"><tr> 15<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td> 16<td align="center"><a href="../../../index.html">Home</a></td> 17<td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td> 18<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> 19<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> 20<td align="center"><a href="../../../more/index.htm">More</a></td> 21</tr></table> 22<hr> 23<div class="spirit-nav"> 24<a accesskey="p" href="offset_ptr.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../interprocess.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="managed_memory_segments.html"><img src="../../../doc/src/images/next.png" alt="Next"></a> 25</div> 26<div class="section"> 27<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 28<a name="interprocess.synchronization_mechanisms"></a><a class="link" href="synchronization_mechanisms.html" title="Synchronization mechanisms">Synchronization 29 mechanisms</a> 30</h2></div></div></div> 31<div class="toc"><dl class="toc"> 32<dt><span class="section"><a href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.synchronization_mechanisms_overview">Synchronization 33 mechanisms overview</a></span></dt> 34<dt><span class="section"><a href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.mutexes">Mutexes</a></span></dt> 35<dt><span class="section"><a href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.conditions">Conditions</a></span></dt> 36<dt><span class="section"><a href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.semaphores">Semaphores</a></span></dt> 37<dt><span class="section"><a href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.sharable_upgradable_mutexes">Sharable 38 and Upgradable Mutexes</a></span></dt> 39<dt><span class="section"><a href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.lock_conversions">Lock 40 Transfers Through Move Semantics</a></span></dt> 41<dt><span class="section"><a href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.file_lock">File 42 Locks</a></span></dt> 43<dt><span class="section"><a href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.message_queue">Message 44 Queue</a></span></dt> 45</dl></div> 46<div class="section"> 47<div class="titlepage"><div><div><h3 class="title"> 48<a name="interprocess.synchronization_mechanisms.synchronization_mechanisms_overview"></a><a class="link" href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.synchronization_mechanisms_overview" title="Synchronization mechanisms overview">Synchronization 49 mechanisms overview</a> 50</h3></div></div></div> 51<div class="toc"><dl class="toc"> 52<dt><span class="section"><a href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.synchronization_mechanisms_overview.synchronization_mechanisms_named_vs_anonymous">Named 53 And Anonymous Synchronization Mechanisms</a></span></dt> 54<dt><span class="section"><a href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.synchronization_mechanisms_overview.synchronization_mechanisms_types">Types 55 Of Synchronization Mechanisms</a></span></dt> 56</dl></div> 57<p> 58 As mentioned before, the ability to shared memory between processes through 59 memory mapped files or shared memory objects is not very useful if the access 60 to that memory can't be effectively synchronized. This is the same problem 61 that happens with thread-synchronization mechanisms, where heap memory and 62 global variables are shared between threads, but the access to these resources 63 needs to be synchronized typically through mutex and condition variables. 64 <span class="bold"><strong>Boost.Threads</strong></span> implements these synchronization 65 utilities between threads inside the same process. <span class="bold"><strong>Boost.Interprocess</strong></span> 66 implements similar mechanisms to synchronize threads from different processes. 67 </p> 68<div class="section"> 69<div class="titlepage"><div><div><h4 class="title"> 70<a name="interprocess.synchronization_mechanisms.synchronization_mechanisms_overview.synchronization_mechanisms_named_vs_anonymous"></a><a class="link" href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.synchronization_mechanisms_overview.synchronization_mechanisms_named_vs_anonymous" title="Named And Anonymous Synchronization Mechanisms">Named 71 And Anonymous Synchronization Mechanisms</a> 72</h4></div></div></div> 73<p> 74 <span class="bold"><strong>Boost.Interprocess</strong></span> presents two types 75 of synchronization objects: 76 </p> 77<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 78<li class="listitem"> 79 <span class="bold"><strong>Named utilities</strong></span>: When two processes 80 want to create an object of such type, both processes must <span class="emphasis"><em>create</em></span> 81 or <span class="emphasis"><em>open</em></span> an object using the same name. This is 82 similar to creating or opening files: a process creates a file with 83 using a <code class="computeroutput"><span class="identifier">fstream</span></code> with 84 the name <span class="emphasis"><em>filename</em></span> and another process opens that 85 file using another <code class="computeroutput"><span class="identifier">fstream</span></code> 86 with the same <span class="emphasis"><em>filename</em></span> argument. <span class="bold"><strong>Each 87 process uses a different object to access to the resource, but both 88 processes are using the same underlying resource</strong></span>. 89 </li> 90<li class="listitem"> 91 <span class="bold"><strong>Anonymous utilities</strong></span>: Since these utilities 92 have no name, two processes must share <span class="bold"><strong>the same 93 object</strong></span> through shared memory or memory mapped files. This 94 is similar to traditional thread synchronization objects: <span class="bold"><strong>Both processes share the same object</strong></span>. Unlike 95 thread synchronization, where global variables and heap memory is shared 96 between threads of the same process, sharing objects between two threads 97 from different process can be only possible through mapped regions 98 that map the same mappable resource (for example, shared memory or 99 memory mapped files). 100 </li> 101</ul></div> 102<p> 103 Each type has it's own advantages and disadvantages: 104 </p> 105<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 106<li class="listitem"> 107 Named utilities are easier to handle for simple synchronization tasks, 108 since both process don't have to create a shared memory region and 109 construct the synchronization mechanism there. 110 </li> 111<li class="listitem"> 112 Anonymous utilities can be serialized to disk when using memory mapped 113 objects obtaining automatic persistence of synchronization utilities. 114 One could construct a synchronization utility in a memory mapped file, 115 reboot the system, map the file again, and use the synchronization 116 utility again without any problem. This can't be achieved with named 117 synchronization utilities. 118 </li> 119</ul></div> 120<p> 121 The main interface difference between named and anonymous utilities are 122 the constructors. Usually anonymous utilities have only one constructor, 123 whereas the named utilities have several constructors whose first argument 124 is a special type that requests creation, opening or opening or creation 125 of the underlying resource: 126 </p> 127<pre class="programlisting"><span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">;</span> 128 129<span class="comment">//Create the synchronization utility. If it previously</span> 130<span class="comment">//exists, throws an error</span> 131<span class="identifier">NamedUtility</span><span class="special">(</span><span class="identifier">create_only</span><span class="special">,</span> <span class="special">...)</span> 132 133<span class="comment">//Open the synchronization utility. If it does not previously</span> 134<span class="comment">//exist, it's created.</span> 135<span class="identifier">NamedUtility</span><span class="special">(</span><span class="identifier">open_or_create</span><span class="special">,</span> <span class="special">...)</span> 136 137<span class="comment">//Open the synchronization utility. If it does not previously</span> 138<span class="comment">//exist, throws an error.</span> 139<span class="identifier">NamedUtility</span><span class="special">(</span><span class="identifier">open_only</span><span class="special">,</span> <span class="special">...)</span> 140</pre> 141<p> 142 On the other hand the anonymous synchronization utility can only be created 143 and the processes must synchronize using other mechanisms who creates the 144 utility: 145 </p> 146<pre class="programlisting"><span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">;</span> 147 148<span class="comment">//Create the synchronization utility.</span> 149<span class="identifier">AnonymousUtility</span><span class="special">(...)</span> 150</pre> 151</div> 152<div class="section"> 153<div class="titlepage"><div><div><h4 class="title"> 154<a name="interprocess.synchronization_mechanisms.synchronization_mechanisms_overview.synchronization_mechanisms_types"></a><a class="link" href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.synchronization_mechanisms_overview.synchronization_mechanisms_types" title="Types Of Synchronization Mechanisms">Types 155 Of Synchronization Mechanisms</a> 156</h4></div></div></div> 157<p> 158 Apart from its named/anonymous nature, <span class="bold"><strong>Boost.Interprocess</strong></span> 159 presents the following synchronization utilities: 160 </p> 161<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 162<li class="listitem"> 163 Mutexes (named and anonymous) 164 </li> 165<li class="listitem"> 166 Condition variables (named and anonymous) 167 </li> 168<li class="listitem"> 169 Semaphores (named and anonymous) 170 </li> 171<li class="listitem"> 172 Upgradable mutexes 173 </li> 174<li class="listitem"> 175 File locks 176 </li> 177</ul></div> 178</div> 179</div> 180<div class="section"> 181<div class="titlepage"><div><div><h3 class="title"> 182<a name="interprocess.synchronization_mechanisms.mutexes"></a><a class="link" href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.mutexes" title="Mutexes">Mutexes</a> 183</h3></div></div></div> 184<div class="toc"><dl class="toc"> 185<dt><span class="section"><a href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.mutexes.mutexes_whats_a_mutex">What's 186 A Mutex?</a></span></dt> 187<dt><span class="section"><a href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.mutexes.mutexes_mutex_operations">Mutex 188 Operations</a></span></dt> 189<dt><span class="section"><a href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.mutexes.mutexes_interprocess_mutexes">Boost.Interprocess 190 Mutex Types And Headers</a></span></dt> 191<dt><span class="section"><a href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.mutexes.mutexes_scoped_lock">Scoped 192 lock</a></span></dt> 193<dt><span class="section"><a href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.mutexes.mutexes_anonymous_example">Anonymous 194 mutex example</a></span></dt> 195<dt><span class="section"><a href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.mutexes.mutexes_named_example">Named 196 mutex example</a></span></dt> 197</dl></div> 198<div class="section"> 199<div class="titlepage"><div><div><h4 class="title"> 200<a name="interprocess.synchronization_mechanisms.mutexes.mutexes_whats_a_mutex"></a><a class="link" href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.mutexes.mutexes_whats_a_mutex" title="What's A Mutex?">What's 201 A Mutex?</a> 202</h4></div></div></div> 203<p> 204 <span class="emphasis"><em>Mutex</em></span> stands for <span class="bold"><strong>mut</strong></span>ual 205 <span class="bold"><strong>ex</strong></span>clusion and it's the most basic form 206 of synchronization between processes. Mutexes guarantee that only one thread 207 can lock a given mutex. If a code section is surrounded by a mutex locking 208 and unlocking, it's guaranteed that only a thread at a time executes that 209 section of code. When that thread <span class="bold"><strong>unlocks</strong></span> 210 the mutex, other threads can enter to that code region: 211 </p> 212<pre class="programlisting"><span class="comment">//The mutex has been previously constructed</span> 213 214<span class="identifier">lock_the_mutex</span><span class="special">();</span> 215 216<span class="comment">//This code will be executed only by one thread</span> 217<span class="comment">//at a time.</span> 218 219<span class="identifier">unlock_the_mutex</span><span class="special">();</span> 220</pre> 221<p> 222 A mutex can also be <span class="bold"><strong>recursive</strong></span> or <span class="bold"><strong>non-recursive</strong></span>: 223 </p> 224<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 225<li class="listitem"> 226 Recursive mutexes can be locked several times by the same thread. To 227 fully unlock the mutex, the thread has to unlock the mutex the same 228 times it has locked it. 229 </li> 230<li class="listitem"> 231 Non-recursive mutexes can't be locked several times by the same thread. 232 If a mutex is locked twice by a thread, the result is undefined, it 233 might throw an error or the thread could be blocked forever. 234 </li> 235</ul></div> 236</div> 237<div class="section"> 238<div class="titlepage"><div><div><h4 class="title"> 239<a name="interprocess.synchronization_mechanisms.mutexes.mutexes_mutex_operations"></a><a class="link" href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.mutexes.mutexes_mutex_operations" title="Mutex Operations">Mutex 240 Operations</a> 241</h4></div></div></div> 242<p> 243 All the mutex types from <span class="bold"><strong>Boost.Interprocess</strong></span> 244 implement the following operations: 245 </p> 246<div class="blurb"> 247<div class="titlepage"><div><div><p class="title"><b></b></p></div></div></div> 248<p> 249 <span class="emphasis"><em><span class="bold"><strong>void lock()</strong></span></em></span> 250 </p> 251</div> 252<p> 253 <span class="bold"><strong>Effects:</strong></span> The calling thread tries to obtain 254 ownership of the mutex, and if another thread has ownership of the mutex, 255 it waits until it can obtain the ownership. If a thread takes ownership 256 of the mutex the mutex must be unlocked by the same thread. If the mutex 257 supports recursive locking, the mutex must be unlocked the same number 258 of times it is locked. 259 </p> 260<p> 261 <span class="bold"><strong>Throws:</strong></span> <span class="bold"><strong>interprocess_exception</strong></span> 262 on error. 263 </p> 264<div class="blurb"> 265<div class="titlepage"><div><div><p class="title"><b></b></p></div></div></div> 266<p> 267 <span class="emphasis"><em><span class="bold"><strong>bool try_lock()</strong></span></em></span> 268 </p> 269</div> 270<p> 271 <span class="bold"><strong>Effects:</strong></span> The calling thread tries to obtain 272 ownership of the mutex, and if another thread has ownership of the mutex 273 returns immediately. If the mutex supports recursive locking, the mutex 274 must be unlocked the same number of times it is locked. 275 </p> 276<p> 277 <span class="bold"><strong>Returns:</strong></span> If the thread acquires ownership 278 of the mutex, returns true, if the another thread has ownership of the 279 mutex, returns false. 280 </p> 281<p> 282 <span class="bold"><strong>Throws:</strong></span> <span class="bold"><strong>interprocess_exception</strong></span> 283 on error. 284 </p> 285<div class="blurb"> 286<div class="titlepage"><div><div><p class="title"><b></b></p></div></div></div> 287<p> 288 <span class="emphasis"><em><span class="bold"><strong>bool timed_lock(const boost::posix_time::ptime 289 &abs_time)</strong></span></em></span> 290 </p> 291</div> 292<p> 293 <span class="bold"><strong>Effects:</strong></span> The calling thread will try to 294 obtain exclusive ownership of the mutex if it can do so in until the specified 295 time is reached. If the mutex supports recursive locking, the mutex must 296 be unlocked the same number of times it is locked. 297 </p> 298<p> 299 <span class="bold"><strong>Returns:</strong></span> If the thread acquires ownership 300 of the mutex, returns true, if the timeout expires returns false. 301 </p> 302<p> 303 <span class="bold"><strong>Throws:</strong></span> <span class="bold"><strong>interprocess_exception</strong></span> 304 on error. 305 </p> 306<div class="blurb"> 307<div class="titlepage"><div><div><p class="title"><b></b></p></div></div></div> 308<p> 309 <span class="emphasis"><em><span class="bold"><strong>void unlock()</strong></span></em></span> 310 </p> 311</div> 312<p> 313 <span class="bold"><strong>Precondition:</strong></span> The thread must have exclusive 314 ownership of the mutex. 315 </p> 316<p> 317 <span class="bold"><strong>Effects:</strong></span> The calling thread releases the 318 exclusive ownership of the mutex. If the mutex supports recursive locking, 319 the mutex must be unlocked the same number of times it is locked. 320 </p> 321<p> 322 <span class="bold"><strong>Throws:</strong></span> An exception derived from <span class="bold"><strong>interprocess_exception</strong></span> on error. 323 </p> 324<div class="important"><table border="0" summary="Important"> 325<tr> 326<td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="../../../doc/src/images/important.png"></td> 327<th align="left">Important</th> 328</tr> 329<tr><td align="left" valign="top"><p> 330 <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">posix_time</span><span class="special">::</span><span class="identifier">ptime</span></code> absolute time points used by 331 Boost.Interprocess synchronization mechanisms are UTC time points, not 332 local time points 333 </p></td></tr> 334</table></div> 335</div> 336<div class="section"> 337<div class="titlepage"><div><div><h4 class="title"> 338<a name="interprocess.synchronization_mechanisms.mutexes.mutexes_interprocess_mutexes"></a><a class="link" href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.mutexes.mutexes_interprocess_mutexes" title="Boost.Interprocess Mutex Types And Headers">Boost.Interprocess 339 Mutex Types And Headers</a> 340</h4></div></div></div> 341<p> 342 Boost.Interprocess offers the following mutex types: 343 </p> 344<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">interprocess</span><span class="special">/</span><span class="identifier">sync</span><span class="special">/</span><span class="identifier">interprocess_mutex</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 345</pre> 346<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> 347 <code class="computeroutput"><a class="link" href="../boost/interprocess/interprocess_mutex.html" title="Class interprocess_mutex">interprocess_mutex</a></code>: 348 A non-recursive, anonymous mutex that can be placed in shared memory 349 or memory mapped files. 350 </li></ul></div> 351<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">interprocess</span><span class="special">/</span><span class="identifier">sync</span><span class="special">/</span><span class="identifier">interprocess_recursive_mutex</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 352</pre> 353<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> 354 <code class="computeroutput"><a class="link" href="../boost/interprocess/interpro_idm45304010361200.html" title="Class interprocess_recursive_mutex">interprocess_recursive_mutex</a></code>: 355 A recursive, anonymous mutex that can be placed in shared memory or 356 memory mapped files. 357 </li></ul></div> 358<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">interprocess</span><span class="special">/</span><span class="identifier">sync</span><span class="special">/</span><span class="identifier">named_mutex</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 359</pre> 360<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> 361 <code class="computeroutput"><a class="link" href="../boost/interprocess/named_mutex.html" title="Class named_mutex">named_mutex</a></code>: 362 A non-recursive, named mutex. 363 </li></ul></div> 364<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">interprocess</span><span class="special">/</span><span class="identifier">sync</span><span class="special">/</span><span class="identifier">named_recursive_mutex</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 365</pre> 366<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> 367 <code class="computeroutput"><a class="link" href="../boost/interprocess/named_recursive_mutex.html" title="Class named_recursive_mutex">named_recursive_mutex</a></code>: 368 A recursive, named mutex. 369 </li></ul></div> 370</div> 371<div class="section"> 372<div class="titlepage"><div><div><h4 class="title"> 373<a name="interprocess.synchronization_mechanisms.mutexes.mutexes_scoped_lock"></a><a class="link" href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.mutexes.mutexes_scoped_lock" title="Scoped lock">Scoped 374 lock</a> 375</h4></div></div></div> 376<p> 377 It's very important to unlock a mutex after the process has read or written 378 the data. This can be difficult when dealing with exceptions, so usually 379 mutexes are used with a scoped lock, a class that can guarantee that a 380 mutex will always be unlocked even when an exception occurs. To use a scoped 381 lock just include: 382 </p> 383<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">interprocess</span><span class="special">/</span><span class="identifier">sync</span><span class="special">/</span><span class="identifier">scoped_lock</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 384</pre> 385<p> 386 Basically, a scoped lock calls <span class="bold"><strong>unlock()</strong></span> 387 in its destructor, and a mutex is always unlocked when an exception occurs. 388 Scoped lock has many constructors to lock, try_lock, timed_lock a mutex 389 or not to lock it at all. 390 </p> 391<pre class="programlisting"><span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">;</span> 392 393<span class="comment">//Let's create any mutex type:</span> 394<span class="identifier">MutexType</span> <span class="identifier">mutex</span><span class="special">;</span> 395 396<span class="special">{</span> 397 <span class="comment">//This will lock the mutex</span> 398 <span class="identifier">scoped_lock</span><span class="special"><</span><span class="identifier">MutexType</span><span class="special">></span> <span class="identifier">lock</span><span class="special">(</span><span class="identifier">mutex</span><span class="special">);</span> 399 400 <span class="comment">//Some code</span> 401 402 <span class="comment">//The mutex will be unlocked here</span> 403<span class="special">}</span> 404 405<span class="special">{</span> 406 <span class="comment">//This will try_lock the mutex</span> 407 <span class="identifier">scoped_lock</span><span class="special"><</span><span class="identifier">MutexType</span><span class="special">></span> <span class="identifier">lock</span><span class="special">(</span><span class="identifier">mutex</span><span class="special">,</span> <span class="identifier">try_to_lock</span><span class="special">);</span> 408 409 <span class="comment">//Check if the mutex has been successfully locked</span> 410 <span class="keyword">if</span><span class="special">(</span><span class="identifier">lock</span><span class="special">){</span> 411 <span class="comment">//Some code</span> 412 <span class="special">}</span> 413 414 <span class="comment">//If the mutex was locked it will be unlocked</span> 415<span class="special">}</span> 416 417<span class="special">{</span> 418 <span class="identifier">boost</span><span class="special">::</span><span class="identifier">posix_time</span><span class="special">::</span><span class="identifier">ptime</span> <span class="identifier">abs_time</span> <span class="special">=</span> <span class="special">...</span> 419 420 <span class="comment">//This will timed_lock the mutex</span> 421 <span class="identifier">scoped_lock</span><span class="special"><</span><span class="identifier">MutexType</span><span class="special">></span> <span class="identifier">lock</span><span class="special">(</span><span class="identifier">mutex</span><span class="special">,</span> <span class="identifier">abs_time</span><span class="special">);</span> 422 423 <span class="comment">//Check if the mutex has been successfully locked</span> 424 <span class="keyword">if</span><span class="special">(</span><span class="identifier">lock</span><span class="special">){</span> 425 <span class="comment">//Some code</span> 426 <span class="special">}</span> 427 428 <span class="comment">//If the mutex was locked it will be unlocked</span> 429<span class="special">}</span> 430</pre> 431<p> 432 For more information, check the <code class="computeroutput"><a class="link" href="../boost/interprocess/scoped_lock.html" title="Class template scoped_lock">scoped_lock's 433 reference</a></code>. 434 </p> 435<div class="important"><table border="0" summary="Important"> 436<tr> 437<td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="../../../doc/src/images/important.png"></td> 438<th align="left">Important</th> 439</tr> 440<tr><td align="left" valign="top"><p> 441 <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">posix_time</span><span class="special">::</span><span class="identifier">ptime</span></code> absolute time points used by 442 Boost.Interprocess synchronization mechanisms are UTC time points, not 443 local time points 444 </p></td></tr> 445</table></div> 446</div> 447<div class="section"> 448<div class="titlepage"><div><div><h4 class="title"> 449<a name="interprocess.synchronization_mechanisms.mutexes.mutexes_anonymous_example"></a><a class="link" href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.mutexes.mutexes_anonymous_example" title="Anonymous mutex example">Anonymous 450 mutex example</a> 451</h4></div></div></div> 452<p> 453 Imagine that two processes need to write traces to a cyclic buffer built 454 in shared memory. Each process needs to obtain exclusive access to the 455 cyclic buffer, write the trace and continue. 456 </p> 457<p> 458 To protect the cyclic buffer, we can store a process shared mutex in the 459 cyclic buffer. Each process will lock the mutex before writing the data 460 and will write a flag when ends writing the traces (<code class="computeroutput"><span class="identifier">doc_anonymous_mutex_shared_data</span><span class="special">.</span><span class="identifier">hpp</span></code> 461 header): 462 </p> 463<p> 464</p> 465<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">interprocess</span><span class="special">/</span><span class="identifier">sync</span><span class="special">/</span><span class="identifier">interprocess_mutex</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 466 467<span class="keyword">struct</span> <span class="identifier">shared_memory_log</span> 468<span class="special">{</span> 469 <span class="keyword">enum</span> <span class="special">{</span> <span class="identifier">NumItems</span> <span class="special">=</span> <span class="number">100</span> <span class="special">};</span> 470 <span class="keyword">enum</span> <span class="special">{</span> <span class="identifier">LineSize</span> <span class="special">=</span> <span class="number">100</span> <span class="special">};</span> 471 472 <span class="identifier">shared_memory_log</span><span class="special">()</span> 473 <span class="special">:</span> <span class="identifier">current_line</span><span class="special">(</span><span class="number">0</span><span class="special">)</span> 474 <span class="special">,</span> <span class="identifier">end_a</span><span class="special">(</span><span class="keyword">false</span><span class="special">)</span> 475 <span class="special">,</span> <span class="identifier">end_b</span><span class="special">(</span><span class="keyword">false</span><span class="special">)</span> 476 <span class="special">{}</span> 477 478 <span class="comment">//Mutex to protect access to the queue</span> 479 <span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">::</span><span class="identifier">interprocess_mutex</span> <span class="identifier">mutex</span><span class="special">;</span> 480 481 <span class="comment">//Items to fill</span> 482 <span class="keyword">char</span> <span class="identifier">items</span><span class="special">[</span><span class="identifier">NumItems</span><span class="special">][</span><span class="identifier">LineSize</span><span class="special">];</span> 483 <span class="keyword">int</span> <span class="identifier">current_line</span><span class="special">;</span> 484 <span class="keyword">bool</span> <span class="identifier">end_a</span><span class="special">;</span> 485 <span class="keyword">bool</span> <span class="identifier">end_b</span><span class="special">;</span> 486<span class="special">};</span> 487</pre> 488<p> 489 </p> 490<p> 491 This is the process main process. Creates the shared memory, constructs 492 the cyclic buffer and start writing traces: 493 </p> 494<p> 495</p> 496<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">interprocess</span><span class="special">/</span><span class="identifier">shared_memory_object</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 497<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">interprocess</span><span class="special">/</span><span class="identifier">mapped_region</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 498<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">interprocess</span><span class="special">/</span><span class="identifier">sync</span><span class="special">/</span><span class="identifier">scoped_lock</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 499<span class="preprocessor">#include</span> <span class="string">"doc_anonymous_mutex_shared_data.hpp"</span> 500<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">iostream</span><span class="special">></span> 501<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">cstdio</span><span class="special">></span> 502 503<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">;</span> 504 505<span class="keyword">int</span> <span class="identifier">main</span> <span class="special">()</span> 506<span class="special">{</span> 507 <span class="keyword">try</span><span class="special">{</span> 508 <span class="comment">//Remove shared memory on construction and destruction</span> 509 <span class="keyword">struct</span> <span class="identifier">shm_remove</span> 510 <span class="special">{</span> 511 <span class="identifier">shm_remove</span><span class="special">()</span> <span class="special">{</span> <span class="identifier">shared_memory_object</span><span class="special">::</span><span class="identifier">remove</span><span class="special">(</span><span class="string">"MySharedMemory"</span><span class="special">);</span> <span class="special">}</span> 512 <span class="special">~</span><span class="identifier">shm_remove</span><span class="special">(){</span> <span class="identifier">shared_memory_object</span><span class="special">::</span><span class="identifier">remove</span><span class="special">(</span><span class="string">"MySharedMemory"</span><span class="special">);</span> <span class="special">}</span> 513 <span class="special">}</span> <span class="identifier">remover</span><span class="special">;</span> 514 515 <span class="comment">//Create a shared memory object.</span> 516 <span class="identifier">shared_memory_object</span> <span class="identifier">shm</span> 517 <span class="special">(</span><span class="identifier">create_only</span> <span class="comment">//only create</span> 518 <span class="special">,</span><span class="string">"MySharedMemory"</span> <span class="comment">//name</span> 519 <span class="special">,</span><span class="identifier">read_write</span> <span class="comment">//read-write mode</span> 520 <span class="special">);</span> 521 522 <span class="comment">//Set size</span> 523 <span class="identifier">shm</span><span class="special">.</span><span class="identifier">truncate</span><span class="special">(</span><span class="keyword">sizeof</span><span class="special">(</span><span class="identifier">shared_memory_log</span><span class="special">));</span> 524 525 <span class="comment">//Map the whole shared memory in this process</span> 526 <span class="identifier">mapped_region</span> <span class="identifier">region</span> 527 <span class="special">(</span><span class="identifier">shm</span> <span class="comment">//What to map</span> 528 <span class="special">,</span><span class="identifier">read_write</span> <span class="comment">//Map it as read-write</span> 529 <span class="special">);</span> 530 531 <span class="comment">//Get the address of the mapped region</span> 532 <span class="keyword">void</span> <span class="special">*</span> <span class="identifier">addr</span> <span class="special">=</span> <span class="identifier">region</span><span class="special">.</span><span class="identifier">get_address</span><span class="special">();</span> 533 534 <span class="comment">//Construct the shared structure in memory</span> 535 <span class="identifier">shared_memory_log</span> <span class="special">*</span> <span class="identifier">data</span> <span class="special">=</span> <span class="keyword">new</span> <span class="special">(</span><span class="identifier">addr</span><span class="special">)</span> <span class="identifier">shared_memory_log</span><span class="special">;</span> 536 537 <span class="comment">//Write some logs</span> 538 <span class="keyword">for</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">i</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span> <span class="identifier">i</span> <span class="special"><</span> <span class="identifier">shared_memory_log</span><span class="special">::</span><span class="identifier">NumItems</span><span class="special">;</span> <span class="special">++</span><span class="identifier">i</span><span class="special">){</span> 539 <span class="comment">//Lock the mutex</span> 540 <span class="identifier">scoped_lock</span><span class="special"><</span><span class="identifier">interprocess_mutex</span><span class="special">></span> <span class="identifier">lock</span><span class="special">(</span><span class="identifier">data</span><span class="special">-></span><span class="identifier">mutex</span><span class="special">);</span> 541 <span class="identifier">std</span><span class="special">::</span><span class="identifier">sprintf</span><span class="special">(</span><span class="identifier">data</span><span class="special">-></span><span class="identifier">items</span><span class="special">[(</span><span class="identifier">data</span><span class="special">-></span><span class="identifier">current_line</span><span class="special">++)</span> <span class="special">%</span> <span class="identifier">shared_memory_log</span><span class="special">::</span><span class="identifier">NumItems</span><span class="special">]</span> 542 <span class="special">,</span><span class="string">"%s_%d"</span><span class="special">,</span> <span class="string">"process_a"</span><span class="special">,</span> <span class="identifier">i</span><span class="special">);</span> 543 <span class="keyword">if</span><span class="special">(</span><span class="identifier">i</span> <span class="special">==</span> <span class="special">(</span><span class="identifier">shared_memory_log</span><span class="special">::</span><span class="identifier">NumItems</span><span class="special">-</span><span class="number">1</span><span class="special">))</span> 544 <span class="identifier">data</span><span class="special">-></span><span class="identifier">end_a</span> <span class="special">=</span> <span class="keyword">true</span><span class="special">;</span> 545 <span class="comment">//Mutex is released here</span> 546 <span class="special">}</span> 547 548 <span class="comment">//Wait until the other process ends</span> 549 <span class="keyword">while</span><span class="special">(</span><span class="number">1</span><span class="special">){</span> 550 <span class="identifier">scoped_lock</span><span class="special"><</span><span class="identifier">interprocess_mutex</span><span class="special">></span> <span class="identifier">lock</span><span class="special">(</span><span class="identifier">data</span><span class="special">-></span><span class="identifier">mutex</span><span class="special">);</span> 551 <span class="keyword">if</span><span class="special">(</span><span class="identifier">data</span><span class="special">-></span><span class="identifier">end_b</span><span class="special">)</span> 552 <span class="keyword">break</span><span class="special">;</span> 553 <span class="special">}</span> 554 <span class="special">}</span> 555 <span class="keyword">catch</span><span class="special">(</span><span class="identifier">interprocess_exception</span> <span class="special">&</span><span class="identifier">ex</span><span class="special">){</span> 556 <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="identifier">ex</span><span class="special">.</span><span class="identifier">what</span><span class="special">()</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> 557 <span class="keyword">return</span> <span class="number">1</span><span class="special">;</span> 558 <span class="special">}</span> 559 <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span> 560<span class="special">}</span> 561</pre> 562<p> 563 </p> 564<p> 565 The second process opens the shared memory, obtains access to the cyclic 566 buffer and starts writing traces: 567 </p> 568<p> 569</p> 570<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">interprocess</span><span class="special">/</span><span class="identifier">shared_memory_object</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 571<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">interprocess</span><span class="special">/</span><span class="identifier">mapped_region</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 572<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">interprocess</span><span class="special">/</span><span class="identifier">sync</span><span class="special">/</span><span class="identifier">scoped_lock</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 573<span class="preprocessor">#include</span> <span class="string">"doc_anonymous_mutex_shared_data.hpp"</span> 574<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">iostream</span><span class="special">></span> 575<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">cstdio</span><span class="special">></span> 576 577<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">;</span> 578 579<span class="keyword">int</span> <span class="identifier">main</span> <span class="special">()</span> 580<span class="special">{</span> 581 <span class="comment">//Remove shared memory on destruction</span> 582 <span class="keyword">struct</span> <span class="identifier">shm_remove</span> 583 <span class="special">{</span> 584 <span class="special">~</span><span class="identifier">shm_remove</span><span class="special">(){</span> <span class="identifier">shared_memory_object</span><span class="special">::</span><span class="identifier">remove</span><span class="special">(</span><span class="string">"MySharedMemory"</span><span class="special">);</span> <span class="special">}</span> 585 <span class="special">}</span> <span class="identifier">remover</span><span class="special">;</span> 586 587 <span class="comment">//Open the shared memory object.</span> 588 <span class="identifier">shared_memory_object</span> <span class="identifier">shm</span> 589 <span class="special">(</span><span class="identifier">open_only</span> <span class="comment">//only create</span> 590 <span class="special">,</span><span class="string">"MySharedMemory"</span> <span class="comment">//name</span> 591 <span class="special">,</span><span class="identifier">read_write</span> <span class="comment">//read-write mode</span> 592 <span class="special">);</span> 593 594 <span class="comment">//Map the whole shared memory in this process</span> 595 <span class="identifier">mapped_region</span> <span class="identifier">region</span> 596 <span class="special">(</span><span class="identifier">shm</span> <span class="comment">//What to map</span> 597 <span class="special">,</span><span class="identifier">read_write</span> <span class="comment">//Map it as read-write</span> 598 <span class="special">);</span> 599 600 <span class="comment">//Get the address of the mapped region</span> 601 <span class="keyword">void</span> <span class="special">*</span> <span class="identifier">addr</span> <span class="special">=</span> <span class="identifier">region</span><span class="special">.</span><span class="identifier">get_address</span><span class="special">();</span> 602 603 <span class="comment">//Construct the shared structure in memory</span> 604 <span class="identifier">shared_memory_log</span> <span class="special">*</span> <span class="identifier">data</span> <span class="special">=</span> <span class="keyword">static_cast</span><span class="special"><</span><span class="identifier">shared_memory_log</span><span class="special">*>(</span><span class="identifier">addr</span><span class="special">);</span> 605 606 <span class="comment">//Write some logs</span> 607 <span class="keyword">for</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">i</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span> <span class="identifier">i</span> <span class="special"><</span> <span class="number">100</span><span class="special">;</span> <span class="special">++</span><span class="identifier">i</span><span class="special">){</span> 608 <span class="comment">//Lock the mutex</span> 609 <span class="identifier">scoped_lock</span><span class="special"><</span><span class="identifier">interprocess_mutex</span><span class="special">></span> <span class="identifier">lock</span><span class="special">(</span><span class="identifier">data</span><span class="special">-></span><span class="identifier">mutex</span><span class="special">);</span> 610 <span class="identifier">std</span><span class="special">::</span><span class="identifier">sprintf</span><span class="special">(</span><span class="identifier">data</span><span class="special">-></span><span class="identifier">items</span><span class="special">[(</span><span class="identifier">data</span><span class="special">-></span><span class="identifier">current_line</span><span class="special">++)</span> <span class="special">%</span> <span class="identifier">shared_memory_log</span><span class="special">::</span><span class="identifier">NumItems</span><span class="special">]</span> 611 <span class="special">,</span><span class="string">"%s_%d"</span><span class="special">,</span> <span class="string">"process_a"</span><span class="special">,</span> <span class="identifier">i</span><span class="special">);</span> 612 <span class="keyword">if</span><span class="special">(</span><span class="identifier">i</span> <span class="special">==</span> <span class="special">(</span><span class="identifier">shared_memory_log</span><span class="special">::</span><span class="identifier">NumItems</span><span class="special">-</span><span class="number">1</span><span class="special">))</span> 613 <span class="identifier">data</span><span class="special">-></span><span class="identifier">end_b</span> <span class="special">=</span> <span class="keyword">true</span><span class="special">;</span> 614 <span class="comment">//Mutex is released here</span> 615 <span class="special">}</span> 616 617 <span class="comment">//Wait until the other process ends</span> 618 <span class="keyword">while</span><span class="special">(</span><span class="number">1</span><span class="special">){</span> 619 <span class="identifier">scoped_lock</span><span class="special"><</span><span class="identifier">interprocess_mutex</span><span class="special">></span> <span class="identifier">lock</span><span class="special">(</span><span class="identifier">data</span><span class="special">-></span><span class="identifier">mutex</span><span class="special">);</span> 620 <span class="keyword">if</span><span class="special">(</span><span class="identifier">data</span><span class="special">-></span><span class="identifier">end_a</span><span class="special">)</span> 621 <span class="keyword">break</span><span class="special">;</span> 622 <span class="special">}</span> 623 <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span> 624<span class="special">}</span> 625</pre> 626<p> 627 </p> 628<p> 629 As we can see, a mutex is useful to protect data but not to notify an event 630 to another process. For this, we need a condition variable, as we will 631 see in the next section. 632 </p> 633</div> 634<div class="section"> 635<div class="titlepage"><div><div><h4 class="title"> 636<a name="interprocess.synchronization_mechanisms.mutexes.mutexes_named_example"></a><a class="link" href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.mutexes.mutexes_named_example" title="Named mutex example">Named 637 mutex example</a> 638</h4></div></div></div> 639<p> 640 Now imagine that two processes want to write a trace to a file. First they 641 write their name, and after that they write the message. Since the operating 642 system can interrupt a process in any moment we can mix parts of the messages 643 of both processes, so we need a way to write the whole message to the file 644 atomically. To achieve this, we can use a named mutex so that each process 645 locks the mutex before writing: 646 </p> 647<p> 648</p> 649<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">interprocess</span><span class="special">/</span><span class="identifier">sync</span><span class="special">/</span><span class="identifier">scoped_lock</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 650<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">interprocess</span><span class="special">/</span><span class="identifier">sync</span><span class="special">/</span><span class="identifier">named_mutex</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 651<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">fstream</span><span class="special">></span> 652<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">iostream</span><span class="special">></span> 653<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">cstdio</span><span class="special">></span> 654 655 656<span class="keyword">int</span> <span class="identifier">main</span> <span class="special">()</span> 657<span class="special">{</span> 658 <span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">;</span> 659 <span class="keyword">try</span><span class="special">{</span> 660 <span class="keyword">struct</span> <span class="identifier">file_remove</span> 661 <span class="special">{</span> 662 <span class="identifier">file_remove</span><span class="special">()</span> <span class="special">{</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">remove</span><span class="special">(</span><span class="string">"file_name"</span><span class="special">);</span> <span class="special">}</span> 663 <span class="special">~</span><span class="identifier">file_remove</span><span class="special">(){</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">remove</span><span class="special">(</span><span class="string">"file_name"</span><span class="special">);</span> <span class="special">}</span> 664 <span class="special">}</span> <span class="identifier">file_remover</span><span class="special">;</span> 665 <span class="keyword">struct</span> <span class="identifier">mutex_remove</span> 666 <span class="special">{</span> 667 <span class="identifier">mutex_remove</span><span class="special">()</span> <span class="special">{</span> <span class="identifier">named_mutex</span><span class="special">::</span><span class="identifier">remove</span><span class="special">(</span><span class="string">"fstream_named_mutex"</span><span class="special">);</span> <span class="special">}</span> 668 <span class="special">~</span><span class="identifier">mutex_remove</span><span class="special">(){</span> <span class="identifier">named_mutex</span><span class="special">::</span><span class="identifier">remove</span><span class="special">(</span><span class="string">"fstream_named_mutex"</span><span class="special">);</span> <span class="special">}</span> 669 <span class="special">}</span> <span class="identifier">remover</span><span class="special">;</span> 670 671 <span class="comment">//Open or create the named mutex</span> 672 <span class="identifier">named_mutex</span> <span class="identifier">mutex</span><span class="special">(</span><span class="identifier">open_or_create</span><span class="special">,</span> <span class="string">"fstream_named_mutex"</span><span class="special">);</span> 673 674 <span class="identifier">std</span><span class="special">::</span><span class="identifier">ofstream</span> <span class="identifier">file</span><span class="special">(</span><span class="string">"file_name"</span><span class="special">);</span> 675 676 <span class="keyword">for</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">i</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span> <span class="identifier">i</span> <span class="special"><</span> <span class="number">10</span><span class="special">;</span> <span class="special">++</span><span class="identifier">i</span><span class="special">){</span> 677 678 <span class="comment">//Do some operations...</span> 679 680 <span class="comment">//Write to file atomically</span> 681 <span class="identifier">scoped_lock</span><span class="special"><</span><span class="identifier">named_mutex</span><span class="special">></span> <span class="identifier">lock</span><span class="special">(</span><span class="identifier">mutex</span><span class="special">);</span> 682 <span class="identifier">file</span> <span class="special"><<</span> <span class="string">"Process name, "</span><span class="special">;</span> 683 <span class="identifier">file</span> <span class="special"><<</span> <span class="string">"This is iteration #"</span> <span class="special"><<</span> <span class="identifier">i</span><span class="special">;</span> 684 <span class="identifier">file</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> 685 <span class="special">}</span> 686 <span class="special">}</span> 687 <span class="keyword">catch</span><span class="special">(</span><span class="identifier">interprocess_exception</span> <span class="special">&</span><span class="identifier">ex</span><span class="special">){</span> 688 <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="identifier">ex</span><span class="special">.</span><span class="identifier">what</span><span class="special">()</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> 689 <span class="keyword">return</span> <span class="number">1</span><span class="special">;</span> 690 <span class="special">}</span> 691 <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span> 692<span class="special">}</span> 693</pre> 694<p> 695 </p> 696</div> 697</div> 698<div class="section"> 699<div class="titlepage"><div><div><h3 class="title"> 700<a name="interprocess.synchronization_mechanisms.conditions"></a><a class="link" href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.conditions" title="Conditions">Conditions</a> 701</h3></div></div></div> 702<div class="toc"><dl class="toc"> 703<dt><span class="section"><a href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.conditions.conditions_whats_a_condition">What's 704 A Condition Variable?</a></span></dt> 705<dt><span class="section"><a href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.conditions.conditions_interprocess_conditions">Boost.Interprocess 706 Condition Types And Headers</a></span></dt> 707<dt><span class="section"><a href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.conditions.conditions_anonymous_example">Anonymous 708 condition example</a></span></dt> 709</dl></div> 710<div class="section"> 711<div class="titlepage"><div><div><h4 class="title"> 712<a name="interprocess.synchronization_mechanisms.conditions.conditions_whats_a_condition"></a><a class="link" href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.conditions.conditions_whats_a_condition" title="What's A Condition Variable?">What's 713 A Condition Variable?</a> 714</h4></div></div></div> 715<p> 716 In the previous example, a mutex is used to <span class="emphasis"><em>lock</em></span> but 717 we can't use it to <span class="emphasis"><em>wait</em></span> efficiently until the condition 718 to continue is met. A condition variable can do two things: 719 </p> 720<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 721<li class="listitem"> 722 <span class="bold"><strong>wait</strong></span>: The thread is blocked until 723 some other thread notifies that it can continue because the condition 724 that lead to waiting has disappeared. 725 </li> 726<li class="listitem"> 727 <span class="bold"><strong>notify</strong></span>: The thread sends a signal 728 to one blocked thread or to all blocked threads to tell them that they 729 the condition that provoked their wait has disappeared. 730 </li> 731</ul></div> 732<p> 733 Waiting in a condition variable is always associated with a mutex. The 734 mutex must be locked prior to waiting on the condition. When waiting on 735 the condition variable, the thread unlocks the mutex and waits <span class="bold"><strong>atomically</strong></span>. 736 </p> 737<p> 738 When the thread returns from a wait function (because of a signal or a 739 timeout, for example) the mutex object is again locked. 740 </p> 741</div> 742<div class="section"> 743<div class="titlepage"><div><div><h4 class="title"> 744<a name="interprocess.synchronization_mechanisms.conditions.conditions_interprocess_conditions"></a><a class="link" href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.conditions.conditions_interprocess_conditions" title="Boost.Interprocess Condition Types And Headers">Boost.Interprocess 745 Condition Types And Headers</a> 746</h4></div></div></div> 747<p> 748 Boost.Interprocess offers the following condition types: 749 </p> 750<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">interprocess</span><span class="special">/</span><span class="identifier">sync</span><span class="special">/</span><span class="identifier">interprocess_condition</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 751</pre> 752<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> 753 <code class="computeroutput"><a class="link" href="../boost/interprocess/interprocess_condition.html" title="Class interprocess_condition">interprocess_condition</a></code>: 754 An anonymous condition variable that can be placed in shared memory 755 or memory mapped files to be used with <code class="computeroutput"><a class="link" href="../boost/interprocess/interprocess_mutex.html" title="Class interprocess_mutex">boost::interprocess::interprocess_mutex</a></code>. 756 </li></ul></div> 757<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">interprocess</span><span class="special">/</span><span class="identifier">sync</span><span class="special">/</span><span class="identifier">interprocess_condition_any</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 758</pre> 759<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> 760 <code class="computeroutput"><a class="link" href="../boost/interprocess/interprocess_condition_any.html" title="Class interprocess_condition_any">interprocess_condition_any</a></code>: 761 An anonymous condition variable that can be placed in shared memory 762 or memory mapped files to be used with any lock type. 763 </li></ul></div> 764<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">interprocess</span><span class="special">/</span><span class="identifier">sync</span><span class="special">/</span><span class="identifier">named_condition</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 765</pre> 766<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> 767 <code class="computeroutput"><a class="link" href="../boost/interprocess/named_condition.html" title="Class named_condition">named_condition</a></code>: 768 A named condition variable to be used with <code class="computeroutput"><a class="link" href="../boost/interprocess/named_mutex.html" title="Class named_mutex">named_mutex</a></code>. 769 </li></ul></div> 770<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">interprocess</span><span class="special">/</span><span class="identifier">sync</span><span class="special">/</span><span class="identifier">named_condition_any</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 771</pre> 772<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> 773 <code class="computeroutput"><a class="link" href="../boost/interprocess/named_condition.html" title="Class named_condition">named_condition</a></code>: 774 A named condition variable to be used with any lock type. 775 </li></ul></div> 776<p> 777 Named conditions are similar to anonymous conditions, but they are used 778 in combination with named mutexes. Several times, we don't want to store 779 synchronization objects with the synchronized data: 780 </p> 781<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 782<li class="listitem"> 783 We want to change the synchronization method (from interprocess to 784 intra-process, or without any synchronization) using the same data. 785 Storing the process-shared anonymous synchronization with the synchronized 786 data would forbid this. 787 </li> 788<li class="listitem"> 789 We want to send the synchronized data through the network or any other 790 communication method. Sending the process-shared synchronization objects 791 wouldn't have any sense. 792 </li> 793</ul></div> 794</div> 795<div class="section"> 796<div class="titlepage"><div><div><h4 class="title"> 797<a name="interprocess.synchronization_mechanisms.conditions.conditions_anonymous_example"></a><a class="link" href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.conditions.conditions_anonymous_example" title="Anonymous condition example">Anonymous 798 condition example</a> 799</h4></div></div></div> 800<p> 801 Imagine that a process that writes a trace to a simple shared memory buffer 802 that another process prints one by one. The first process writes the trace 803 and waits until the other process prints the data. To achieve this, we 804 can use two condition variables: the first one is used to block the sender 805 until the second process prints the message and the second one to block 806 the receiver until the buffer has a trace to print. 807 </p> 808<p> 809 The shared memory trace buffer (doc_anonymous_condition_shared_data.hpp): 810 </p> 811<p> 812</p> 813<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">interprocess</span><span class="special">/</span><span class="identifier">sync</span><span class="special">/</span><span class="identifier">interprocess_mutex</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 814<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">interprocess</span><span class="special">/</span><span class="identifier">sync</span><span class="special">/</span><span class="identifier">interprocess_condition</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 815 816<span class="keyword">struct</span> <span class="identifier">trace_queue</span> 817<span class="special">{</span> 818 <span class="keyword">enum</span> <span class="special">{</span> <span class="identifier">LineSize</span> <span class="special">=</span> <span class="number">100</span> <span class="special">};</span> 819 820 <span class="identifier">trace_queue</span><span class="special">()</span> 821 <span class="special">:</span> <span class="identifier">message_in</span><span class="special">(</span><span class="keyword">false</span><span class="special">)</span> 822 <span class="special">{}</span> 823 824 <span class="comment">//Mutex to protect access to the queue</span> 825 <span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">::</span><span class="identifier">interprocess_mutex</span> <span class="identifier">mutex</span><span class="special">;</span> 826 827 <span class="comment">//Condition to wait when the queue is empty</span> 828 <span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">::</span><span class="identifier">interprocess_condition</span> <span class="identifier">cond_empty</span><span class="special">;</span> 829 830 <span class="comment">//Condition to wait when the queue is full</span> 831 <span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">::</span><span class="identifier">interprocess_condition</span> <span class="identifier">cond_full</span><span class="special">;</span> 832 833 <span class="comment">//Items to fill</span> 834 <span class="keyword">char</span> <span class="identifier">items</span><span class="special">[</span><span class="identifier">LineSize</span><span class="special">];</span> 835 836 <span class="comment">//Is there any message</span> 837 <span class="keyword">bool</span> <span class="identifier">message_in</span><span class="special">;</span> 838<span class="special">};</span> 839</pre> 840<p> 841 </p> 842<p> 843 This is the process main process. Creates the shared memory, places there 844 the buffer and starts writing messages one by one until it writes "last 845 message" to indicate that there are no more messages to print: 846 </p> 847<p> 848</p> 849<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">interprocess</span><span class="special">/</span><span class="identifier">shared_memory_object</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 850<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">interprocess</span><span class="special">/</span><span class="identifier">mapped_region</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 851<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">interprocess</span><span class="special">/</span><span class="identifier">sync</span><span class="special">/</span><span class="identifier">scoped_lock</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 852<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">iostream</span><span class="special">></span> 853<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">cstdio</span><span class="special">></span> 854<span class="preprocessor">#include</span> <span class="string">"doc_anonymous_condition_shared_data.hpp"</span> 855 856<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">;</span> 857 858<span class="keyword">int</span> <span class="identifier">main</span> <span class="special">()</span> 859<span class="special">{</span> 860 861 <span class="comment">//Erase previous shared memory and schedule erasure on exit</span> 862 <span class="keyword">struct</span> <span class="identifier">shm_remove</span> 863 <span class="special">{</span> 864 <span class="identifier">shm_remove</span><span class="special">()</span> <span class="special">{</span> <span class="identifier">shared_memory_object</span><span class="special">::</span><span class="identifier">remove</span><span class="special">(</span><span class="string">"MySharedMemory"</span><span class="special">);</span> <span class="special">}</span> 865 <span class="special">~</span><span class="identifier">shm_remove</span><span class="special">(){</span> <span class="identifier">shared_memory_object</span><span class="special">::</span><span class="identifier">remove</span><span class="special">(</span><span class="string">"MySharedMemory"</span><span class="special">);</span> <span class="special">}</span> 866 <span class="special">}</span> <span class="identifier">remover</span><span class="special">;</span> 867 868 <span class="comment">//Create a shared memory object.</span> 869 <span class="identifier">shared_memory_object</span> <span class="identifier">shm</span> 870 <span class="special">(</span><span class="identifier">create_only</span> <span class="comment">//only create</span> 871 <span class="special">,</span><span class="string">"MySharedMemory"</span> <span class="comment">//name</span> 872 <span class="special">,</span><span class="identifier">read_write</span> <span class="comment">//read-write mode</span> 873 <span class="special">);</span> 874 <span class="keyword">try</span><span class="special">{</span> 875 <span class="comment">//Set size</span> 876 <span class="identifier">shm</span><span class="special">.</span><span class="identifier">truncate</span><span class="special">(</span><span class="keyword">sizeof</span><span class="special">(</span><span class="identifier">trace_queue</span><span class="special">));</span> 877 878 <span class="comment">//Map the whole shared memory in this process</span> 879 <span class="identifier">mapped_region</span> <span class="identifier">region</span> 880 <span class="special">(</span><span class="identifier">shm</span> <span class="comment">//What to map</span> 881 <span class="special">,</span><span class="identifier">read_write</span> <span class="comment">//Map it as read-write</span> 882 <span class="special">);</span> 883 884 <span class="comment">//Get the address of the mapped region</span> 885 <span class="keyword">void</span> <span class="special">*</span> <span class="identifier">addr</span> <span class="special">=</span> <span class="identifier">region</span><span class="special">.</span><span class="identifier">get_address</span><span class="special">();</span> 886 887 <span class="comment">//Construct the shared structure in memory</span> 888 <span class="identifier">trace_queue</span> <span class="special">*</span> <span class="identifier">data</span> <span class="special">=</span> <span class="keyword">new</span> <span class="special">(</span><span class="identifier">addr</span><span class="special">)</span> <span class="identifier">trace_queue</span><span class="special">;</span> 889 890 <span class="keyword">const</span> <span class="keyword">int</span> <span class="identifier">NumMsg</span> <span class="special">=</span> <span class="number">100</span><span class="special">;</span> 891 892 <span class="keyword">for</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">i</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span> <span class="identifier">i</span> <span class="special"><</span> <span class="identifier">NumMsg</span><span class="special">;</span> <span class="special">++</span><span class="identifier">i</span><span class="special">){</span> 893 <span class="identifier">scoped_lock</span><span class="special"><</span><span class="identifier">interprocess_mutex</span><span class="special">></span> <span class="identifier">lock</span><span class="special">(</span><span class="identifier">data</span><span class="special">-></span><span class="identifier">mutex</span><span class="special">);</span> 894 <span class="keyword">if</span><span class="special">(</span><span class="identifier">data</span><span class="special">-></span><span class="identifier">message_in</span><span class="special">){</span> 895 <span class="identifier">data</span><span class="special">-></span><span class="identifier">cond_full</span><span class="special">.</span><span class="identifier">wait</span><span class="special">(</span><span class="identifier">lock</span><span class="special">);</span> 896 <span class="special">}</span> 897 <span class="keyword">if</span><span class="special">(</span><span class="identifier">i</span> <span class="special">==</span> <span class="special">(</span><span class="identifier">NumMsg</span><span class="special">-</span><span class="number">1</span><span class="special">))</span> 898 <span class="identifier">std</span><span class="special">::</span><span class="identifier">sprintf</span><span class="special">(</span><span class="identifier">data</span><span class="special">-></span><span class="identifier">items</span><span class="special">,</span> <span class="string">"%s"</span><span class="special">,</span> <span class="string">"last message"</span><span class="special">);</span> 899 <span class="keyword">else</span> 900 <span class="identifier">std</span><span class="special">::</span><span class="identifier">sprintf</span><span class="special">(</span><span class="identifier">data</span><span class="special">-></span><span class="identifier">items</span><span class="special">,</span> <span class="string">"%s_%d"</span><span class="special">,</span> <span class="string">"my_trace"</span><span class="special">,</span> <span class="identifier">i</span><span class="special">);</span> 901 902 <span class="comment">//Notify to the other process that there is a message</span> 903 <span class="identifier">data</span><span class="special">-></span><span class="identifier">cond_empty</span><span class="special">.</span><span class="identifier">notify_one</span><span class="special">();</span> 904 905 <span class="comment">//Mark message buffer as full</span> 906 <span class="identifier">data</span><span class="special">-></span><span class="identifier">message_in</span> <span class="special">=</span> <span class="keyword">true</span><span class="special">;</span> 907 <span class="special">}</span> 908 <span class="special">}</span> 909 <span class="keyword">catch</span><span class="special">(</span><span class="identifier">interprocess_exception</span> <span class="special">&</span><span class="identifier">ex</span><span class="special">){</span> 910 <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="identifier">ex</span><span class="special">.</span><span class="identifier">what</span><span class="special">()</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> 911 <span class="keyword">return</span> <span class="number">1</span><span class="special">;</span> 912 <span class="special">}</span> 913 914 <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span> 915<span class="special">}</span> 916</pre> 917<p> 918 </p> 919<p> 920 The second process opens the shared memory and prints each message until 921 the "last message" message is received: 922 </p> 923<p> 924</p> 925<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">interprocess</span><span class="special">/</span><span class="identifier">shared_memory_object</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 926<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">interprocess</span><span class="special">/</span><span class="identifier">mapped_region</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 927<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">interprocess</span><span class="special">/</span><span class="identifier">sync</span><span class="special">/</span><span class="identifier">scoped_lock</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 928<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">iostream</span><span class="special">></span> 929<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">cstring</span><span class="special">></span> 930<span class="preprocessor">#include</span> <span class="string">"doc_anonymous_condition_shared_data.hpp"</span> 931 932<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">;</span> 933 934<span class="keyword">int</span> <span class="identifier">main</span> <span class="special">()</span> 935<span class="special">{</span> 936 <span class="comment">//Create a shared memory object.</span> 937 <span class="identifier">shared_memory_object</span> <span class="identifier">shm</span> 938 <span class="special">(</span><span class="identifier">open_only</span> <span class="comment">//only create</span> 939 <span class="special">,</span><span class="string">"MySharedMemory"</span> <span class="comment">//name</span> 940 <span class="special">,</span><span class="identifier">read_write</span> <span class="comment">//read-write mode</span> 941 <span class="special">);</span> 942 943 <span class="keyword">try</span><span class="special">{</span> 944 <span class="comment">//Map the whole shared memory in this process</span> 945 <span class="identifier">mapped_region</span> <span class="identifier">region</span> 946 <span class="special">(</span><span class="identifier">shm</span> <span class="comment">//What to map</span> 947 <span class="special">,</span><span class="identifier">read_write</span> <span class="comment">//Map it as read-write</span> 948 <span class="special">);</span> 949 950 <span class="comment">//Get the address of the mapped region</span> 951 <span class="keyword">void</span> <span class="special">*</span> <span class="identifier">addr</span> <span class="special">=</span> <span class="identifier">region</span><span class="special">.</span><span class="identifier">get_address</span><span class="special">();</span> 952 953 <span class="comment">//Obtain a pointer to the shared structure</span> 954 <span class="identifier">trace_queue</span> <span class="special">*</span> <span class="identifier">data</span> <span class="special">=</span> <span class="keyword">static_cast</span><span class="special"><</span><span class="identifier">trace_queue</span><span class="special">*>(</span><span class="identifier">addr</span><span class="special">);</span> 955 956 <span class="comment">//Print messages until the other process marks the end</span> 957 <span class="keyword">bool</span> <span class="identifier">end_loop</span> <span class="special">=</span> <span class="keyword">false</span><span class="special">;</span> 958 <span class="keyword">do</span><span class="special">{</span> 959 <span class="identifier">scoped_lock</span><span class="special"><</span><span class="identifier">interprocess_mutex</span><span class="special">></span> <span class="identifier">lock</span><span class="special">(</span><span class="identifier">data</span><span class="special">-></span><span class="identifier">mutex</span><span class="special">);</span> 960 <span class="keyword">if</span><span class="special">(!</span><span class="identifier">data</span><span class="special">-></span><span class="identifier">message_in</span><span class="special">){</span> 961 <span class="identifier">data</span><span class="special">-></span><span class="identifier">cond_empty</span><span class="special">.</span><span class="identifier">wait</span><span class="special">(</span><span class="identifier">lock</span><span class="special">);</span> 962 <span class="special">}</span> 963 <span class="keyword">if</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">strcmp</span><span class="special">(</span><span class="identifier">data</span><span class="special">-></span><span class="identifier">items</span><span class="special">,</span> <span class="string">"last message"</span><span class="special">)</span> <span class="special">==</span> <span class="number">0</span><span class="special">){</span> 964 <span class="identifier">end_loop</span> <span class="special">=</span> <span class="keyword">true</span><span class="special">;</span> 965 <span class="special">}</span> 966 <span class="keyword">else</span><span class="special">{</span> 967 <span class="comment">//Print the message</span> 968 <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="identifier">data</span><span class="special">-></span><span class="identifier">items</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> 969 <span class="comment">//Notify the other process that the buffer is empty</span> 970 <span class="identifier">data</span><span class="special">-></span><span class="identifier">message_in</span> <span class="special">=</span> <span class="keyword">false</span><span class="special">;</span> 971 <span class="identifier">data</span><span class="special">-></span><span class="identifier">cond_full</span><span class="special">.</span><span class="identifier">notify_one</span><span class="special">();</span> 972 <span class="special">}</span> 973 <span class="special">}</span> 974 <span class="keyword">while</span><span class="special">(!</span><span class="identifier">end_loop</span><span class="special">);</span> 975 <span class="special">}</span> 976 <span class="keyword">catch</span><span class="special">(</span><span class="identifier">interprocess_exception</span> <span class="special">&</span><span class="identifier">ex</span><span class="special">){</span> 977 <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="identifier">ex</span><span class="special">.</span><span class="identifier">what</span><span class="special">()</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> 978 <span class="keyword">return</span> <span class="number">1</span><span class="special">;</span> 979 <span class="special">}</span> 980 981 <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span> 982<span class="special">}</span> 983</pre> 984<p> 985 </p> 986<p> 987 With condition variables, a process can block if it can't continue the 988 work, and when the conditions to continue are met another process can wake 989 it. 990 </p> 991</div> 992</div> 993<div class="section"> 994<div class="titlepage"><div><div><h3 class="title"> 995<a name="interprocess.synchronization_mechanisms.semaphores"></a><a class="link" href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.semaphores" title="Semaphores">Semaphores</a> 996</h3></div></div></div> 997<div class="toc"><dl class="toc"> 998<dt><span class="section"><a href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.semaphores.semaphores_whats_a_semaphores">What's 999 A Semaphore?</a></span></dt> 1000<dt><span class="section"><a href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.semaphores.semaphores_interprocess_semaphores">Boost.Interprocess 1001 Semaphore Types And Headers</a></span></dt> 1002<dt><span class="section"><a href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.semaphores.semaphores_anonymous_example">Anonymous 1003 semaphore example</a></span></dt> 1004</dl></div> 1005<div class="section"> 1006<div class="titlepage"><div><div><h4 class="title"> 1007<a name="interprocess.synchronization_mechanisms.semaphores.semaphores_whats_a_semaphores"></a><a class="link" href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.semaphores.semaphores_whats_a_semaphores" title="What's A Semaphore?">What's 1008 A Semaphore?</a> 1009</h4></div></div></div> 1010<p> 1011 A semaphore is a synchronization mechanism between processes based in an 1012 internal count that offers two basic operations: 1013 </p> 1014<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 1015<li class="listitem"> 1016 <span class="bold"><strong>Wait</strong></span>: Tests the value of the semaphore 1017 count, and waits if the value is less than or equal than 0. Otherwise, 1018 decrements the semaphore count. 1019 </li> 1020<li class="listitem"> 1021 <span class="bold"><strong>Post</strong></span>: Increments the semaphore count. 1022 If any process is blocked, one of those processes is awoken. 1023 </li> 1024</ul></div> 1025<p> 1026 If the initial semaphore count is initialized to 1, a <span class="bold"><strong>Wait</strong></span> 1027 operation is equivalent to a mutex locking and <span class="bold"><strong>Post</strong></span> 1028 is equivalent to a mutex unlocking. This type of semaphore is known as 1029 a <span class="bold"><strong>binary semaphore</strong></span>. 1030 </p> 1031<p> 1032 Although semaphores can be used like mutexes, they have a unique feature: 1033 unlike mutexes, a <span class="bold"><strong>Post</strong></span> operation need 1034 not be executed by the same thread/process that executed the <span class="bold"><strong>Wait</strong></span> operation. 1035 </p> 1036</div> 1037<div class="section"> 1038<div class="titlepage"><div><div><h4 class="title"> 1039<a name="interprocess.synchronization_mechanisms.semaphores.semaphores_interprocess_semaphores"></a><a class="link" href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.semaphores.semaphores_interprocess_semaphores" title="Boost.Interprocess Semaphore Types And Headers">Boost.Interprocess 1040 Semaphore Types And Headers</a> 1041</h4></div></div></div> 1042<p> 1043 Boost.Interprocess offers the following semaphore types: 1044 </p> 1045<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">interprocess</span><span class="special">/</span><span class="identifier">sync</span><span class="special">/</span><span class="identifier">interprocess_semaphore</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 1046</pre> 1047<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> 1048 <code class="computeroutput"><a class="link" href="../boost/interprocess/interprocess_semaphore.html" title="Class interprocess_semaphore">interprocess_semaphore</a></code>: 1049 An anonymous semaphore that can be placed in shared memory or memory 1050 mapped files. 1051 </li></ul></div> 1052<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">interprocess</span><span class="special">/</span><span class="identifier">sync</span><span class="special">/</span><span class="identifier">named_semaphore</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 1053</pre> 1054<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> 1055 <code class="computeroutput"><a class="link" href="../boost/interprocess/named_semaphore.html" title="Class named_semaphore">named_semaphore</a></code>: 1056 A named semaphore. 1057 </li></ul></div> 1058</div> 1059<div class="section"> 1060<div class="titlepage"><div><div><h4 class="title"> 1061<a name="interprocess.synchronization_mechanisms.semaphores.semaphores_anonymous_example"></a><a class="link" href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.semaphores.semaphores_anonymous_example" title="Anonymous semaphore example">Anonymous 1062 semaphore example</a> 1063</h4></div></div></div> 1064<p> 1065 We will implement an integer array in shared memory that will be used to 1066 transfer data from one process to another process. The first process will 1067 write some integers to the array and the process will block if the array 1068 is full. 1069 </p> 1070<p> 1071 The second process will copy the transmitted data to its own buffer, blocking 1072 if there is no new data in the buffer. 1073 </p> 1074<p> 1075 This is the shared integer array (doc_anonymous_semaphore_shared_data.hpp): 1076 </p> 1077<p> 1078</p> 1079<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">interprocess</span><span class="special">/</span><span class="identifier">sync</span><span class="special">/</span><span class="identifier">interprocess_semaphore</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 1080 1081<span class="keyword">struct</span> <span class="identifier">shared_memory_buffer</span> 1082<span class="special">{</span> 1083 <span class="keyword">enum</span> <span class="special">{</span> <span class="identifier">NumItems</span> <span class="special">=</span> <span class="number">10</span> <span class="special">};</span> 1084 1085 <span class="identifier">shared_memory_buffer</span><span class="special">()</span> 1086 <span class="special">:</span> <span class="identifier">mutex</span><span class="special">(</span><span class="number">1</span><span class="special">),</span> <span class="identifier">nempty</span><span class="special">(</span><span class="identifier">NumItems</span><span class="special">),</span> <span class="identifier">nstored</span><span class="special">(</span><span class="number">0</span><span class="special">)</span> 1087 <span class="special">{}</span> 1088 1089 <span class="comment">//Semaphores to protect and synchronize access</span> 1090 <span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">::</span><span class="identifier">interprocess_semaphore</span> 1091 <span class="identifier">mutex</span><span class="special">,</span> <span class="identifier">nempty</span><span class="special">,</span> <span class="identifier">nstored</span><span class="special">;</span> 1092 1093 <span class="comment">//Items to fill</span> 1094 <span class="keyword">int</span> <span class="identifier">items</span><span class="special">[</span><span class="identifier">NumItems</span><span class="special">];</span> 1095<span class="special">};</span> 1096</pre> 1097<p> 1098 </p> 1099<p> 1100 This is the process main process. Creates the shared memory, places there 1101 the integer array and starts integers one by one, blocking if the array 1102 is full: 1103 </p> 1104<p> 1105</p> 1106<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">interprocess</span><span class="special">/</span><span class="identifier">shared_memory_object</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 1107<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">interprocess</span><span class="special">/</span><span class="identifier">mapped_region</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 1108<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">iostream</span><span class="special">></span> 1109<span class="preprocessor">#include</span> <span class="string">"doc_anonymous_semaphore_shared_data.hpp"</span> 1110 1111<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">;</span> 1112 1113<span class="keyword">int</span> <span class="identifier">main</span> <span class="special">()</span> 1114<span class="special">{</span> 1115 <span class="comment">//Remove shared memory on construction and destruction</span> 1116 <span class="keyword">struct</span> <span class="identifier">shm_remove</span> 1117 <span class="special">{</span> 1118 <span class="identifier">shm_remove</span><span class="special">()</span> <span class="special">{</span> <span class="identifier">shared_memory_object</span><span class="special">::</span><span class="identifier">remove</span><span class="special">(</span><span class="string">"MySharedMemory"</span><span class="special">);</span> <span class="special">}</span> 1119 <span class="special">~</span><span class="identifier">shm_remove</span><span class="special">(){</span> <span class="identifier">shared_memory_object</span><span class="special">::</span><span class="identifier">remove</span><span class="special">(</span><span class="string">"MySharedMemory"</span><span class="special">);</span> <span class="special">}</span> 1120 <span class="special">}</span> <span class="identifier">remover</span><span class="special">;</span> 1121 1122 <span class="comment">//Create a shared memory object.</span> 1123 <span class="identifier">shared_memory_object</span> <span class="identifier">shm</span> 1124 <span class="special">(</span><span class="identifier">create_only</span> <span class="comment">//only create</span> 1125 <span class="special">,</span><span class="string">"MySharedMemory"</span> <span class="comment">//name</span> 1126 <span class="special">,</span><span class="identifier">read_write</span> <span class="comment">//read-write mode</span> 1127 <span class="special">);</span> 1128 1129 <span class="comment">//Set size</span> 1130 <span class="identifier">shm</span><span class="special">.</span><span class="identifier">truncate</span><span class="special">(</span><span class="keyword">sizeof</span><span class="special">(</span><span class="identifier">shared_memory_buffer</span><span class="special">));</span> 1131 1132 <span class="comment">//Map the whole shared memory in this process</span> 1133 <span class="identifier">mapped_region</span> <span class="identifier">region</span> 1134 <span class="special">(</span><span class="identifier">shm</span> <span class="comment">//What to map</span> 1135 <span class="special">,</span><span class="identifier">read_write</span> <span class="comment">//Map it as read-write</span> 1136 <span class="special">);</span> 1137 1138 <span class="comment">//Get the address of the mapped region</span> 1139 <span class="keyword">void</span> <span class="special">*</span> <span class="identifier">addr</span> <span class="special">=</span> <span class="identifier">region</span><span class="special">.</span><span class="identifier">get_address</span><span class="special">();</span> 1140 1141 <span class="comment">//Construct the shared structure in memory</span> 1142 <span class="identifier">shared_memory_buffer</span> <span class="special">*</span> <span class="identifier">data</span> <span class="special">=</span> <span class="keyword">new</span> <span class="special">(</span><span class="identifier">addr</span><span class="special">)</span> <span class="identifier">shared_memory_buffer</span><span class="special">;</span> 1143 1144 <span class="keyword">const</span> <span class="keyword">int</span> <span class="identifier">NumMsg</span> <span class="special">=</span> <span class="number">100</span><span class="special">;</span> 1145 1146 <span class="comment">//Insert data in the array</span> 1147 <span class="keyword">for</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">i</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span> <span class="identifier">i</span> <span class="special"><</span> <span class="identifier">NumMsg</span><span class="special">;</span> <span class="special">++</span><span class="identifier">i</span><span class="special">){</span> 1148 <span class="identifier">data</span><span class="special">-></span><span class="identifier">nempty</span><span class="special">.</span><span class="identifier">wait</span><span class="special">();</span> 1149 <span class="identifier">data</span><span class="special">-></span><span class="identifier">mutex</span><span class="special">.</span><span class="identifier">wait</span><span class="special">();</span> 1150 <span class="identifier">data</span><span class="special">-></span><span class="identifier">items</span><span class="special">[</span><span class="identifier">i</span> <span class="special">%</span> <span class="identifier">shared_memory_buffer</span><span class="special">::</span><span class="identifier">NumItems</span><span class="special">]</span> <span class="special">=</span> <span class="identifier">i</span><span class="special">;</span> 1151 <span class="identifier">data</span><span class="special">-></span><span class="identifier">mutex</span><span class="special">.</span><span class="identifier">post</span><span class="special">();</span> 1152 <span class="identifier">data</span><span class="special">-></span><span class="identifier">nstored</span><span class="special">.</span><span class="identifier">post</span><span class="special">();</span> 1153 <span class="special">}</span> 1154 1155 <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span> 1156<span class="special">}</span> 1157</pre> 1158<p> 1159 </p> 1160<p> 1161 The second process opens the shared memory and copies the received integers 1162 to it's own buffer: 1163 </p> 1164<p> 1165</p> 1166<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">interprocess</span><span class="special">/</span><span class="identifier">shared_memory_object</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 1167<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">interprocess</span><span class="special">/</span><span class="identifier">mapped_region</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 1168<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">iostream</span><span class="special">></span> 1169<span class="preprocessor">#include</span> <span class="string">"doc_anonymous_semaphore_shared_data.hpp"</span> 1170 1171<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">;</span> 1172 1173<span class="keyword">int</span> <span class="identifier">main</span> <span class="special">()</span> 1174<span class="special">{</span> 1175 <span class="comment">//Remove shared memory on destruction</span> 1176 <span class="keyword">struct</span> <span class="identifier">shm_remove</span> 1177 <span class="special">{</span> 1178 <span class="special">~</span><span class="identifier">shm_remove</span><span class="special">(){</span> <span class="identifier">shared_memory_object</span><span class="special">::</span><span class="identifier">remove</span><span class="special">(</span><span class="string">"MySharedMemory"</span><span class="special">);</span> <span class="special">}</span> 1179 <span class="special">}</span> <span class="identifier">remover</span><span class="special">;</span> 1180 1181 <span class="comment">//Create a shared memory object.</span> 1182 <span class="identifier">shared_memory_object</span> <span class="identifier">shm</span> 1183 <span class="special">(</span><span class="identifier">open_only</span> <span class="comment">//only create</span> 1184 <span class="special">,</span><span class="string">"MySharedMemory"</span> <span class="comment">//name</span> 1185 <span class="special">,</span><span class="identifier">read_write</span> <span class="comment">//read-write mode</span> 1186 <span class="special">);</span> 1187 1188 <span class="comment">//Map the whole shared memory in this process</span> 1189 <span class="identifier">mapped_region</span> <span class="identifier">region</span> 1190 <span class="special">(</span><span class="identifier">shm</span> <span class="comment">//What to map</span> 1191 <span class="special">,</span><span class="identifier">read_write</span> <span class="comment">//Map it as read-write</span> 1192 <span class="special">);</span> 1193 1194 <span class="comment">//Get the address of the mapped region</span> 1195 <span class="keyword">void</span> <span class="special">*</span> <span class="identifier">addr</span> <span class="special">=</span> <span class="identifier">region</span><span class="special">.</span><span class="identifier">get_address</span><span class="special">();</span> 1196 1197 <span class="comment">//Obtain the shared structure</span> 1198 <span class="identifier">shared_memory_buffer</span> <span class="special">*</span> <span class="identifier">data</span> <span class="special">=</span> <span class="keyword">static_cast</span><span class="special"><</span><span class="identifier">shared_memory_buffer</span><span class="special">*>(</span><span class="identifier">addr</span><span class="special">);</span> 1199 1200 <span class="keyword">const</span> <span class="keyword">int</span> <span class="identifier">NumMsg</span> <span class="special">=</span> <span class="number">100</span><span class="special">;</span> 1201 1202 <span class="keyword">int</span> <span class="identifier">extracted_data</span> <span class="special">[</span><span class="identifier">NumMsg</span><span class="special">];</span> 1203 1204 <span class="comment">//Extract the data</span> 1205 <span class="keyword">for</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">i</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span> <span class="identifier">i</span> <span class="special"><</span> <span class="identifier">NumMsg</span><span class="special">;</span> <span class="special">++</span><span class="identifier">i</span><span class="special">){</span> 1206 <span class="identifier">data</span><span class="special">-></span><span class="identifier">nstored</span><span class="special">.</span><span class="identifier">wait</span><span class="special">();</span> 1207 <span class="identifier">data</span><span class="special">-></span><span class="identifier">mutex</span><span class="special">.</span><span class="identifier">wait</span><span class="special">();</span> 1208 <span class="identifier">extracted_data</span><span class="special">[</span><span class="identifier">i</span><span class="special">]</span> <span class="special">=</span> <span class="identifier">data</span><span class="special">-></span><span class="identifier">items</span><span class="special">[</span><span class="identifier">i</span> <span class="special">%</span> <span class="identifier">shared_memory_buffer</span><span class="special">::</span><span class="identifier">NumItems</span><span class="special">];</span> 1209 <span class="identifier">data</span><span class="special">-></span><span class="identifier">mutex</span><span class="special">.</span><span class="identifier">post</span><span class="special">();</span> 1210 <span class="identifier">data</span><span class="special">-></span><span class="identifier">nempty</span><span class="special">.</span><span class="identifier">post</span><span class="special">();</span> 1211 <span class="special">}</span> 1212 <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span> 1213<span class="special">}</span> 1214</pre> 1215<p> 1216 </p> 1217<p> 1218 The same interprocess communication can be achieved with a condition variables 1219 and mutexes, but for several synchronization patterns, a semaphore is more 1220 efficient than a mutex/condition combination. 1221 </p> 1222</div> 1223</div> 1224<div class="section"> 1225<div class="titlepage"><div><div><h3 class="title"> 1226<a name="interprocess.synchronization_mechanisms.sharable_upgradable_mutexes"></a><a class="link" href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.sharable_upgradable_mutexes" title="Sharable and Upgradable Mutexes">Sharable 1227 and Upgradable Mutexes</a> 1228</h3></div></div></div> 1229<div class="toc"><dl class="toc"> 1230<dt><span class="section"><a href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.sharable_upgradable_mutexes.upgradable_whats_a_mutex">What's 1231 a Sharable and an Upgradable Mutex?</a></span></dt> 1232<dt><span class="section"><a href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.sharable_upgradable_mutexes.upgradable_transitions">Lock 1233 transitions for Upgradable Mutex</a></span></dt> 1234<dt><span class="section"><a href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.sharable_upgradable_mutexes.sharable_upgradable_mutexes_operations">Upgradable 1235 Mutex Operations</a></span></dt> 1236<dt><span class="section"><a href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.sharable_upgradable_mutexes.sharable_upgradable_mutexes_mutex_interprocess_mutexes">Boost.Interprocess 1237 Sharable & Upgradable Mutex Types And Headers</a></span></dt> 1238<dt><span class="section"><a href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.sharable_upgradable_mutexes.sharable_upgradable_locks">Sharable 1239 Lock And Upgradable Lock</a></span></dt> 1240</dl></div> 1241<div class="section"> 1242<div class="titlepage"><div><div><h4 class="title"> 1243<a name="interprocess.synchronization_mechanisms.sharable_upgradable_mutexes.upgradable_whats_a_mutex"></a><a class="link" href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.sharable_upgradable_mutexes.upgradable_whats_a_mutex" title="What's a Sharable and an Upgradable Mutex?">What's 1244 a Sharable and an Upgradable Mutex?</a> 1245</h4></div></div></div> 1246<p> 1247 Sharable and upgradable mutex are special mutex types that offers more 1248 locking possibilities than a normal mutex. Sometimes, we can distinguish 1249 between <span class="bold"><strong>reading</strong></span> the data and <span class="bold"><strong>modifying</strong></span> the data. If just some threads need to 1250 modify the data, and a plain mutex is used to protect the data from concurrent 1251 access, concurrency is pretty limited: two threads that only read the data 1252 will be serialized instead of being executed concurrently. 1253 </p> 1254<p> 1255 If we allow concurrent access to threads that just read the data but we 1256 avoid concurrent access between threads that read and modify or between 1257 threads that modify, we can increase performance. This is specially true 1258 in applications where data reading is more common than data modification 1259 and the synchronized data reading code needs some time to execute. With 1260 a sharable mutex we can acquire 2 lock types: 1261 </p> 1262<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 1263<li class="listitem"> 1264 <span class="bold"><strong>Exclusive lock</strong></span>: Similar to a plain 1265 mutex. If a thread acquires an exclusive lock, no other thread can 1266 acquire any lock (exclusive or other) until the exclusive lock is released. 1267 If any thread other has any lock other than exclusive, a thread trying 1268 to acquire an exclusive lock will block. This lock will be acquired 1269 by threads that will modify the data. 1270 </li> 1271<li class="listitem"> 1272 <span class="bold"><strong>Sharable lock</strong></span>: If a thread acquires 1273 a sharable lock, other threads can't acquire the exclusive lock. If 1274 any thread has acquired the exclusive lock a thread trying to acquire 1275 a sharable lock will block. This locking is executed by threads that 1276 just need to read the data. 1277 </li> 1278</ul></div> 1279<p> 1280 With an upgradable mutex we can acquire previous locks plus a new upgradable 1281 lock: 1282 </p> 1283<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> 1284 <span class="bold"><strong>Upgradable lock</strong></span>: Acquiring an upgradable 1285 lock is similar to acquiring a <span class="bold"><strong>privileged sharable 1286 lock</strong></span>. If a thread acquires an upgradable lock, other threads 1287 can acquire a sharable lock. If any thread has acquired the exclusive 1288 or upgradable lock a thread trying to acquire an upgradable lock will 1289 block. A thread that has acquired an upgradable lock, is guaranteed 1290 to be able to acquire atomically an exclusive lock when other threads 1291 that have acquired a sharable lock release it. This is used for a thread 1292 that <span class="bold"><strong>maybe</strong></span> needs to modify the data, 1293 but usually just needs to read the data. This thread acquires the upgradable 1294 lock and other threads can acquire the sharable lock. If the upgradable 1295 thread reads the data and it has to modify it, the thread can be promoted 1296 to acquire the exclusive lock: when all sharable threads have released 1297 the sharable lock, the upgradable lock is atomically promoted to an 1298 exclusive lock. The newly promoted thread can modify the data and it 1299 can be sure that no other thread has modified it while doing the transition. 1300 <span class="bold"><strong>Only 1 thread can acquire the upgradable (privileged 1301 reader) lock</strong></span>. 1302 </li></ul></div> 1303<p> 1304 To sum up: 1305 </p> 1306<div class="table"> 1307<a name="interprocess.synchronization_mechanisms.sharable_upgradable_mutexes.upgradable_whats_a_mutex.locking_possibilities_for_a_sharable_mutex"></a><p class="title"><b>Table 18.5. Locking Possibilities for a Sharable Mutex</b></p> 1308<div class="table-contents"><table class="table" summary="Locking Possibilities for a Sharable Mutex"> 1309<colgroup> 1310<col> 1311<col> 1312</colgroup> 1313<thead><tr> 1314<th> 1315 <p> 1316 If a thread has acquired the... 1317 </p> 1318 </th> 1319<th> 1320 <p> 1321 Other threads can acquire... 1322 </p> 1323 </th> 1324</tr></thead> 1325<tbody> 1326<tr> 1327<td> 1328 <p> 1329 Sharable lock 1330 </p> 1331 </td> 1332<td> 1333 <p> 1334 many sharable locks 1335 </p> 1336 </td> 1337</tr> 1338<tr> 1339<td> 1340 <p> 1341 Exclusive lock 1342 </p> 1343 </td> 1344<td> 1345 <p> 1346 no locks 1347 </p> 1348 </td> 1349</tr> 1350</tbody> 1351</table></div> 1352</div> 1353<br class="table-break"><div class="table"> 1354<a name="interprocess.synchronization_mechanisms.sharable_upgradable_mutexes.upgradable_whats_a_mutex.locking_possibilities_for_an_upgradable_mutex"></a><p class="title"><b>Table 18.6. Locking Possibilities for an Upgradable Mutex</b></p> 1355<div class="table-contents"><table class="table" summary="Locking Possibilities for an Upgradable Mutex"> 1356<colgroup> 1357<col> 1358<col> 1359</colgroup> 1360<thead><tr> 1361<th> 1362 <p> 1363 If a thread has acquired the... 1364 </p> 1365 </th> 1366<th> 1367 <p> 1368 Other threads can acquire... 1369 </p> 1370 </th> 1371</tr></thead> 1372<tbody> 1373<tr> 1374<td> 1375 <p> 1376 Sharable lock 1377 </p> 1378 </td> 1379<td> 1380 <p> 1381 many sharable locks and 1 upgradable lock 1382 </p> 1383 </td> 1384</tr> 1385<tr> 1386<td> 1387 <p> 1388 Upgradable lock 1389 </p> 1390 </td> 1391<td> 1392 <p> 1393 many sharable locks 1394 </p> 1395 </td> 1396</tr> 1397<tr> 1398<td> 1399 <p> 1400 Exclusive lock 1401 </p> 1402 </td> 1403<td> 1404 <p> 1405 no locks 1406 </p> 1407 </td> 1408</tr> 1409</tbody> 1410</table></div> 1411</div> 1412<br class="table-break"> 1413</div> 1414<div class="section"> 1415<div class="titlepage"><div><div><h4 class="title"> 1416<a name="interprocess.synchronization_mechanisms.sharable_upgradable_mutexes.upgradable_transitions"></a><a class="link" href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.sharable_upgradable_mutexes.upgradable_transitions" title="Lock transitions for Upgradable Mutex">Lock 1417 transitions for Upgradable Mutex</a> 1418</h4></div></div></div> 1419<p> 1420 A sharable mutex has no option to change the acquired lock for another 1421 lock atomically. 1422 </p> 1423<p> 1424 On the other hand, for an upgradable mutex, a thread that has acquired 1425 a lock can try to acquire another lock type atomically. All lock transitions 1426 are not guaranteed to succeed. Even if a transition is guaranteed to succeed, 1427 some transitions will block the thread waiting until other threads release 1428 the sharable locks. <span class="bold"><strong>Atomically</strong></span> means that 1429 no other thread will acquire an Upgradable or Exclusive lock in the transition, 1430 <span class="bold"><strong>so data is guaranteed to remain unchanged</strong></span>: 1431 </p> 1432<div class="table"> 1433<a name="interprocess.synchronization_mechanisms.sharable_upgradable_mutexes.upgradable_transitions.transition_possibilities_for_an_upgradable_mutex"></a><p class="title"><b>Table 18.7. Transition Possibilities for an Upgradable Mutex</b></p> 1434<div class="table-contents"><table class="table" summary="Transition Possibilities for an Upgradable Mutex"> 1435<colgroup> 1436<col> 1437<col> 1438</colgroup> 1439<thead><tr> 1440<th> 1441 <p> 1442 If a thread has acquired the... 1443 </p> 1444 </th> 1445<th> 1446 <p> 1447 It can atomically release the previous lock and... 1448 </p> 1449 </th> 1450</tr></thead> 1451<tbody> 1452<tr> 1453<td> 1454 <p> 1455 Sharable lock 1456 </p> 1457 </td> 1458<td> 1459 <p> 1460 try to obtain (not guaranteed) immediately the Exclusive lock 1461 if no other thread has exclusive or upgrable lock 1462 </p> 1463 </td> 1464</tr> 1465<tr> 1466<td> 1467 <p> 1468 Sharable lock 1469 </p> 1470 </td> 1471<td> 1472 <p> 1473 try to obtain (not guaranteed) immediately the Upgradable lock 1474 if no other thread has exclusive or upgrable lock 1475 </p> 1476 </td> 1477</tr> 1478<tr> 1479<td> 1480 <p> 1481 Upgradable lock 1482 </p> 1483 </td> 1484<td> 1485 <p> 1486 obtain the Exclusive lock when all sharable locks are released 1487 </p> 1488 </td> 1489</tr> 1490<tr> 1491<td> 1492 <p> 1493 Upgradable lock 1494 </p> 1495 </td> 1496<td> 1497 <p> 1498 obtain the Sharable lock immediately 1499 </p> 1500 </td> 1501</tr> 1502<tr> 1503<td> 1504 <p> 1505 Exclusive lock 1506 </p> 1507 </td> 1508<td> 1509 <p> 1510 obtain the Upgradable lock immediately 1511 </p> 1512 </td> 1513</tr> 1514<tr> 1515<td> 1516 <p> 1517 Exclusive lock 1518 </p> 1519 </td> 1520<td> 1521 <p> 1522 obtain the Sharable lock immediately 1523 </p> 1524 </td> 1525</tr> 1526</tbody> 1527</table></div> 1528</div> 1529<br class="table-break"><p> 1530 As we can see, an upgradable mutex is a powerful synchronization utility 1531 that can improve the concurrency. However, if most of the time we have 1532 to modify the data, or the synchronized code section is very short, it's 1533 more efficient to use a plain mutex, since it has less overhead. Upgradable 1534 lock shines when the synchronized code section is bigger and there are 1535 more readers than modifiers. 1536 </p> 1537</div> 1538<div class="section"> 1539<div class="titlepage"><div><div><h4 class="title"> 1540<a name="interprocess.synchronization_mechanisms.sharable_upgradable_mutexes.sharable_upgradable_mutexes_operations"></a><a class="link" href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.sharable_upgradable_mutexes.sharable_upgradable_mutexes_operations" title="Upgradable Mutex Operations">Upgradable 1541 Mutex Operations</a> 1542</h4></div></div></div> 1543<div class="toc"><dl class="toc"> 1544<dt><span class="section"><a href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.sharable_upgradable_mutexes.sharable_upgradable_mutexes_operations.sharable_upgradable_mutexes_operations_exclusive">Exclusive 1545 Locking (Sharable & Upgradable Mutexes)</a></span></dt> 1546<dt><span class="section"><a href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.sharable_upgradable_mutexes.sharable_upgradable_mutexes_operations.sharable_upgradable_mutexes_operations_sharable">Sharable 1547 Locking (Sharable & Upgradable Mutexes)</a></span></dt> 1548<dt><span class="section"><a href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.sharable_upgradable_mutexes.sharable_upgradable_mutexes_operations.upgradable_mutexes_operations_upgradable">Upgradable 1549 Locking (Upgradable Mutex only)</a></span></dt> 1550<dt><span class="section"><a href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.sharable_upgradable_mutexes.sharable_upgradable_mutexes_operations.upgradable_mutexes_operations_demotions">Demotions 1551 (Upgradable Mutex only)</a></span></dt> 1552<dt><span class="section"><a href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.sharable_upgradable_mutexes.sharable_upgradable_mutexes_operations.upgradable_mutexes_operations_promotions">Promotions 1553 (Upgradable Mutex only)</a></span></dt> 1554</dl></div> 1555<p> 1556 All the upgradable mutex types from <span class="bold"><strong>Boost.Interprocess</strong></span> 1557 implement the following operations: 1558 </p> 1559<div class="section"> 1560<div class="titlepage"><div><div><h5 class="title"> 1561<a name="interprocess.synchronization_mechanisms.sharable_upgradable_mutexes.sharable_upgradable_mutexes_operations.sharable_upgradable_mutexes_operations_exclusive"></a><a class="link" href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.sharable_upgradable_mutexes.sharable_upgradable_mutexes_operations.sharable_upgradable_mutexes_operations_exclusive" title="Exclusive Locking (Sharable & Upgradable Mutexes)">Exclusive 1562 Locking (Sharable & Upgradable Mutexes)</a> 1563</h5></div></div></div> 1564<div class="blurb"> 1565<div class="titlepage"><div><div><p class="title"><b></b></p></div></div></div> 1566<p> 1567 <span class="emphasis"><em><span class="bold"><strong>void lock()</strong></span></em></span> 1568 </p> 1569</div> 1570<p> 1571 <span class="bold"><strong>Effects:</strong></span> The calling thread tries to 1572 obtain exclusive ownership of the mutex, and if another thread has any 1573 ownership of the mutex (exclusive or other), it waits until it can obtain 1574 the ownership. 1575 </p> 1576<p> 1577 <span class="bold"><strong>Throws:</strong></span> <span class="bold"><strong>interprocess_exception</strong></span> 1578 on error. 1579 </p> 1580<div class="blurb"> 1581<div class="titlepage"><div><div><p class="title"><b></b></p></div></div></div> 1582<p> 1583 <span class="emphasis"><em><span class="bold"><strong>bool try_lock()</strong></span></em></span> 1584 </p> 1585</div> 1586<p> 1587 <span class="bold"><strong>Effects:</strong></span> The calling thread tries to 1588 acquire exclusive ownership of the mutex without waiting. If no other 1589 thread has any ownership of the mutex (exclusive or other) this succeeds. 1590 </p> 1591<p> 1592 <span class="bold"><strong>Returns:</strong></span> If it can acquire exclusive 1593 ownership immediately returns true. If it has to wait, returns false. 1594 </p> 1595<p> 1596 <span class="bold"><strong>Throws:</strong></span> <span class="bold"><strong>interprocess_exception</strong></span> 1597 on error. 1598 </p> 1599<div class="blurb"> 1600<div class="titlepage"><div><div><p class="title"><b></b></p></div></div></div> 1601<p> 1602 <span class="emphasis"><em><span class="bold"><strong>bool timed_lock(const boost::posix_time::ptime 1603 &abs_time)</strong></span></em></span> 1604 </p> 1605</div> 1606<p> 1607 <span class="bold"><strong>Effects:</strong></span> The calling thread tries to 1608 acquire exclusive ownership of the mutex waiting if necessary until no 1609 other thread has any ownership of the mutex (exclusive or other) or abs_time 1610 is reached. 1611 </p> 1612<p> 1613 <span class="bold"><strong>Returns:</strong></span> If acquires exclusive ownership, 1614 returns true. Otherwise returns false. 1615 </p> 1616<p> 1617 <span class="bold"><strong>Throws:</strong></span> <span class="bold"><strong>interprocess_exception</strong></span> 1618 on error. 1619 </p> 1620<div class="blurb"> 1621<div class="titlepage"><div><div><p class="title"><b></b></p></div></div></div> 1622<p> 1623 <span class="emphasis"><em><span class="bold"><strong>void unlock()</strong></span></em></span> 1624 </p> 1625</div> 1626<p> 1627 <span class="bold"><strong>Precondition:</strong></span> The thread must have exclusive 1628 ownership of the mutex. 1629 </p> 1630<p> 1631 <span class="bold"><strong>Effects:</strong></span> The calling thread releases 1632 the exclusive ownership of the mutex. 1633 </p> 1634<p> 1635 <span class="bold"><strong>Throws:</strong></span> An exception derived from <span class="bold"><strong>interprocess_exception</strong></span> on error. 1636 </p> 1637</div> 1638<div class="section"> 1639<div class="titlepage"><div><div><h5 class="title"> 1640<a name="interprocess.synchronization_mechanisms.sharable_upgradable_mutexes.sharable_upgradable_mutexes_operations.sharable_upgradable_mutexes_operations_sharable"></a><a class="link" href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.sharable_upgradable_mutexes.sharable_upgradable_mutexes_operations.sharable_upgradable_mutexes_operations_sharable" title="Sharable Locking (Sharable & Upgradable Mutexes)">Sharable 1641 Locking (Sharable & Upgradable Mutexes)</a> 1642</h5></div></div></div> 1643<div class="blurb"> 1644<div class="titlepage"><div><div><p class="title"><b></b></p></div></div></div> 1645<p> 1646 <span class="emphasis"><em><span class="bold"><strong>void lock_sharable()</strong></span></em></span> 1647 </p> 1648</div> 1649<p> 1650 <span class="bold"><strong>Effects:</strong></span> The calling thread tries to 1651 obtain sharable ownership of the mutex, and if another thread has exclusive 1652 ownership of the mutex, waits until it can obtain the ownership. 1653 </p> 1654<p> 1655 <span class="bold"><strong>Throws:</strong></span> <span class="bold"><strong>interprocess_exception</strong></span> 1656 on error. 1657 </p> 1658<div class="blurb"> 1659<div class="titlepage"><div><div><p class="title"><b></b></p></div></div></div> 1660<p> 1661 <span class="emphasis"><em><span class="bold"><strong>bool try_lock_sharable()</strong></span></em></span> 1662 </p> 1663</div> 1664<p> 1665 <span class="bold"><strong>Effects:</strong></span> The calling thread tries to 1666 acquire sharable ownership of the mutex without waiting. If no other 1667 thread has exclusive ownership of the mutex this succeeds. 1668 </p> 1669<p> 1670 <span class="bold"><strong>Returns:</strong></span> If it can acquire sharable 1671 ownership immediately returns true. If it has to wait, returns false. 1672 </p> 1673<p> 1674 <span class="bold"><strong>Throws:</strong></span> <span class="bold"><strong>interprocess_exception</strong></span> 1675 on error. 1676 </p> 1677<div class="blurb"> 1678<div class="titlepage"><div><div><p class="title"><b></b></p></div></div></div> 1679<p> 1680 <span class="emphasis"><em><span class="bold"><strong>bool timed_lock_sharable(const boost::posix_time::ptime 1681 &abs_time)</strong></span></em></span> 1682 </p> 1683</div> 1684<p> 1685 <span class="bold"><strong>Effects:</strong></span> The calling thread tries to 1686 acquire sharable ownership of the mutex waiting if necessary until no 1687 other thread has exclusive ownership of the mutex or abs_time is reached. 1688 </p> 1689<p> 1690 <span class="bold"><strong>Returns:</strong></span> If acquires sharable ownership, 1691 returns true. Otherwise returns false. 1692 </p> 1693<p> 1694 <span class="bold"><strong>Throws:</strong></span> <span class="bold"><strong>interprocess_exception</strong></span> 1695 on error. 1696 </p> 1697<div class="blurb"> 1698<div class="titlepage"><div><div><p class="title"><b></b></p></div></div></div> 1699<p> 1700 <span class="emphasis"><em><span class="bold"><strong>void unlock_sharable()</strong></span></em></span> 1701 </p> 1702</div> 1703<p> 1704 <span class="bold"><strong>Precondition:</strong></span> The thread must have sharable 1705 ownership of the mutex. 1706 </p> 1707<p> 1708 <span class="bold"><strong>Effects:</strong></span> The calling thread releases 1709 the sharable ownership of the mutex. 1710 </p> 1711<p> 1712 <span class="bold"><strong>Throws:</strong></span> An exception derived from <span class="bold"><strong>interprocess_exception</strong></span> on error. 1713 </p> 1714</div> 1715<div class="section"> 1716<div class="titlepage"><div><div><h5 class="title"> 1717<a name="interprocess.synchronization_mechanisms.sharable_upgradable_mutexes.sharable_upgradable_mutexes_operations.upgradable_mutexes_operations_upgradable"></a><a class="link" href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.sharable_upgradable_mutexes.sharable_upgradable_mutexes_operations.upgradable_mutexes_operations_upgradable" title="Upgradable Locking (Upgradable Mutex only)">Upgradable 1718 Locking (Upgradable Mutex only)</a> 1719</h5></div></div></div> 1720<div class="blurb"> 1721<div class="titlepage"><div><div><p class="title"><b></b></p></div></div></div> 1722<p> 1723 <span class="emphasis"><em><span class="bold"><strong>void lock_upgradable()</strong></span></em></span> 1724 </p> 1725</div> 1726<p> 1727 <span class="bold"><strong>Effects:</strong></span> The calling thread tries to 1728 obtain upgradable ownership of the mutex, and if another thread has exclusive 1729 or upgradable ownership of the mutex, waits until it can obtain the ownership. 1730 </p> 1731<p> 1732 <span class="bold"><strong>Throws:</strong></span> <span class="bold"><strong>interprocess_exception</strong></span> 1733 on error. 1734 </p> 1735<div class="blurb"> 1736<div class="titlepage"><div><div><p class="title"><b></b></p></div></div></div> 1737<p> 1738 <span class="emphasis"><em><span class="bold"><strong>bool try_lock_upgradable()</strong></span></em></span> 1739 </p> 1740</div> 1741<p> 1742 <span class="bold"><strong>Effects:</strong></span> The calling thread tries to 1743 acquire upgradable ownership of the mutex without waiting. If no other 1744 thread has exclusive or upgradable ownership of the mutex this succeeds. 1745 </p> 1746<p> 1747 <span class="bold"><strong>Returns:</strong></span> If it can acquire upgradable 1748 ownership immediately returns true. If it has to wait, returns false. 1749 </p> 1750<p> 1751 <span class="bold"><strong>Throws:</strong></span> <span class="bold"><strong>interprocess_exception</strong></span> 1752 on error. 1753 </p> 1754<div class="blurb"> 1755<div class="titlepage"><div><div><p class="title"><b></b></p></div></div></div> 1756<p> 1757 <span class="emphasis"><em><span class="bold"><strong>bool timed_lock_upgradable(const boost::posix_time::ptime 1758 &abs_time)</strong></span></em></span> 1759 </p> 1760</div> 1761<p> 1762 <span class="bold"><strong>Effects:</strong></span> The calling thread tries to 1763 acquire upgradable ownership of the mutex waiting if necessary until 1764 no other thread has exclusive ownership of the mutex or abs_time is reached. 1765 </p> 1766<p> 1767 <span class="bold"><strong>Returns:</strong></span> If acquires upgradable ownership, 1768 returns true. Otherwise returns false. 1769 </p> 1770<p> 1771 <span class="bold"><strong>Throws:</strong></span> <span class="bold"><strong>interprocess_exception</strong></span> 1772 on error. 1773 </p> 1774<div class="blurb"> 1775<div class="titlepage"><div><div><p class="title"><b></b></p></div></div></div> 1776<p> 1777 <span class="emphasis"><em><span class="bold"><strong>void unlock_upgradable()</strong></span></em></span> 1778 </p> 1779</div> 1780<p> 1781 <span class="bold"><strong>Precondition:</strong></span> The thread must have upgradable 1782 ownership of the mutex. 1783 </p> 1784<p> 1785 <span class="bold"><strong>Effects:</strong></span> The calling thread releases 1786 the upgradable ownership of the mutex. 1787 </p> 1788<p> 1789 <span class="bold"><strong>Throws:</strong></span> An exception derived from <span class="bold"><strong>interprocess_exception</strong></span> on error. 1790 </p> 1791</div> 1792<div class="section"> 1793<div class="titlepage"><div><div><h5 class="title"> 1794<a name="interprocess.synchronization_mechanisms.sharable_upgradable_mutexes.sharable_upgradable_mutexes_operations.upgradable_mutexes_operations_demotions"></a><a class="link" href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.sharable_upgradable_mutexes.sharable_upgradable_mutexes_operations.upgradable_mutexes_operations_demotions" title="Demotions (Upgradable Mutex only)">Demotions 1795 (Upgradable Mutex only)</a> 1796</h5></div></div></div> 1797<div class="blurb"> 1798<div class="titlepage"><div><div><p class="title"><b></b></p></div></div></div> 1799<p> 1800 <span class="emphasis"><em><span class="bold"><strong>void unlock_and_lock_upgradable()</strong></span></em></span> 1801 </p> 1802</div> 1803<p> 1804 <span class="bold"><strong>Precondition:</strong></span> The thread must have exclusive 1805 ownership of the mutex. 1806 </p> 1807<p> 1808 <span class="bold"><strong>Effects:</strong></span> The thread atomically releases 1809 exclusive ownership and acquires upgradable ownership. This operation 1810 is non-blocking. 1811 </p> 1812<p> 1813 <span class="bold"><strong>Throws:</strong></span> An exception derived from <span class="bold"><strong>interprocess_exception</strong></span> on error. 1814 </p> 1815<div class="blurb"> 1816<div class="titlepage"><div><div><p class="title"><b></b></p></div></div></div> 1817<p> 1818 <span class="emphasis"><em><span class="bold"><strong>void unlock_and_lock_sharable()</strong></span></em></span> 1819 </p> 1820</div> 1821<p> 1822 <span class="bold"><strong>Precondition:</strong></span> The thread must have exclusive 1823 ownership of the mutex. 1824 </p> 1825<p> 1826 <span class="bold"><strong>Effects:</strong></span> The thread atomically releases 1827 exclusive ownership and acquires sharable ownership. This operation is 1828 non-blocking. 1829 </p> 1830<p> 1831 <span class="bold"><strong>Throws:</strong></span> An exception derived from <span class="bold"><strong>interprocess_exception</strong></span> on error. 1832 </p> 1833<div class="blurb"> 1834<div class="titlepage"><div><div><p class="title"><b></b></p></div></div></div> 1835<p> 1836 <span class="emphasis"><em><span class="bold"><strong>void unlock_upgradable_and_lock_sharable()</strong></span></em></span> 1837 </p> 1838</div> 1839<p> 1840 <span class="bold"><strong>Precondition:</strong></span> The thread must have upgradable 1841 ownership of the mutex. 1842 </p> 1843<p> 1844 <span class="bold"><strong>Effects:</strong></span> The thread atomically releases 1845 upgradable ownership and acquires sharable ownership. This operation 1846 is non-blocking. 1847 </p> 1848<p> 1849 <span class="bold"><strong>Throws:</strong></span> An exception derived from <span class="bold"><strong>interprocess_exception</strong></span> on error. 1850 </p> 1851</div> 1852<div class="section"> 1853<div class="titlepage"><div><div><h5 class="title"> 1854<a name="interprocess.synchronization_mechanisms.sharable_upgradable_mutexes.sharable_upgradable_mutexes_operations.upgradable_mutexes_operations_promotions"></a><a class="link" href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.sharable_upgradable_mutexes.sharable_upgradable_mutexes_operations.upgradable_mutexes_operations_promotions" title="Promotions (Upgradable Mutex only)">Promotions 1855 (Upgradable Mutex only)</a> 1856</h5></div></div></div> 1857<div class="blurb"> 1858<div class="titlepage"><div><div><p class="title"><b></b></p></div></div></div> 1859<p> 1860 <span class="emphasis"><em><span class="bold"><strong>void unlock_upgradable_and_lock()</strong></span></em></span> 1861 </p> 1862</div> 1863<p> 1864 <span class="bold"><strong>Precondition:</strong></span> The thread must have upgradable 1865 ownership of the mutex. 1866 </p> 1867<p> 1868 <span class="bold"><strong>Effects:</strong></span> The thread atomically releases 1869 upgradable ownership and acquires exclusive ownership. This operation 1870 will block until all threads with sharable ownership release it. 1871 </p> 1872<p> 1873 <span class="bold"><strong>Throws:</strong></span> An exception derived from <span class="bold"><strong>interprocess_exception</strong></span> on error. 1874 </p> 1875<div class="blurb"> 1876<div class="titlepage"><div><div><p class="title"><b></b></p></div></div></div> 1877<p> 1878 <span class="emphasis"><em><span class="bold"><strong>bool try_unlock_upgradable_and_lock()</strong></span></em></span> 1879 </p> 1880</div> 1881<p> 1882 <span class="bold"><strong>Precondition:</strong></span> The thread must have upgradable 1883 ownership of the mutex. 1884 </p> 1885<p> 1886 <span class="bold"><strong>Effects:</strong></span> The thread atomically releases 1887 upgradable ownership and tries to acquire exclusive ownership. This operation 1888 will fail if there are threads with sharable ownership, but it will maintain 1889 upgradable ownership. 1890 </p> 1891<p> 1892 <span class="bold"><strong>Returns:</strong></span> If acquires exclusive ownership, 1893 returns true. Otherwise returns false. 1894 </p> 1895<p> 1896 <span class="bold"><strong>Throws:</strong></span> An exception derived from <span class="bold"><strong>interprocess_exception</strong></span> on error. 1897 </p> 1898<div class="blurb"> 1899<div class="titlepage"><div><div><p class="title"><b></b></p></div></div></div> 1900<p> 1901 <span class="emphasis"><em><span class="bold"><strong>bool timed_unlock_upgradable_and_lock(const 1902 boost::posix_time::ptime &abs_time)</strong></span></em></span> 1903 </p> 1904</div> 1905<p> 1906 <span class="bold"><strong>Precondition:</strong></span> The thread must have upgradable 1907 ownership of the mutex. 1908 </p> 1909<p> 1910 <span class="bold"><strong>Effects:</strong></span> The thread atomically releases 1911 upgradable ownership and tries to acquire exclusive ownership, waiting 1912 if necessary until abs_time. This operation will fail if there are threads 1913 with sharable ownership or timeout reaches, but it will maintain upgradable 1914 ownership. 1915 </p> 1916<p> 1917 <span class="bold"><strong>Returns:</strong></span> If acquires exclusive ownership, 1918 returns true. Otherwise returns false. 1919 </p> 1920<p> 1921 <span class="bold"><strong>Throws:</strong></span> An exception derived from <span class="bold"><strong>interprocess_exception</strong></span> on error. 1922 </p> 1923<div class="blurb"> 1924<div class="titlepage"><div><div><p class="title"><b></b></p></div></div></div> 1925<p> 1926 <span class="emphasis"><em><span class="bold"><strong>bool try_unlock_sharable_and_lock()</strong></span></em></span> 1927 </p> 1928</div> 1929<p> 1930 <span class="bold"><strong>Precondition:</strong></span> The thread must have sharable 1931 ownership of the mutex. 1932 </p> 1933<p> 1934 <span class="bold"><strong>Effects:</strong></span> The thread atomically releases 1935 sharable ownership and tries to acquire exclusive ownership. This operation 1936 will fail if there are threads with sharable or upgradable ownership, 1937 but it will maintain sharable ownership. 1938 </p> 1939<p> 1940 <span class="bold"><strong>Returns:</strong></span> If acquires exclusive ownership, 1941 returns true. Otherwise returns false. 1942 </p> 1943<p> 1944 <span class="bold"><strong>Throws:</strong></span> An exception derived from <span class="bold"><strong>interprocess_exception</strong></span> on error. 1945 </p> 1946<div class="blurb"> 1947<div class="titlepage"><div><div><p class="title"><b></b></p></div></div></div> 1948<p> 1949 <span class="emphasis"><em><span class="bold"><strong>bool try_unlock_sharable_and_lock_upgradable()</strong></span></em></span> 1950 </p> 1951</div> 1952<p> 1953 <span class="bold"><strong>Precondition:</strong></span> The thread must have sharable 1954 ownership of the mutex. 1955 </p> 1956<p> 1957 <span class="bold"><strong>Effects:</strong></span> The thread atomically releases 1958 sharable ownership and tries to acquire upgradable ownership. This operation 1959 will fail if there are threads with sharable or upgradable ownership, 1960 but it will maintain sharable ownership. 1961 </p> 1962<p> 1963 <span class="bold"><strong>Returns:</strong></span> If acquires upgradable ownership, 1964 returns true. Otherwise returns false. 1965 </p> 1966<p> 1967 <span class="bold"><strong>Throws:</strong></span> An exception derived from <span class="bold"><strong>interprocess_exception</strong></span> on error. 1968 </p> 1969<div class="important"><table border="0" summary="Important"> 1970<tr> 1971<td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="../../../doc/src/images/important.png"></td> 1972<th align="left">Important</th> 1973</tr> 1974<tr><td align="left" valign="top"><p> 1975 <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">posix_time</span><span class="special">::</span><span class="identifier">ptime</span></code> absolute time points used by 1976 Boost.Interprocess synchronization mechanisms are UTC time points, 1977 not local time points 1978 </p></td></tr> 1979</table></div> 1980</div> 1981</div> 1982<div class="section"> 1983<div class="titlepage"><div><div><h4 class="title"> 1984<a name="interprocess.synchronization_mechanisms.sharable_upgradable_mutexes.sharable_upgradable_mutexes_mutex_interprocess_mutexes"></a><a class="link" href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.sharable_upgradable_mutexes.sharable_upgradable_mutexes_mutex_interprocess_mutexes" title="Boost.Interprocess Sharable & Upgradable Mutex Types And Headers">Boost.Interprocess 1985 Sharable & Upgradable Mutex Types And Headers</a> 1986</h4></div></div></div> 1987<p> 1988 Boost.Interprocess offers the following sharable mutex types: 1989 </p> 1990<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">interprocess</span><span class="special">/</span><span class="identifier">sync</span><span class="special">/</span><span class="identifier">interprocess_sharable_mutex</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 1991</pre> 1992<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> 1993 <code class="computeroutput"><a class="link" href="../boost/interprocess/interpro_idm45304010315808.html" title="Class interprocess_sharable_mutex">interprocess_sharable_mutex</a></code>: 1994 A non-recursive, anonymous sharable mutex that can be placed in shared 1995 memory or memory mapped files. 1996 </li></ul></div> 1997<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">interprocess</span><span class="special">/</span><span class="identifier">sync</span><span class="special">/</span><span class="identifier">named_sharable_mutex</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 1998</pre> 1999<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> 2000 <code class="computeroutput"><a class="link" href="../boost/interprocess/named_sharable_mutex.html" title="Class named_sharable_mutex">named_sharable_mutex</a></code>: 2001 A non-recursive, named sharable mutex. 2002 </li></ul></div> 2003<p> 2004 Boost.Interprocess offers the following upgradable mutex types: 2005 </p> 2006<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">interprocess</span><span class="special">/</span><span class="identifier">sync</span><span class="special">/</span><span class="identifier">interprocess_upgradable_mutex</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 2007</pre> 2008<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> 2009 <code class="computeroutput"><a class="link" href="../boost/interprocess/interpro_idm45304010284992.html" title="Class interprocess_upgradable_mutex">interprocess_upgradable_mutex</a></code>: 2010 A non-recursive, anonymous upgradable mutex that can be placed in shared 2011 memory or memory mapped files. 2012 </li></ul></div> 2013<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">interprocess</span><span class="special">/</span><span class="identifier">sync</span><span class="special">/</span><span class="identifier">named_upgradable_mutex</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 2014</pre> 2015<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> 2016 <code class="computeroutput"><a class="link" href="../boost/interprocess/named_upgradable_mutex.html" title="Class named_upgradable_mutex">named_upgradable_mutex</a></code>: 2017 A non-recursive, named upgradable mutex. 2018 </li></ul></div> 2019</div> 2020<div class="section"> 2021<div class="titlepage"><div><div><h4 class="title"> 2022<a name="interprocess.synchronization_mechanisms.sharable_upgradable_mutexes.sharable_upgradable_locks"></a><a class="link" href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.sharable_upgradable_mutexes.sharable_upgradable_locks" title="Sharable Lock And Upgradable Lock">Sharable 2023 Lock And Upgradable Lock</a> 2024</h4></div></div></div> 2025<div class="toc"><dl class="toc"><dt><span class="section"><a href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.sharable_upgradable_mutexes.sharable_upgradable_locks.upgradable_mutexes_lock_types">Sharable 2026 Lock And Upgradable Lock Headers</a></span></dt></dl></div> 2027<p> 2028 As with plain mutexes, it's important to release the acquired lock even 2029 in the presence of exceptions. <span class="bold"><strong>Boost.Interprocess</strong></span> 2030 mutexes are best used with the <code class="computeroutput"><a class="link" href="../boost/interprocess/scoped_lock.html" title="Class template scoped_lock">scoped_lock</a></code> 2031 utility, and this class only offers exclusive locking. 2032 </p> 2033<p> 2034 As we have sharable locking and upgradable locking with upgradable mutexes, 2035 we have two new utilities: <code class="computeroutput"><a class="link" href="../boost/interprocess/sharable_lock.html" title="Class template sharable_lock">sharable_lock</a></code> 2036 and <code class="computeroutput"><a class="link" href="../boost/interprocess/upgradable_lock.html" title="Class template upgradable_lock">upgradable_lock</a></code>. 2037 Both classes are similar to <code class="computeroutput"><span class="identifier">scoped_lock</span></code> 2038 but <code class="computeroutput"><span class="identifier">sharable_lock</span></code> acquires 2039 the sharable lock in the constructor and <code class="computeroutput"><span class="identifier">upgradable_lock</span></code> 2040 acquires the upgradable lock in the constructor. 2041 </p> 2042<p> 2043 These two utilities can be use with any synchronization object that offers 2044 the needed operations. For example, a user defined mutex type with no upgradable 2045 locking features can use <code class="computeroutput"><span class="identifier">sharable_lock</span></code> 2046 if the synchronization object offers <span class="bold"><strong>lock_sharable()</strong></span> 2047 and <span class="bold"><strong>unlock_sharable()</strong></span> operations: 2048 </p> 2049<div class="section"> 2050<div class="titlepage"><div><div><h5 class="title"> 2051<a name="interprocess.synchronization_mechanisms.sharable_upgradable_mutexes.sharable_upgradable_locks.upgradable_mutexes_lock_types"></a><a class="link" href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.sharable_upgradable_mutexes.sharable_upgradable_locks.upgradable_mutexes_lock_types" title="Sharable Lock And Upgradable Lock Headers">Sharable 2052 Lock And Upgradable Lock Headers</a> 2053</h5></div></div></div> 2054<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">interprocess</span><span class="special">/</span><span class="identifier">sync</span><span class="special">/</span><span class="identifier">sharable_lock</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 2055</pre> 2056<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">interprocess</span><span class="special">/</span><span class="identifier">sync</span><span class="special">/</span><span class="identifier">upgradable_lock</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 2057</pre> 2058</div> 2059<p> 2060 <code class="computeroutput"><span class="identifier">sharable_lock</span></code> calls <span class="bold"><strong>unlock_sharable()</strong></span> in its destructor, and <code class="computeroutput"><span class="identifier">upgradable_lock</span></code> calls <span class="bold"><strong>unlock_upgradable()</strong></span> 2061 in its destructor, so the upgradable mutex is always unlocked when an exception 2062 occurs. 2063 </p> 2064<pre class="programlisting"><span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">;</span> 2065 2066<span class="identifier">SharableOrUpgradableMutex</span> <span class="identifier">sh_or_up_mutex</span><span class="special">;</span> 2067 2068<span class="special">{</span> 2069 <span class="comment">//This will call lock_sharable()</span> 2070 <span class="identifier">sharable_lock</span><span class="special"><</span><span class="identifier">SharableOrUpgradableMutex</span><span class="special">></span> <span class="identifier">lock</span><span class="special">(</span><span class="identifier">sh_or_up_mutex</span><span class="special">);</span> 2071 2072 <span class="comment">//Some code</span> 2073 2074 <span class="comment">//The mutex will be unlocked here</span> 2075<span class="special">}</span> 2076 2077<span class="special">{</span> 2078 <span class="comment">//This won't lock the mutex()</span> 2079 <span class="identifier">sharable_lock</span><span class="special"><</span><span class="identifier">SharableOrUpgradableMutex</span><span class="special">></span> <span class="identifier">lock</span><span class="special">(</span><span class="identifier">sh_or_up_mutex</span><span class="special">,</span> <span class="identifier">defer_lock</span><span class="special">);</span> 2080 2081 <span class="comment">//Lock it on demand. This will call lock_sharable()</span> 2082 <span class="identifier">lock</span><span class="special">.</span><span class="identifier">lock</span><span class="special">();</span> 2083 2084 <span class="comment">//Some code</span> 2085 2086 <span class="comment">//The mutex will be unlocked here</span> 2087<span class="special">}</span> 2088 2089<span class="special">{</span> 2090 <span class="comment">//This will call try_lock_sharable()</span> 2091 <span class="identifier">sharable_lock</span><span class="special"><</span><span class="identifier">SharableOrUpgradableMutex</span><span class="special">></span> <span class="identifier">lock</span><span class="special">(</span><span class="identifier">sh_or_up_mutex</span><span class="special">,</span> <span class="identifier">try_to_lock</span><span class="special">);</span> 2092 2093 <span class="comment">//Check if the mutex has been successfully locked</span> 2094 <span class="keyword">if</span><span class="special">(</span><span class="identifier">lock</span><span class="special">){</span> 2095 <span class="comment">//Some code</span> 2096 <span class="special">}</span> 2097 <span class="comment">//If the mutex was locked it will be unlocked</span> 2098<span class="special">}</span> 2099 2100<span class="special">{</span> 2101 <span class="identifier">boost</span><span class="special">::</span><span class="identifier">posix_time</span><span class="special">::</span><span class="identifier">ptime</span> <span class="identifier">abs_time</span> <span class="special">=</span> <span class="special">...</span> 2102 2103 <span class="comment">//This will call timed_lock_sharable()</span> 2104 <span class="identifier">scoped_lock</span><span class="special"><</span><span class="identifier">SharableOrUpgradableMutex</span><span class="special">></span> <span class="identifier">lock</span><span class="special">(</span><span class="identifier">sh_or_up_mutex</span><span class="special">,</span> <span class="identifier">abs_time</span><span class="special">);</span> 2105 2106 <span class="comment">//Check if the mutex has been successfully locked</span> 2107 <span class="keyword">if</span><span class="special">(</span><span class="identifier">lock</span><span class="special">){</span> 2108 <span class="comment">//Some code</span> 2109 <span class="special">}</span> 2110 <span class="comment">//If the mutex was locked it will be unlocked</span> 2111<span class="special">}</span> 2112 2113<span class="identifier">UpgradableMutex</span> <span class="identifier">up_mutex</span><span class="special">;</span> 2114 2115<span class="special">{</span> 2116 <span class="comment">//This will call lock_upgradable()</span> 2117 <span class="identifier">upgradable_lock</span><span class="special"><</span><span class="identifier">UpgradableMutex</span><span class="special">></span> <span class="identifier">lock</span><span class="special">(</span><span class="identifier">up_mutex</span><span class="special">);</span> 2118 2119 <span class="comment">//Some code</span> 2120 2121 <span class="comment">//The mutex will be unlocked here</span> 2122<span class="special">}</span> 2123 2124<span class="special">{</span> 2125 <span class="comment">//This won't lock the mutex()</span> 2126 <span class="identifier">upgradable_lock</span><span class="special"><</span><span class="identifier">UpgradableMutex</span><span class="special">></span> <span class="identifier">lock</span><span class="special">(</span><span class="identifier">up_mutex</span><span class="special">,</span> <span class="identifier">defer_lock</span><span class="special">);</span> 2127 2128 <span class="comment">//Lock it on demand. This will call lock_upgradable()</span> 2129 <span class="identifier">lock</span><span class="special">.</span><span class="identifier">lock</span><span class="special">();</span> 2130 2131 <span class="comment">//Some code</span> 2132 2133 <span class="comment">//The mutex will be unlocked here</span> 2134<span class="special">}</span> 2135 2136<span class="special">{</span> 2137 <span class="comment">//This will call try_lock_upgradable()</span> 2138 <span class="identifier">upgradable_lock</span><span class="special"><</span><span class="identifier">UpgradableMutex</span><span class="special">></span> <span class="identifier">lock</span><span class="special">(</span><span class="identifier">up_mutex</span><span class="special">,</span> <span class="identifier">try_to_lock</span><span class="special">);</span> 2139 2140 <span class="comment">//Check if the mutex has been successfully locked</span> 2141 <span class="keyword">if</span><span class="special">(</span><span class="identifier">lock</span><span class="special">){</span> 2142 <span class="comment">//Some code</span> 2143 <span class="special">}</span> 2144 <span class="comment">//If the mutex was locked it will be unlocked</span> 2145<span class="special">}</span> 2146 2147<span class="special">{</span> 2148 <span class="identifier">boost</span><span class="special">::</span><span class="identifier">posix_time</span><span class="special">::</span><span class="identifier">ptime</span> <span class="identifier">abs_time</span> <span class="special">=</span> <span class="special">...</span> 2149 2150 <span class="comment">//This will call timed_lock_upgradable()</span> 2151 <span class="identifier">scoped_lock</span><span class="special"><</span><span class="identifier">UpgradableMutex</span><span class="special">></span> <span class="identifier">lock</span><span class="special">(</span><span class="identifier">up_mutex</span><span class="special">,</span> <span class="identifier">abs_time</span><span class="special">);</span> 2152 2153 <span class="comment">//Check if the mutex has been successfully locked</span> 2154 <span class="keyword">if</span><span class="special">(</span><span class="identifier">lock</span><span class="special">){</span> 2155 <span class="comment">//Some code</span> 2156 <span class="special">}</span> 2157 <span class="comment">//If the mutex was locked it will be unlocked</span> 2158<span class="special">}</span> 2159</pre> 2160<p> 2161 <code class="computeroutput"><a class="link" href="../boost/interprocess/upgradable_lock.html" title="Class template upgradable_lock">upgradable_lock</a></code> 2162 and <code class="computeroutput"><a class="link" href="../boost/interprocess/sharable_lock.html" title="Class template sharable_lock">sharable_lock</a></code> 2163 offer more features and operations, see their reference for more informations 2164 </p> 2165<div class="important"><table border="0" summary="Important"> 2166<tr> 2167<td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="../../../doc/src/images/important.png"></td> 2168<th align="left">Important</th> 2169</tr> 2170<tr><td align="left" valign="top"><p> 2171 <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">posix_time</span><span class="special">::</span><span class="identifier">ptime</span></code> absolute time points used by 2172 Boost.Interprocess synchronization mechanisms are UTC time points, not 2173 local time points 2174 </p></td></tr> 2175</table></div> 2176</div> 2177</div> 2178<div class="section"> 2179<div class="titlepage"><div><div><h3 class="title"> 2180<a name="interprocess.synchronization_mechanisms.lock_conversions"></a><a class="link" href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.lock_conversions" title="Lock Transfers Through Move Semantics">Lock 2181 Transfers Through Move Semantics</a> 2182</h3></div></div></div> 2183<div class="toc"><dl class="toc"> 2184<dt><span class="section"><a href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.lock_conversions.lock_transfer_simple_transfer">Simple 2185 Lock Transfer</a></span></dt> 2186<dt><span class="section"><a href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.lock_conversions.lock_transfer_summary">Lock 2187 Transfer Summary</a></span></dt> 2188<dt><span class="section"><a href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.lock_conversions.lock_transfer_not_locked">Transferring 2189 Unlocked Locks</a></span></dt> 2190<dt><span class="section"><a href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.lock_conversions.lock_transfer_failure">Transfer 2191 Failures</a></span></dt> 2192</dl></div> 2193<div class="blurb"> 2194<div class="titlepage"><div><div><p class="title"><b></b></p></div></div></div> 2195<p> 2196 <span class="bold"><strong>Interprocess uses its own move semantics emulation 2197 code for compilers that don't support rvalues references. This is a temporary 2198 solution until a Boost move semantics library is accepted.</strong></span> 2199 </p> 2200</div> 2201<p> 2202 Scoped locks and similar utilities offer simple resource management possibilities, 2203 but with advanced mutex types like upgradable mutexes, there are operations 2204 where an acquired lock type is released and another lock type is acquired 2205 atomically. This is implemented by upgradable mutex operations like <code class="computeroutput"><span class="identifier">unlock_and_lock_sharable</span><span class="special">()</span></code>. 2206 </p> 2207<p> 2208 These operations can be managed more effectively using <span class="bold"><strong>lock 2209 transfer operations</strong></span>. A lock transfer operations explicitly indicates 2210 that a mutex owned by a lock is transferred to another lock executing atomic 2211 unlocking plus locking operations. 2212 </p> 2213<div class="section"> 2214<div class="titlepage"><div><div><h4 class="title"> 2215<a name="interprocess.synchronization_mechanisms.lock_conversions.lock_transfer_simple_transfer"></a><a class="link" href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.lock_conversions.lock_transfer_simple_transfer" title="Simple Lock Transfer">Simple 2216 Lock Transfer</a> 2217</h4></div></div></div> 2218<p> 2219 Imagine that a thread modifies some data in the beginning but after that, 2220 it has to just read it in a long time. The code can acquire the exclusive 2221 lock, modify the data and atomically release the exclusive lock and acquire 2222 the sharable lock. With these sequence we guarantee that no other thread 2223 can modify the data in the transition and that more readers can acquire 2224 sharable lock, increasing concurrency. Without lock transfer operations, 2225 this would be coded like this: 2226 </p> 2227<pre class="programlisting"><span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">;</span> 2228<span class="identifier">interprocess_upgradable_mutex</span> <span class="identifier">mutex</span><span class="special">;</span> 2229 2230<span class="comment">//Acquire exclusive lock</span> 2231<span class="identifier">mutex</span><span class="special">.</span><span class="identifier">lock</span><span class="special">();</span> 2232 2233<span class="comment">//Modify data</span> 2234 2235<span class="comment">//Atomically release exclusive lock and acquire sharable lock.</span> 2236<span class="comment">//More threads can acquire the sharable lock and read the data.</span> 2237<span class="identifier">mutex</span><span class="special">.</span><span class="identifier">unlock_and_lock_sharable</span><span class="special">();</span> 2238 2239<span class="comment">//Read data</span> 2240 2241<span class="comment">//Explicit unlocking</span> 2242<span class="identifier">mutex</span><span class="special">.</span><span class="identifier">unlock_sharable</span><span class="special">();</span> 2243</pre> 2244<p> 2245 This can be simple, but in the presence of exceptions, it's complicated 2246 to know what type of lock the mutex had when the exception was thrown and 2247 what function we should call to unlock it: 2248 </p> 2249<pre class="programlisting"><span class="keyword">try</span><span class="special">{</span> 2250 <span class="comment">//Mutex operations</span> 2251<span class="special">}</span> 2252<span class="keyword">catch</span><span class="special">(...){</span> 2253 <span class="comment">//What should we call? "unlock()" or "unlock_sharable()"</span> 2254 <span class="comment">//Is the mutex locked?</span> 2255<span class="special">}</span> 2256</pre> 2257<p> 2258 We can use <span class="bold"><strong>lock transfer</strong></span> to simplify all 2259 this management: 2260 </p> 2261<pre class="programlisting"><span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">;</span> 2262<span class="identifier">interprocess_upgradable_mutex</span> <span class="identifier">mutex</span><span class="special">;</span> 2263 2264<span class="comment">//Acquire exclusive lock</span> 2265<span class="identifier">scoped_lock</span> <span class="identifier">s_lock</span><span class="special">(</span><span class="identifier">mutex</span><span class="special">);</span> 2266 2267<span class="comment">//Modify data</span> 2268 2269<span class="comment">//Atomically release exclusive lock and acquire sharable lock.</span> 2270<span class="comment">//More threads can acquire the sharable lock and read the data.</span> 2271<span class="identifier">sharable_lock</span><span class="special">(</span><span class="identifier">move</span><span class="special">(</span><span class="identifier">s_lock</span><span class="special">));</span> 2272 2273<span class="comment">//Read data</span> 2274 2275<span class="comment">//The lock is automatically unlocked calling the appropriate unlock</span> 2276<span class="comment">//function even in the presence of exceptions.</span> 2277<span class="comment">//If the mutex was not locked, no function is called.</span> 2278</pre> 2279<p> 2280 As we can see, even if an exception is thrown at any moment, the mutex 2281 will be automatically unlocked calling the appropriate <code class="computeroutput"><span class="identifier">unlock</span><span class="special">()</span></code> or <code class="computeroutput"><span class="identifier">unlock_sharable</span><span class="special">()</span></code> method. 2282 </p> 2283</div> 2284<div class="section"> 2285<div class="titlepage"><div><div><h4 class="title"> 2286<a name="interprocess.synchronization_mechanisms.lock_conversions.lock_transfer_summary"></a><a class="link" href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.lock_conversions.lock_transfer_summary" title="Lock Transfer Summary">Lock 2287 Transfer Summary</a> 2288</h4></div></div></div> 2289<div class="toc"><dl class="toc"> 2290<dt><span class="section"><a href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.lock_conversions.lock_transfer_summary.lock_transfer_summary_scoped">Transfers 2291 To Scoped Lock</a></span></dt> 2292<dt><span class="section"><a href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.lock_conversions.lock_transfer_summary.lock_transfer_summary_upgradable">Transfers 2293 To Upgradable Lock</a></span></dt> 2294<dt><span class="section"><a href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.lock_conversions.lock_transfer_summary.lock_transfer_summary_sharable">Transfers 2295 To Sharable Lock</a></span></dt> 2296</dl></div> 2297<p> 2298 There are many lock transfer operations that we can classify according 2299 to the operations presented in the upgradable mutex operations: 2300 </p> 2301<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 2302<li class="listitem"> 2303 <span class="bold"><strong>Guaranteed to succeed and non-blocking:</strong></span> 2304 Any transition from a more restrictive lock to a less restrictive one. 2305 Scoped -> Upgradable, Scoped -> Sharable, Upgradable -> Sharable. 2306 </li> 2307<li class="listitem"> 2308 <span class="bold"><strong>Not guaranteed to succeed:</strong></span> The operation 2309 might succeed if no one has acquired the upgradable or exclusive lock: 2310 Sharable -> Exclusive. This operation is a try operation. 2311 </li> 2312<li class="listitem"> 2313 <span class="bold"><strong>Guaranteed to succeed if using an infinite waiting:</strong></span> 2314 Any transition that will succeed but needs to wait until all Sharable 2315 locks are released: Upgradable -> Scoped. Since this is a blocking 2316 operation, we can also choose not to wait infinitely and just try or 2317 wait until a timeout is reached. 2318 </li> 2319</ul></div> 2320<div class="section"> 2321<div class="titlepage"><div><div><h5 class="title"> 2322<a name="interprocess.synchronization_mechanisms.lock_conversions.lock_transfer_summary.lock_transfer_summary_scoped"></a><a class="link" href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.lock_conversions.lock_transfer_summary.lock_transfer_summary_scoped" title="Transfers To Scoped Lock">Transfers 2323 To Scoped Lock</a> 2324</h5></div></div></div> 2325<p> 2326 Transfers to <code class="computeroutput"><span class="identifier">scoped_lock</span></code> 2327 are guaranteed to succeed only from an <code class="computeroutput"><span class="identifier">upgradable_lock</span></code> 2328 and only if a blocking operation is requested, due to the fact that this 2329 operation needs to wait until all sharable locks are released. The user 2330 can also use "try" or "timed" transfer to avoid infinite 2331 locking, but succeed is not guaranteed. 2332 </p> 2333<p> 2334 A conversion from a <code class="computeroutput"><span class="identifier">sharable_lock</span></code> 2335 is never guaranteed and thus, only a try operation is permitted: 2336 </p> 2337<pre class="programlisting"><span class="comment">//Conversions to scoped_lock</span> 2338<span class="special">{</span> 2339 <span class="identifier">upgradable_lock</span><span class="special"><</span><span class="identifier">Mutex</span><span class="special">></span> <span class="identifier">u_lock</span><span class="special">(</span><span class="identifier">mut</span><span class="special">);</span> 2340 <span class="comment">//This calls unlock_upgradable_and_lock()</span> 2341 <span class="identifier">scoped_lock</span><span class="special"><</span><span class="identifier">Mutex</span><span class="special">></span> <span class="identifier">e_lock</span><span class="special">(</span><span class="identifier">move</span><span class="special">(</span><span class="identifier">u_lock</span><span class="special">));</span> 2342<span class="special">}</span> 2343<span class="special">{</span> 2344 <span class="identifier">upgradable_lock</span><span class="special"><</span><span class="identifier">Mutex</span><span class="special">></span> <span class="identifier">u_lock</span><span class="special">(</span><span class="identifier">mut</span><span class="special">);</span> 2345 <span class="comment">//This calls try_unlock_upgradable_and_lock()</span> 2346 <span class="identifier">scoped_lock</span><span class="special"><</span><span class="identifier">Mutex</span><span class="special">></span> <span class="identifier">e_lock</span><span class="special">(</span><span class="identifier">move</span><span class="special">(</span><span class="identifier">u_lock</span><span class="special">,</span> <span class="identifier">try_to_lock</span><span class="special">));</span> 2347<span class="special">}</span> 2348<span class="special">{</span> 2349 <span class="identifier">boost</span><span class="special">::</span><span class="identifier">posix_time</span><span class="special">::</span><span class="identifier">ptime</span> <span class="identifier">t</span> <span class="special">=</span> <span class="identifier">test</span><span class="special">::</span><span class="identifier">delay</span><span class="special">(</span><span class="number">100</span><span class="special">);</span> 2350 <span class="identifier">upgradable_lock</span><span class="special"><</span><span class="identifier">Mutex</span><span class="special">></span> <span class="identifier">u_lock</span><span class="special">(</span><span class="identifier">mut</span><span class="special">);</span> 2351 <span class="comment">//This calls timed_unlock_upgradable_and_lock()</span> 2352 <span class="identifier">scoped_lock</span><span class="special"><</span><span class="identifier">Mutex</span><span class="special">></span> <span class="identifier">e_lock</span><span class="special">(</span><span class="identifier">move</span><span class="special">(</span><span class="identifier">u_lock</span><span class="special">));</span> 2353<span class="special">}</span> 2354<span class="special">{</span> 2355 <span class="identifier">sharable_lock</span><span class="special"><</span><span class="identifier">Mutex</span><span class="special">></span> <span class="identifier">s_lock</span><span class="special">(</span><span class="identifier">mut</span><span class="special">);</span> 2356 <span class="comment">//This calls try_unlock_sharable_and_lock()</span> 2357 <span class="identifier">scoped_lock</span><span class="special"><</span><span class="identifier">Mutex</span><span class="special">></span> <span class="identifier">e_lock</span><span class="special">(</span><span class="identifier">move</span><span class="special">(</span><span class="identifier">s_lock</span><span class="special">,</span> <span class="identifier">try_to_lock</span><span class="special">));</span> 2358<span class="special">}</span> 2359</pre> 2360<div class="important"><table border="0" summary="Important"> 2361<tr> 2362<td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="../../../doc/src/images/important.png"></td> 2363<th align="left">Important</th> 2364</tr> 2365<tr><td align="left" valign="top"><p> 2366 <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">posix_time</span><span class="special">::</span><span class="identifier">ptime</span></code> absolute time points used by 2367 Boost.Interprocess synchronization mechanisms are UTC time points, 2368 not local time points 2369 </p></td></tr> 2370</table></div> 2371</div> 2372<div class="section"> 2373<div class="titlepage"><div><div><h5 class="title"> 2374<a name="interprocess.synchronization_mechanisms.lock_conversions.lock_transfer_summary.lock_transfer_summary_upgradable"></a><a class="link" href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.lock_conversions.lock_transfer_summary.lock_transfer_summary_upgradable" title="Transfers To Upgradable Lock">Transfers 2375 To Upgradable Lock</a> 2376</h5></div></div></div> 2377<p> 2378 A transfer to an <code class="computeroutput"><span class="identifier">upgradable_lock</span></code> 2379 is guaranteed to succeed only from a <code class="computeroutput"><span class="identifier">scoped_lock</span></code> 2380 since scoped locking is a more restrictive locking than an upgradable 2381 locking. This operation is also non-blocking. 2382 </p> 2383<p> 2384 A transfer from a <code class="computeroutput"><span class="identifier">sharable_lock</span></code> 2385 is not guaranteed and only a "try" operation is permitted: 2386 </p> 2387<pre class="programlisting"><span class="comment">//Conversions to upgradable</span> 2388<span class="special">{</span> 2389 <span class="identifier">sharable_lock</span><span class="special"><</span><span class="identifier">Mutex</span><span class="special">></span> <span class="identifier">s_lock</span><span class="special">(</span><span class="identifier">mut</span><span class="special">);</span> 2390 <span class="comment">//This calls try_unlock_sharable_and_lock_upgradable()</span> 2391 <span class="identifier">upgradable_lock</span><span class="special"><</span><span class="identifier">Mutex</span><span class="special">></span> <span class="identifier">u_lock</span><span class="special">(</span><span class="identifier">move</span><span class="special">(</span><span class="identifier">s_lock</span><span class="special">,</span> <span class="identifier">try_to_lock</span><span class="special">));</span> 2392<span class="special">}</span> 2393<span class="special">{</span> 2394 <span class="identifier">scoped_lock</span><span class="special"><</span><span class="identifier">Mutex</span><span class="special">></span> <span class="identifier">e_lock</span><span class="special">(</span><span class="identifier">mut</span><span class="special">);</span> 2395 <span class="comment">//This calls unlock_and_lock_upgradable()</span> 2396 <span class="identifier">upgradable_lock</span><span class="special"><</span><span class="identifier">Mutex</span><span class="special">></span> <span class="identifier">u_lock</span><span class="special">(</span><span class="identifier">move</span><span class="special">(</span><span class="identifier">e_lock</span><span class="special">));</span> 2397<span class="special">}</span> 2398</pre> 2399</div> 2400<div class="section"> 2401<div class="titlepage"><div><div><h5 class="title"> 2402<a name="interprocess.synchronization_mechanisms.lock_conversions.lock_transfer_summary.lock_transfer_summary_sharable"></a><a class="link" href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.lock_conversions.lock_transfer_summary.lock_transfer_summary_sharable" title="Transfers To Sharable Lock">Transfers 2403 To Sharable Lock</a> 2404</h5></div></div></div> 2405<p> 2406 All transfers to a <code class="computeroutput"><span class="identifier">sharable_lock</span></code> 2407 are guaranteed to succeed since both <code class="computeroutput"><span class="identifier">upgradable_lock</span></code> 2408 and <code class="computeroutput"><span class="identifier">scoped_lock</span></code> are more 2409 restrictive than <code class="computeroutput"><span class="identifier">sharable_lock</span></code>. 2410 These operations are also non-blocking: 2411 </p> 2412<pre class="programlisting"><span class="comment">//Conversions to sharable_lock</span> 2413<span class="special">{</span> 2414 <span class="identifier">upgradable_lock</span><span class="special"><</span><span class="identifier">Mutex</span><span class="special">></span> <span class="identifier">u_lock</span><span class="special">(</span><span class="identifier">mut</span><span class="special">);</span> 2415 <span class="comment">//This calls unlock_upgradable_and_lock_sharable()</span> 2416 <span class="identifier">sharable_lock</span><span class="special"><</span><span class="identifier">Mutex</span><span class="special">></span> <span class="identifier">s_lock</span><span class="special">(</span><span class="identifier">move</span><span class="special">(</span><span class="identifier">u_lock</span><span class="special">));</span> 2417<span class="special">}</span> 2418<span class="special">{</span> 2419 <span class="identifier">scoped_lock</span><span class="special"><</span><span class="identifier">Mutex</span><span class="special">></span> <span class="identifier">e_lock</span><span class="special">(</span><span class="identifier">mut</span><span class="special">);</span> 2420 <span class="comment">//This calls unlock_and_lock_sharable()</span> 2421 <span class="identifier">sharable_lock</span><span class="special"><</span><span class="identifier">Mutex</span><span class="special">></span> <span class="identifier">s_lock</span><span class="special">(</span><span class="identifier">move</span><span class="special">(</span><span class="identifier">e_lock</span><span class="special">));</span> 2422<span class="special">}</span> 2423</pre> 2424</div> 2425</div> 2426<div class="section"> 2427<div class="titlepage"><div><div><h4 class="title"> 2428<a name="interprocess.synchronization_mechanisms.lock_conversions.lock_transfer_not_locked"></a><a class="link" href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.lock_conversions.lock_transfer_not_locked" title="Transferring Unlocked Locks">Transferring 2429 Unlocked Locks</a> 2430</h4></div></div></div> 2431<p> 2432 In the previous examples, the mutex used in the transfer operation was 2433 previously locked: 2434 </p> 2435<pre class="programlisting"> <span class="identifier">Mutex</span> <span class="identifier">mut</span><span class="special">;</span> 2436 2437 <span class="comment">//This calls mut.lock()</span> 2438 <span class="identifier">scoped_lock</span><span class="special"><</span><span class="identifier">Mutex</span><span class="special">></span> <span class="identifier">e_lock</span><span class="special">(</span><span class="identifier">mut</span><span class="special">);</span> 2439 2440 <span class="comment">//This calls unlock_and_lock_sharable()</span> 2441 <span class="identifier">sharable_lock</span><span class="special"><</span><span class="identifier">Mutex</span><span class="special">></span> <span class="identifier">s_lock</span><span class="special">(</span><span class="identifier">move</span><span class="special">(</span><span class="identifier">e_lock</span><span class="special">));</span> 2442<span class="special">}</span> 2443</pre> 2444<p> 2445 but it's possible to execute the transfer with an unlocked source, due 2446 to explicit unlocking, a try, timed or a <code class="computeroutput"><span class="identifier">defer_lock</span></code> 2447 constructor: 2448 </p> 2449<pre class="programlisting"><span class="comment">//These operations can leave the mutex unlocked!</span> 2450 2451<span class="special">{</span> 2452 <span class="comment">//Try might fail</span> 2453 <span class="identifier">scoped_lock</span><span class="special"><</span><span class="identifier">Mutex</span><span class="special">></span> <span class="identifier">e_lock</span><span class="special">(</span><span class="identifier">mut</span><span class="special">,</span> <span class="identifier">try_to_lock</span><span class="special">);</span> 2454 <span class="identifier">sharable_lock</span><span class="special"><</span><span class="identifier">Mutex</span><span class="special">></span> <span class="identifier">s_lock</span><span class="special">(</span><span class="identifier">move</span><span class="special">(</span><span class="identifier">e_lock</span><span class="special">));</span> 2455<span class="special">}</span> 2456<span class="special">{</span> 2457 <span class="comment">//Timed operation might fail</span> 2458 <span class="identifier">scoped_lock</span><span class="special"><</span><span class="identifier">Mutex</span><span class="special">></span> <span class="identifier">e_lock</span><span class="special">(</span><span class="identifier">mut</span><span class="special">,</span> <span class="identifier">time</span><span class="special">);</span> 2459 <span class="identifier">sharable_lock</span><span class="special"><</span><span class="identifier">Mutex</span><span class="special">></span> <span class="identifier">s_lock</span><span class="special">(</span><span class="identifier">move</span><span class="special">(</span><span class="identifier">e_lock</span><span class="special">));</span> 2460<span class="special">}</span> 2461<span class="special">{</span> 2462 <span class="comment">//Avoid mutex locking</span> 2463 <span class="identifier">scoped_lock</span><span class="special"><</span><span class="identifier">Mutex</span><span class="special">></span> <span class="identifier">e_lock</span><span class="special">(</span><span class="identifier">mut</span><span class="special">,</span> <span class="identifier">defer_lock</span><span class="special">);</span> 2464 <span class="identifier">sharable_lock</span><span class="special"><</span><span class="identifier">Mutex</span><span class="special">></span> <span class="identifier">s_lock</span><span class="special">(</span><span class="identifier">move</span><span class="special">(</span><span class="identifier">e_lock</span><span class="special">));</span> 2465<span class="special">}</span> 2466<span class="special">{</span> 2467 <span class="comment">//Explicitly call unlock</span> 2468 <span class="identifier">scoped_lock</span><span class="special"><</span><span class="identifier">Mutex</span><span class="special">></span> <span class="identifier">e_lock</span><span class="special">(</span><span class="identifier">mut</span><span class="special">);</span> 2469 <span class="identifier">e_lock</span><span class="special">.</span><span class="identifier">unlock</span><span class="special">();</span> 2470 <span class="comment">//Mutex was explicitly unlocked</span> 2471 <span class="identifier">sharable_lock</span><span class="special"><</span><span class="identifier">Mutex</span><span class="special">></span> <span class="identifier">s_lock</span><span class="special">(</span><span class="identifier">move</span><span class="special">(</span><span class="identifier">e_lock</span><span class="special">));</span> 2472<span class="special">}</span> 2473</pre> 2474<p> 2475 If the source mutex was not locked: 2476 </p> 2477<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 2478<li class="listitem"> 2479 The target lock does not execute the atomic <code class="computeroutput"><span class="identifier">unlock_xxx_and_lock_xxx</span></code> 2480 operation. 2481 </li> 2482<li class="listitem"> 2483 The target lock is also unlocked. 2484 </li> 2485<li class="listitem"> 2486 The source lock is released() and the ownership of the mutex is transferred 2487 to the target. 2488 </li> 2489</ul></div> 2490<pre class="programlisting"><span class="special">{</span> 2491 <span class="identifier">scoped_lock</span><span class="special"><</span><span class="identifier">Mutex</span><span class="special">></span> <span class="identifier">e_lock</span><span class="special">(</span><span class="identifier">mut</span><span class="special">,</span> <span class="identifier">defer_lock</span><span class="special">);</span> 2492 <span class="identifier">sharable_lock</span><span class="special"><</span><span class="identifier">Mutex</span><span class="special">></span> <span class="identifier">s_lock</span><span class="special">(</span><span class="identifier">move</span><span class="special">(</span><span class="identifier">e_lock</span><span class="special">));</span> 2493 2494 <span class="comment">//Assertions</span> 2495 <span class="identifier">assert</span><span class="special">(</span><span class="identifier">e_lock</span><span class="special">.</span><span class="identifier">mutex</span><span class="special">()</span> <span class="special">==</span> <span class="number">0</span><span class="special">);</span> 2496 <span class="identifier">assert</span><span class="special">(</span><span class="identifier">s_lock</span><span class="special">.</span><span class="identifier">mutex</span><span class="special">()</span> <span class="special">!=</span> <span class="number">0</span><span class="special">);</span> 2497 <span class="identifier">assert</span><span class="special">(</span><span class="identifier">e_lock</span><span class="special">.</span><span class="identifier">owns</span><span class="special">()</span> <span class="special">==</span> <span class="keyword">false</span><span class="special">);</span> 2498<span class="special">}</span> 2499</pre> 2500</div> 2501<div class="section"> 2502<div class="titlepage"><div><div><h4 class="title"> 2503<a name="interprocess.synchronization_mechanisms.lock_conversions.lock_transfer_failure"></a><a class="link" href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.lock_conversions.lock_transfer_failure" title="Transfer Failures">Transfer 2504 Failures</a> 2505</h4></div></div></div> 2506<p> 2507 When executing a lock transfer, the operation can fail: 2508 </p> 2509<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 2510<li class="listitem"> 2511 The executed atomic mutex unlock plus lock function might throw. 2512 </li> 2513<li class="listitem"> 2514 The executed atomic function might be a "try" or "timed" 2515 function that can fail. 2516 </li> 2517</ul></div> 2518<p> 2519 In the first case, the mutex ownership is not transferred and the source 2520 lock's destructor will unlock the mutex: 2521 </p> 2522<pre class="programlisting"><span class="special">{</span> 2523 <span class="identifier">scoped_lock</span><span class="special"><</span><span class="identifier">Mutex</span><span class="special">></span> <span class="identifier">e_lock</span><span class="special">(</span><span class="identifier">mut</span><span class="special">,</span> <span class="identifier">defer_lock</span><span class="special">);</span> 2524 2525 <span class="comment">//This operations throws because</span> 2526 <span class="comment">//"unlock_and_lock_sharable()" throws!!!</span> 2527 <span class="identifier">sharable_lock</span><span class="special"><</span><span class="identifier">Mutex</span><span class="special">></span> <span class="identifier">s_lock</span><span class="special">(</span><span class="identifier">move</span><span class="special">(</span><span class="identifier">e_lock</span><span class="special">));</span> 2528 2529 <span class="comment">//Some code ...</span> 2530 2531 <span class="comment">//e_lock's destructor will call "unlock()"</span> 2532<span class="special">}</span> 2533</pre> 2534<p> 2535 In the second case, if an internal "try" or "timed" 2536 operation fails (returns "false") then the mutex ownership is 2537 <span class="bold"><strong>not</strong></span> transferred, the source lock is unchanged 2538 and the target lock's state will the same as a default construction: 2539 </p> 2540<pre class="programlisting"><span class="special">{</span> 2541 <span class="identifier">sharable_lock</span><span class="special"><</span><span class="identifier">Mutex</span><span class="special">></span> <span class="identifier">s_lock</span><span class="special">(</span><span class="identifier">mut</span><span class="special">);</span> 2542 2543 <span class="comment">//Internal "try_unlock_sharable_and_lock_upgradable()" returns false</span> 2544 <span class="identifier">upgradable_lock</span><span class="special"><</span><span class="identifier">Mutex</span><span class="special">></span> <span class="identifier">u_lock</span><span class="special">(</span><span class="identifier">move</span><span class="special">(</span><span class="identifier">s_lock</span><span class="special">,</span> <span class="identifier">try_to_lock</span><span class="special">));</span> 2545 2546 <span class="identifier">assert</span><span class="special">(</span><span class="identifier">s_lock</span><span class="special">.</span><span class="identifier">mutex</span><span class="special">()</span> <span class="special">==</span> <span class="special">&</span><span class="identifier">mut</span><span class="special">);</span> 2547 <span class="identifier">assert</span><span class="special">(</span><span class="identifier">s_lock</span><span class="special">.</span><span class="identifier">owns</span><span class="special">()</span> <span class="special">==</span> <span class="keyword">true</span><span class="special">);</span> 2548 <span class="identifier">assert</span><span class="special">(</span><span class="identifier">u_lock</span><span class="special">.</span><span class="identifier">mutex</span><span class="special">()</span> <span class="special">==</span> <span class="number">0</span><span class="special">);</span> 2549 <span class="identifier">assert</span><span class="special">(</span><span class="identifier">u_lock</span><span class="special">.</span><span class="identifier">owns</span><span class="special">()</span> <span class="special">==</span> <span class="keyword">false</span><span class="special">);</span> 2550 2551 <span class="comment">//u_lock's destructor does nothing</span> 2552 <span class="comment">//s_lock's destructor calls "unlock()"</span> 2553<span class="special">}</span> 2554</pre> 2555</div> 2556</div> 2557<div class="section"> 2558<div class="titlepage"><div><div><h3 class="title"> 2559<a name="interprocess.synchronization_mechanisms.file_lock"></a><a class="link" href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.file_lock" title="File Locks">File 2560 Locks</a> 2561</h3></div></div></div> 2562<div class="toc"><dl class="toc"> 2563<dt><span class="section"><a href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.file_lock.file_lock_whats_a_file_lock">What's 2564 A File Lock?</a></span></dt> 2565<dt><span class="section"><a href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.file_lock.file_lock_operations">File 2566 Locking Operations</a></span></dt> 2567<dt><span class="section"><a href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.file_lock.file_lock_scoped_locks">Scoped 2568 Lock and Sharable Lock With File Locking</a></span></dt> 2569<dt><span class="section"><a href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.file_lock.file_lock_not_thread_safe">Caution: 2570 Synchronization limitations</a></span></dt> 2571<dt><span class="section"><a href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.file_lock.file_lock_careful_iostream">Be 2572 Careful With Iostream Writing</a></span></dt> 2573</dl></div> 2574<div class="section"> 2575<div class="titlepage"><div><div><h4 class="title"> 2576<a name="interprocess.synchronization_mechanisms.file_lock.file_lock_whats_a_file_lock"></a><a class="link" href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.file_lock.file_lock_whats_a_file_lock" title="What's A File Lock?">What's 2577 A File Lock?</a> 2578</h4></div></div></div> 2579<p> 2580 A file lock is an interprocess synchronization mechanism to protect concurrent 2581 writes and reads to files using a mutex <span class="emphasis"><em>embedded</em></span> in 2582 the file. This <span class="emphasis"><em>embedded mutex</em></span> has sharable and exclusive 2583 locking capabilities. With a file lock, an existing file can be used as 2584 a mutex without the need of creating additional synchronization objects 2585 to control concurrent file reads or writes. 2586 </p> 2587<p> 2588 Generally speaking, we can have two file locking capabilities: 2589 </p> 2590<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 2591<li class="listitem"> 2592 <span class="bold"><strong>Advisory locking:</strong></span> The operating system 2593 kernel maintains a list of files that have been locked. But does not 2594 prevent writing to those files even if a process has acquired a sharable 2595 lock or does not prevent reading from the file when a process has acquired 2596 the exclusive lock. Any process can ignore an advisory lock. This means 2597 that advisory locks are for <span class="bold"><strong>cooperating</strong></span> 2598 processes, processes that can trust each other. This is similar to 2599 a mutex protecting data in a shared memory segment: any process connected 2600 to that memory can overwrite the data but <span class="bold"><strong>cooperative</strong></span> 2601 processes use mutexes to protect the data first acquiring the mutex 2602 lock. 2603 </li> 2604<li class="listitem"> 2605 <span class="bold"><strong>Mandatory locking:</strong></span> The OS kernel checks 2606 every read and write request to verify that the operation can be performed 2607 according to the acquired lock. Reads and writes block until the lock 2608 is released. 2609 </li> 2610</ul></div> 2611<p> 2612 <span class="bold"><strong>Boost.Interprocess</strong></span> implements <span class="bold"><strong>advisory blocking</strong></span> because of portability reasons. 2613 This means that every process accessing to a file concurrently, must cooperate 2614 using file locks to synchronize the access. 2615 </p> 2616<p> 2617 In some systems file locking can be even further refined, leading to <span class="bold"><strong>record locking</strong></span>, where a user can specify a <span class="bold"><strong>byte range</strong></span> within the file where the lock is applied. 2618 This allows concurrent write access by several processes if they need to 2619 access a different byte range in the file. <span class="bold"><strong>Boost.Interprocess</strong></span> 2620 does <span class="bold"><strong>not</strong></span> offer record locking for the 2621 moment, but might offer it in the future. To use a file lock just include: 2622 </p> 2623<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">interprocess</span><span class="special">/</span><span class="identifier">sync</span><span class="special">/</span><span class="identifier">file_lock</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 2624</pre> 2625<p> 2626 A file locking is a class that has <span class="bold"><strong>process lifetime</strong></span>. 2627 This means that if a process holding a file lock ends or crashes, the operating 2628 system will automatically unlock it. This feature is very useful in some 2629 situations where we want to assure automatic unlocking even when the process 2630 crashes and avoid leaving blocked resources in the system. A file lock 2631 is constructed using the name of the file as an argument: 2632 </p> 2633<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">interprocess</span><span class="special">/</span><span class="identifier">sync</span><span class="special">/</span><span class="identifier">file_lock</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 2634 2635<span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span> 2636<span class="special">{</span> 2637 <span class="comment">//This throws if the file does not exist or it can't</span> 2638 <span class="comment">//open it with read-write access!</span> 2639 <span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">::</span><span class="identifier">file_lock</span> <span class="identifier">flock</span><span class="special">(</span><span class="string">"my_file"</span><span class="special">);</span> 2640 <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span> 2641<span class="special">}</span> 2642</pre> 2643</div> 2644<div class="section"> 2645<div class="titlepage"><div><div><h4 class="title"> 2646<a name="interprocess.synchronization_mechanisms.file_lock.file_lock_operations"></a><a class="link" href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.file_lock.file_lock_operations" title="File Locking Operations">File 2647 Locking Operations</a> 2648</h4></div></div></div> 2649<p> 2650 File locking has normal mutex operations plus sharable locking capabilities. 2651 This means that we can have multiple readers holding the sharable lock 2652 and writers holding the exclusive lock waiting until the readers end their 2653 job. 2654 </p> 2655<p> 2656 However, file locking does <span class="bold"><strong>not</strong></span> support 2657 upgradable locking or promotion or demotion (lock transfers), so it's more 2658 limited than an upgradable lock. These are the operations: 2659 </p> 2660<div class="blurb"> 2661<div class="titlepage"><div><div><p class="title"><b></b></p></div></div></div> 2662<p> 2663 <span class="emphasis"><em><span class="bold"><strong>void lock()</strong></span></em></span> 2664 </p> 2665</div> 2666<p> 2667 <span class="bold"><strong>Effects:</strong></span> The calling thread tries to obtain 2668 exclusive ownership of the file lock, and if another thread has exclusive 2669 or sharable ownership of the mutex, it waits until it can obtain the ownership. 2670 </p> 2671<p> 2672 <span class="bold"><strong>Throws:</strong></span> <span class="bold"><strong>interprocess_exception</strong></span> 2673 on error. 2674 </p> 2675<div class="blurb"> 2676<div class="titlepage"><div><div><p class="title"><b></b></p></div></div></div> 2677<p> 2678 <span class="emphasis"><em><span class="bold"><strong>bool try_lock()</strong></span></em></span> 2679 </p> 2680</div> 2681<p> 2682 <span class="bold"><strong>Effects:</strong></span> The calling thread tries to acquire 2683 exclusive ownership of the file lock without waiting. If no other thread 2684 has exclusive or sharable ownership of the file lock, this succeeds. 2685 </p> 2686<p> 2687 <span class="bold"><strong>Returns:</strong></span> If it can acquire exclusive ownership 2688 immediately returns true. If it has to wait, returns false. 2689 </p> 2690<p> 2691 <span class="bold"><strong>Throws:</strong></span> <span class="bold"><strong>interprocess_exception</strong></span> 2692 on error. 2693 </p> 2694<div class="blurb"> 2695<div class="titlepage"><div><div><p class="title"><b></b></p></div></div></div> 2696<p> 2697 <span class="emphasis"><em><span class="bold"><strong>bool timed_lock(const boost::posix_time::ptime 2698 &abs_time)</strong></span></em></span> 2699 </p> 2700</div> 2701<p> 2702 <span class="bold"><strong>Effects:</strong></span> The calling thread tries to acquire 2703 exclusive ownership of the file lock waiting if necessary until no other 2704 thread has exclusive or sharable ownership of the file lock or abs_time 2705 is reached. 2706 </p> 2707<p> 2708 <span class="bold"><strong>Returns:</strong></span> If acquires exclusive ownership, 2709 returns true. Otherwise returns false. 2710 </p> 2711<p> 2712 <span class="bold"><strong>Throws:</strong></span> <span class="bold"><strong>interprocess_exception</strong></span> 2713 on error. 2714 </p> 2715<div class="blurb"> 2716<div class="titlepage"><div><div><p class="title"><b></b></p></div></div></div> 2717<p> 2718 <span class="emphasis"><em><span class="bold"><strong>void unlock()</strong></span></em></span> 2719 </p> 2720</div> 2721<p> 2722 <span class="bold"><strong>Precondition:</strong></span> The thread must have exclusive 2723 ownership of the file lock. 2724 </p> 2725<p> 2726 <span class="bold"><strong>Effects:</strong></span> The calling thread releases the 2727 exclusive ownership of the file lock. 2728 </p> 2729<p> 2730 <span class="bold"><strong>Throws:</strong></span> An exception derived from <span class="bold"><strong>interprocess_exception</strong></span> on error. 2731 </p> 2732<div class="blurb"> 2733<div class="titlepage"><div><div><p class="title"><b></b></p></div></div></div> 2734<p> 2735 <span class="emphasis"><em><span class="bold"><strong>void lock_sharable()</strong></span></em></span> 2736 </p> 2737</div> 2738<p> 2739 <span class="bold"><strong>Effects:</strong></span> The calling thread tries to obtain 2740 sharable ownership of the file lock, and if another thread has exclusive 2741 ownership of the file lock, waits until it can obtain the ownership. 2742 </p> 2743<p> 2744 <span class="bold"><strong>Throws:</strong></span> <span class="bold"><strong>interprocess_exception</strong></span> 2745 on error. 2746 </p> 2747<div class="blurb"> 2748<div class="titlepage"><div><div><p class="title"><b></b></p></div></div></div> 2749<p> 2750 <span class="emphasis"><em><span class="bold"><strong>bool try_lock_sharable()</strong></span></em></span> 2751 </p> 2752</div> 2753<p> 2754 <span class="bold"><strong>Effects:</strong></span> The calling thread tries to acquire 2755 sharable ownership of the file lock without waiting. If no other thread 2756 has exclusive ownership of the file lock, this succeeds. 2757 </p> 2758<p> 2759 <span class="bold"><strong>Returns:</strong></span> If it can acquire sharable ownership 2760 immediately returns true. If it has to wait, returns false. 2761 </p> 2762<p> 2763 <span class="bold"><strong>Throws:</strong></span> <span class="bold"><strong>interprocess_exception</strong></span> 2764 on error. 2765 </p> 2766<div class="blurb"> 2767<div class="titlepage"><div><div><p class="title"><b></b></p></div></div></div> 2768<p> 2769 <span class="emphasis"><em><span class="bold"><strong>bool timed_lock_sharable(const boost::posix_time::ptime 2770 &abs_time)</strong></span></em></span> 2771 </p> 2772</div> 2773<p> 2774 <span class="bold"><strong>Effects:</strong></span> The calling thread tries to acquire 2775 sharable ownership of the file lock waiting if necessary until no other 2776 thread has exclusive ownership of the file lock or abs_time is reached. 2777 </p> 2778<p> 2779 <span class="bold"><strong>Returns:</strong></span> If acquires sharable ownership, 2780 returns true. Otherwise returns false. 2781 </p> 2782<p> 2783 <span class="bold"><strong>Throws:</strong></span> <span class="bold"><strong>interprocess_exception</strong></span> 2784 on error. 2785 </p> 2786<div class="blurb"> 2787<div class="titlepage"><div><div><p class="title"><b></b></p></div></div></div> 2788<p> 2789 <span class="emphasis"><em><span class="bold"><strong>void unlock_sharable()</strong></span></em></span> 2790 </p> 2791</div> 2792<p> 2793 <span class="bold"><strong>Precondition:</strong></span> The thread must have sharable 2794 ownership of the file lock. 2795 </p> 2796<p> 2797 <span class="bold"><strong>Effects:</strong></span> The calling thread releases the 2798 sharable ownership of the file lock. 2799 </p> 2800<p> 2801 <span class="bold"><strong>Throws:</strong></span> An exception derived from <span class="bold"><strong>interprocess_exception</strong></span> on error. 2802 </p> 2803<p> 2804 For more file locking methods, please <code class="computeroutput"><a class="link" href="../boost/interprocess/file_lock.html" title="Class file_lock">file_lock 2805 reference</a></code>. 2806 </p> 2807<div class="important"><table border="0" summary="Important"> 2808<tr> 2809<td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="../../../doc/src/images/important.png"></td> 2810<th align="left">Important</th> 2811</tr> 2812<tr><td align="left" valign="top"><p> 2813 <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">posix_time</span><span class="special">::</span><span class="identifier">ptime</span></code> absolute time points used by 2814 Boost.Interprocess synchronization mechanisms are UTC time points, not 2815 local time points 2816 </p></td></tr> 2817</table></div> 2818</div> 2819<div class="section"> 2820<div class="titlepage"><div><div><h4 class="title"> 2821<a name="interprocess.synchronization_mechanisms.file_lock.file_lock_scoped_locks"></a><a class="link" href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.file_lock.file_lock_scoped_locks" title="Scoped Lock and Sharable Lock With File Locking">Scoped 2822 Lock and Sharable Lock With File Locking</a> 2823</h4></div></div></div> 2824<p> 2825 <code class="computeroutput"><a class="link" href="../boost/interprocess/scoped_lock.html" title="Class template scoped_lock">scoped_lock</a></code> 2826 and <code class="computeroutput"><a class="link" href="../boost/interprocess/sharable_lock.html" title="Class template sharable_lock">sharable_lock</a></code> 2827 can be used to make file locking easier in the presence of exceptions, 2828 just like with mutexes: 2829 </p> 2830<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">interprocess</span><span class="special">/</span><span class="identifier">sync</span><span class="special">/</span><span class="identifier">file_lock</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 2831<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">interprocess</span><span class="special">/</span><span class="identifier">sync</span><span class="special">/</span><span class="identifier">sharable_lock</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 2832<span class="comment">//...</span> 2833 2834<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">;</span> 2835<span class="comment">//This process reads the file</span> 2836<span class="comment">// ...</span> 2837<span class="comment">//Open the file lock</span> 2838<span class="identifier">file_lock</span> <span class="identifier">f_lock</span><span class="special">(</span><span class="string">"my_file"</span><span class="special">);</span> 2839 2840<span class="special">{</span> 2841 <span class="comment">//Construct a sharable lock with the file lock.</span> 2842 <span class="comment">//This will call "f_lock.sharable_lock()".</span> 2843 <span class="identifier">sharable_lock</span><span class="special"><</span><span class="identifier">file_lock</span><span class="special">></span> <span class="identifier">sh_lock</span><span class="special">(</span><span class="identifier">f_lock</span><span class="special">);</span> 2844 2845 <span class="comment">//Now read the file...</span> 2846 2847 <span class="comment">//The sharable lock is automatically released by</span> 2848 <span class="comment">//sh_lock's destructor</span> 2849<span class="special">}</span> 2850</pre> 2851<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">interprocess</span><span class="special">/</span><span class="identifier">sync</span><span class="special">/</span><span class="identifier">file_lock</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 2852<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">interprocess</span><span class="special">/</span><span class="identifier">sync</span><span class="special">/</span><span class="identifier">scoped_lock</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 2853 2854<span class="comment">//...</span> 2855 2856<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">;</span> 2857<span class="comment">//This process writes the file</span> 2858<span class="comment">// ...</span> 2859<span class="comment">//Open the file lock</span> 2860<span class="identifier">file_lock</span> <span class="identifier">f_lock</span><span class="special">(</span><span class="string">"my_file"</span><span class="special">);</span> 2861 2862<span class="special">{</span> 2863 <span class="comment">//Construct an exclusive lock with the file lock.</span> 2864 <span class="comment">//This will call "f_lock.lock()".</span> 2865 <span class="identifier">scoped_lock</span><span class="special"><</span><span class="identifier">file_lock</span><span class="special">></span> <span class="identifier">e_lock</span><span class="special">(</span><span class="identifier">f_lock</span><span class="special">);</span> 2866 2867 <span class="comment">//Now write the file...</span> 2868 2869 <span class="comment">//The exclusive lock is automatically released by</span> 2870 <span class="comment">//e_lock's destructor</span> 2871<span class="special">}</span> 2872</pre> 2873<p> 2874 However, lock transfers are only allowed between same type of locks, that 2875 is, from a sharable lock to another sharable lock or from a scoped lock 2876 to another scoped lock. A transfer from a scoped lock to a sharable lock 2877 is not allowed, because <code class="computeroutput"><a class="link" href="../boost/interprocess/file_lock.html" title="Class file_lock">file_lock</a></code> 2878 has no lock promotion or demotion functions like <code class="computeroutput"><span class="identifier">unlock_and_lock_sharable</span><span class="special">()</span></code>. This will produce a compilation error: 2879 </p> 2880<pre class="programlisting"><span class="comment">//Open the file lock</span> 2881<span class="identifier">file_lock</span> <span class="identifier">f_lock</span><span class="special">(</span><span class="string">"my_file"</span><span class="special">);</span> 2882 2883<span class="identifier">scoped_lock</span><span class="special"><</span><span class="identifier">file_lock</span><span class="special">></span> <span class="identifier">e_lock</span><span class="special">(</span><span class="identifier">f_lock</span><span class="special">);</span> 2884 2885<span class="comment">//Compilation error, f_lock has no "unlock_and_lock_sharable()" member!</span> 2886<span class="identifier">sharable_lock</span><span class="special"><</span><span class="identifier">file_lock</span><span class="special">></span> <span class="identifier">e_lock</span><span class="special">(</span><span class="identifier">move</span><span class="special">(</span><span class="identifier">f_lock</span><span class="special">));</span> 2887</pre> 2888</div> 2889<div class="section"> 2890<div class="titlepage"><div><div><h4 class="title"> 2891<a name="interprocess.synchronization_mechanisms.file_lock.file_lock_not_thread_safe"></a><a class="link" href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.file_lock.file_lock_not_thread_safe" title="Caution: Synchronization limitations">Caution: 2892 Synchronization limitations</a> 2893</h4></div></div></div> 2894<p> 2895 If you plan to use file locks just like named mutexes, be careful, because 2896 portable file locks have synchronization limitations, mainly because different 2897 implementations (POSIX, Windows) offer different guarantees. Interprocess 2898 file locks have the following limitations: 2899 </p> 2900<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 2901<li class="listitem"> 2902 It's unspecified if a <code class="computeroutput"><span class="identifier">file_lock</span></code> 2903 synchronizes <span class="bold"><strong>two threads from the same process</strong></span>. 2904 </li> 2905<li class="listitem"> 2906 It's unspecified if a process can use two <code class="computeroutput"><span class="identifier">file_lock</span></code> 2907 objects pointing to the same file. 2908 </li> 2909</ul></div> 2910<p> 2911 The first limitation comes mainly from POSIX, since a file handle is a 2912 per-process attribute and not a per-thread attribute. This means that if 2913 a thread uses a <code class="computeroutput"><span class="identifier">file_lock</span></code> 2914 object to lock a file, other threads will see the file as locked. Windows 2915 file locking mechanism, on the other hand, offer thread-synchronization 2916 guarantees so a thread trying to lock the already locked file, would block. 2917 </p> 2918<p> 2919 The second limitation comes from the fact that file locking synchronization 2920 state is tied with a single file descriptor in Windows. This means that 2921 if two <code class="computeroutput"><span class="identifier">file_lock</span></code> objects 2922 are created pointing to the same file, no synchronization is guaranteed. 2923 In POSIX, when two file descriptors are used to lock a file if a descriptor 2924 is closed, all file locks set by the calling process are cleared. 2925 </p> 2926<p> 2927 To sum up, if you plan to use portable file locking in your processes, 2928 use the following restrictions: 2929 </p> 2930<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 2931<li class="listitem"> 2932 <span class="bold"><strong>For each file, use a single <code class="computeroutput"><span class="identifier">file_lock</span></code> 2933 object per process.</strong></span> 2934 </li> 2935<li class="listitem"> 2936 <span class="bold"><strong>Use the same thread to lock and unlock a file.</strong></span> 2937 </li> 2938<li class="listitem"> 2939 If you are using a std::fstream/native file handle to write to the 2940 file while using file locks on that file, <span class="bold"><strong>don't 2941 close the file before releasing all the locks of the file.</strong></span> 2942 </li> 2943</ul></div> 2944</div> 2945<div class="section"> 2946<div class="titlepage"><div><div><h4 class="title"> 2947<a name="interprocess.synchronization_mechanisms.file_lock.file_lock_careful_iostream"></a><a class="link" href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.file_lock.file_lock_careful_iostream" title="Be Careful With Iostream Writing">Be 2948 Careful With Iostream Writing</a> 2949</h4></div></div></div> 2950<p> 2951 As we've seen file locking can be useful to synchronize two processes, 2952 but <span class="bold"><strong>make sure data is written to the file</strong></span> 2953 before unlocking the file lock. Take in care that iostream classes do some 2954 kind of buffering, so if you want to make sure that other processes can 2955 see the data you've written, you have the following alternatives: 2956 </p> 2957<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 2958<li class="listitem"> 2959 Use native file functions (read()/write() in Unix systems and ReadFile/WriteFile 2960 in Windows systems) instead of iostream. 2961 </li> 2962<li class="listitem"> 2963 Flush data before unlocking the file lock in writers using <code class="computeroutput"><span class="identifier">fflush</span></code> if you are using standard 2964 C functions or the <code class="computeroutput"><span class="identifier">flush</span><span class="special">()</span></code> member function when using C++ iostreams. 2965 In windows you can't even use another class to access the same file. 2966 </li> 2967</ul></div> 2968<pre class="programlisting"><span class="comment">//...</span> 2969 2970<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">;</span> 2971<span class="comment">//This process writes the file</span> 2972<span class="comment">// ...</span> 2973<span class="comment">//Open the file lock</span> 2974<span class="identifier">fstream</span> <span class="identifier">file</span><span class="special">(</span><span class="string">"my_file"</span><span class="special">)</span> 2975<span class="identifier">file_lock</span> <span class="identifier">f_lock</span><span class="special">(</span><span class="string">"my_lock_file"</span><span class="special">);</span> 2976 2977<span class="special">{</span> 2978 <span class="identifier">scoped_lock</span><span class="special"><</span><span class="identifier">file_lock</span><span class="special">></span> <span class="identifier">e_lock</span><span class="special">(</span><span class="identifier">f_lock</span><span class="special">);</span> 2979 2980 <span class="comment">//Now write the file...</span> 2981 2982 <span class="comment">//Flush data before unlocking the exclusive lock</span> 2983 <span class="identifier">file</span><span class="special">.</span><span class="identifier">flush</span><span class="special">();</span> 2984<span class="special">}</span> 2985</pre> 2986</div> 2987</div> 2988<div class="section"> 2989<div class="titlepage"><div><div><h3 class="title"> 2990<a name="interprocess.synchronization_mechanisms.message_queue"></a><a class="link" href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.message_queue" title="Message Queue">Message 2991 Queue</a> 2992</h3></div></div></div> 2993<div class="toc"><dl class="toc"> 2994<dt><span class="section"><a href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.message_queue.message_queue_whats_a_mq">What's 2995 A Message Queue?</a></span></dt> 2996<dt><span class="section"><a href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.message_queue.message_queue_example">Using 2997 a message queue</a></span></dt> 2998</dl></div> 2999<div class="section"> 3000<div class="titlepage"><div><div><h4 class="title"> 3001<a name="interprocess.synchronization_mechanisms.message_queue.message_queue_whats_a_mq"></a><a class="link" href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.message_queue.message_queue_whats_a_mq" title="What's A Message Queue?">What's 3002 A Message Queue?</a> 3003</h4></div></div></div> 3004<p> 3005 A message queue is similar to a list of messages. Threads can put messages 3006 in the queue and they can also remove messages from the queue. Each message 3007 can have also a <span class="bold"><strong>priority</strong></span> so that higher 3008 priority messages are read before lower priority messages. Each message 3009 has some attributes: 3010 </p> 3011<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 3012<li class="listitem"> 3013 A priority. 3014 </li> 3015<li class="listitem"> 3016 The length of the message. 3017 </li> 3018<li class="listitem"> 3019 The data (if length is bigger than 0). 3020 </li> 3021</ul></div> 3022<p> 3023 A thread can send a message to or receive a message from the message queue 3024 using 3 methods: 3025 </p> 3026<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 3027<li class="listitem"> 3028 <span class="bold"><strong>Blocking</strong></span>: If the message queue is 3029 full when sending or the message queue is empty when receiving, the 3030 thread is blocked until there is room for a new message or there is 3031 a new message. 3032 </li> 3033<li class="listitem"> 3034 <span class="bold"><strong>Try</strong></span>: If the message queue is full 3035 when sending or the message queue is empty when receiving, the thread 3036 returns immediately with an error. 3037 </li> 3038<li class="listitem"> 3039 <span class="bold"><strong>Timed</strong></span>: If the message queue is full 3040 when sending or the message queue is empty when receiving, the thread 3041 retries the operation until succeeds (returning successful state) or 3042 a timeout is reached (returning a failure). 3043 </li> 3044</ul></div> 3045<p> 3046 A message queue <span class="bold"><strong>just copies raw bytes between processes</strong></span> 3047 and does not send objects. This means that if we want to send an object 3048 using a message queue <span class="bold"><strong>the object must be binary serializable</strong></span>. 3049 For example, we can send integers between processes but <span class="bold"><strong>not</strong></span> 3050 a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span></code>. You should use <span class="bold"><strong>Boost.Serialization</strong></span> 3051 or use advanced <span class="bold"><strong>Boost.Interprocess</strong></span> mechanisms 3052 to send complex data between processes. 3053 </p> 3054<p> 3055 The <span class="bold"><strong>Boost.Interprocess</strong></span> message queue is 3056 a named interprocess communication: the message queue is created with a 3057 name and it's opened with a name, just like a file. When creating a message 3058 queue, the user must specify the maximum message size and the maximum message 3059 number that the message queue can store. These parameters will define the 3060 resources (for example the size of the shared memory used to implement 3061 the message queue if shared memory is used). 3062 </p> 3063<pre class="programlisting"><span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">;</span> 3064<span class="comment">//Create a message_queue. If the queue</span> 3065<span class="comment">//exists throws an exception</span> 3066<span class="identifier">message_queue</span> <span class="identifier">mq</span> 3067 <span class="special">(</span><span class="identifier">create_only</span> <span class="comment">//only create</span> 3068 <span class="special">,</span><span class="string">"message_queue"</span> <span class="comment">//name</span> 3069 <span class="special">,</span><span class="number">100</span> <span class="comment">//max message number</span> 3070 <span class="special">,</span><span class="number">100</span> <span class="comment">//max message size</span> 3071 <span class="special">);</span> 3072</pre> 3073<pre class="programlisting"><span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">;</span> 3074<span class="comment">//Creates or opens a message_queue. If the queue</span> 3075<span class="comment">//does not exist creates it, otherwise opens it.</span> 3076<span class="comment">//Message number and size are ignored if the queue</span> 3077<span class="comment">//is opened</span> 3078<span class="identifier">message_queue</span> <span class="identifier">mq</span> 3079 <span class="special">(</span><span class="identifier">open_or_create</span> <span class="comment">//open or create</span> 3080 <span class="special">,</span><span class="string">"message_queue"</span> <span class="comment">//name</span> 3081 <span class="special">,</span><span class="number">100</span> <span class="comment">//max message number</span> 3082 <span class="special">,</span><span class="number">100</span> <span class="comment">//max message size</span> 3083 <span class="special">);</span> 3084</pre> 3085<pre class="programlisting"><span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">;</span> 3086<span class="comment">//Opens a message_queue. If the queue</span> 3087<span class="comment">//does not exist throws an exception.</span> 3088<span class="identifier">message_queue</span> <span class="identifier">mq</span> 3089 <span class="special">(</span><span class="identifier">open_only</span> <span class="comment">//only open</span> 3090 <span class="special">,</span><span class="string">"message_queue"</span> <span class="comment">//name</span> 3091 <span class="special">);</span> 3092</pre> 3093<p> 3094 The message queue is explicitly removed calling the static <code class="computeroutput"><span class="identifier">remove</span></code> function: 3095 </p> 3096<pre class="programlisting"><span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">;</span> 3097<span class="identifier">message_queue</span><span class="special">::</span><span class="identifier">remove</span><span class="special">(</span><span class="string">"message_queue"</span><span class="special">);</span> 3098</pre> 3099<p> 3100 The function can fail if the message queue is still being used by any process. 3101 </p> 3102</div> 3103<div class="section"> 3104<div class="titlepage"><div><div><h4 class="title"> 3105<a name="interprocess.synchronization_mechanisms.message_queue.message_queue_example"></a><a class="link" href="synchronization_mechanisms.html#interprocess.synchronization_mechanisms.message_queue.message_queue_example" title="Using a message queue">Using 3106 a message queue</a> 3107</h4></div></div></div> 3108<p> 3109 To use a message queue you must include the following header: 3110 </p> 3111<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">interprocess</span><span class="special">/</span><span class="identifier">ipc</span><span class="special">/</span><span class="identifier">message_queue</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 3112</pre> 3113<p> 3114 In the following example, the first process creates the message queue, 3115 and writes an array of integers on it. The other process just reads the 3116 array and checks that the sequence number is correct. This is the first 3117 process: 3118 </p> 3119<p> 3120</p> 3121<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">interprocess</span><span class="special">/</span><span class="identifier">ipc</span><span class="special">/</span><span class="identifier">message_queue</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 3122<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">iostream</span><span class="special">></span> 3123<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">vector</span><span class="special">></span> 3124 3125<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">;</span> 3126 3127<span class="keyword">int</span> <span class="identifier">main</span> <span class="special">()</span> 3128<span class="special">{</span> 3129 <span class="keyword">try</span><span class="special">{</span> 3130 <span class="comment">//Erase previous message queue</span> 3131 <span class="identifier">message_queue</span><span class="special">::</span><span class="identifier">remove</span><span class="special">(</span><span class="string">"message_queue"</span><span class="special">);</span> 3132 3133 <span class="comment">//Create a message_queue.</span> 3134 <span class="identifier">message_queue</span> <span class="identifier">mq</span> 3135 <span class="special">(</span><span class="identifier">create_only</span> <span class="comment">//only create</span> 3136 <span class="special">,</span><span class="string">"message_queue"</span> <span class="comment">//name</span> 3137 <span class="special">,</span><span class="number">100</span> <span class="comment">//max message number</span> 3138 <span class="special">,</span><span class="keyword">sizeof</span><span class="special">(</span><span class="keyword">int</span><span class="special">)</span> <span class="comment">//max message size</span> 3139 <span class="special">);</span> 3140 3141 <span class="comment">//Send 100 numbers</span> 3142 <span class="keyword">for</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">i</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span> <span class="identifier">i</span> <span class="special"><</span> <span class="number">100</span><span class="special">;</span> <span class="special">++</span><span class="identifier">i</span><span class="special">){</span> 3143 <span class="identifier">mq</span><span class="special">.</span><span class="identifier">send</span><span class="special">(&</span><span class="identifier">i</span><span class="special">,</span> <span class="keyword">sizeof</span><span class="special">(</span><span class="identifier">i</span><span class="special">),</span> <span class="number">0</span><span class="special">);</span> 3144 <span class="special">}</span> 3145 <span class="special">}</span> 3146 <span class="keyword">catch</span><span class="special">(</span><span class="identifier">interprocess_exception</span> <span class="special">&</span><span class="identifier">ex</span><span class="special">){</span> 3147 <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="identifier">ex</span><span class="special">.</span><span class="identifier">what</span><span class="special">()</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> 3148 <span class="keyword">return</span> <span class="number">1</span><span class="special">;</span> 3149 <span class="special">}</span> 3150 3151 <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span> 3152<span class="special">}</span> 3153</pre> 3154<p> 3155 </p> 3156<p> 3157 This is the second process: 3158 </p> 3159<p> 3160</p> 3161<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">interprocess</span><span class="special">/</span><span class="identifier">ipc</span><span class="special">/</span><span class="identifier">message_queue</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 3162<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">iostream</span><span class="special">></span> 3163<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">vector</span><span class="special">></span> 3164 3165<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">;</span> 3166 3167<span class="keyword">int</span> <span class="identifier">main</span> <span class="special">()</span> 3168<span class="special">{</span> 3169 <span class="keyword">try</span><span class="special">{</span> 3170 <span class="comment">//Open a message queue.</span> 3171 <span class="identifier">message_queue</span> <span class="identifier">mq</span> 3172 <span class="special">(</span><span class="identifier">open_only</span> <span class="comment">//only create</span> 3173 <span class="special">,</span><span class="string">"message_queue"</span> <span class="comment">//name</span> 3174 <span class="special">);</span> 3175 3176 <span class="keyword">unsigned</span> <span class="keyword">int</span> <span class="identifier">priority</span><span class="special">;</span> 3177 <span class="identifier">message_queue</span><span class="special">::</span><span class="identifier">size_type</span> <span class="identifier">recvd_size</span><span class="special">;</span> 3178 3179 <span class="comment">//Receive 100 numbers</span> 3180 <span class="keyword">for</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">i</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span> <span class="identifier">i</span> <span class="special"><</span> <span class="number">100</span><span class="special">;</span> <span class="special">++</span><span class="identifier">i</span><span class="special">){</span> 3181 <span class="keyword">int</span> <span class="identifier">number</span><span class="special">;</span> 3182 <span class="identifier">mq</span><span class="special">.</span><span class="identifier">receive</span><span class="special">(&</span><span class="identifier">number</span><span class="special">,</span> <span class="keyword">sizeof</span><span class="special">(</span><span class="identifier">number</span><span class="special">),</span> <span class="identifier">recvd_size</span><span class="special">,</span> <span class="identifier">priority</span><span class="special">);</span> 3183 <span class="keyword">if</span><span class="special">(</span><span class="identifier">number</span> <span class="special">!=</span> <span class="identifier">i</span> <span class="special">||</span> <span class="identifier">recvd_size</span> <span class="special">!=</span> <span class="keyword">sizeof</span><span class="special">(</span><span class="identifier">number</span><span class="special">))</span> 3184 <span class="keyword">return</span> <span class="number">1</span><span class="special">;</span> 3185 <span class="special">}</span> 3186 <span class="special">}</span> 3187 <span class="keyword">catch</span><span class="special">(</span><span class="identifier">interprocess_exception</span> <span class="special">&</span><span class="identifier">ex</span><span class="special">){</span> 3188 <span class="identifier">message_queue</span><span class="special">::</span><span class="identifier">remove</span><span class="special">(</span><span class="string">"message_queue"</span><span class="special">);</span> 3189 <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="identifier">ex</span><span class="special">.</span><span class="identifier">what</span><span class="special">()</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> 3190 <span class="keyword">return</span> <span class="number">1</span><span class="special">;</span> 3191 <span class="special">}</span> 3192 <span class="identifier">message_queue</span><span class="special">::</span><span class="identifier">remove</span><span class="special">(</span><span class="string">"message_queue"</span><span class="special">);</span> 3193 <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span> 3194<span class="special">}</span> 3195</pre> 3196<p> 3197 </p> 3198<p> 3199 To know more about this class and all its operations, please see the <code class="computeroutput"><a class="link" href="../boost/interprocess/message_queue.html" title="Type definition message_queue">message_queue</a></code> class 3200 reference. 3201 </p> 3202</div> 3203</div> 3204</div> 3205<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 3206<td align="left"></td> 3207<td align="right"><div class="copyright-footer">Copyright © 2005-2015 Ion Gaztanaga<p> 3208 Distributed under the Boost Software License, Version 1.0. (See accompanying 3209 file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) 3210 </p> 3211</div></td> 3212</tr></table> 3213<hr> 3214<div class="spirit-nav"> 3215<a accesskey="p" href="offset_ptr.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../interprocess.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="managed_memory_segments.html"><img src="../../../doc/src/images/next.png" alt="Next"></a> 3216</div> 3217</body> 3218</html> 3219
