<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<title>Wt: Wt::SyncLock< Lock > Class Template Reference</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
$(document).ready(function() { searchBox.OnSelectItem(0); });
</script>
</head>
<body>
<div id="top"><!-- do not remove this div! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td style="padding-left: 0.5em;">
<div id="projectname">Wt
 <span id="projectnumber">3.2.3</span>
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- Generated by Doxygen 1.7.5.1 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
<div id="navrow1" class="tabs">
<ul class="tablist">
<li><a href="index.html"><span>Main Page</span></a></li>
<li><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="modules.html"><span>Modules</span></a></li>
<li><a href="namespaces.html"><span>Namespaces</span></a></li>
<li class="current"><a href="annotated.html"><span>Classes</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
<li>
<div id="MSearchBox" class="MSearchBoxInactive">
<span class="left">
<img id="MSearchSelect" src="search/mag_sel.png"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
alt=""/>
<input type="text" id="MSearchField" value="Search" accesskey="S"
onfocus="searchBox.OnSearchFieldFocus(true)"
onblur="searchBox.OnSearchFieldFocus(false)"
onkeyup="searchBox.OnSearchFieldChange(event)"/>
</span><span class="right">
<a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
</span>
</div>
</li>
</ul>
</div>
<div id="navrow2" class="tabs2">
<ul class="tablist">
<li><a href="annotated.html"><span>Class List</span></a></li>
<li><a href="inherits.html"><span>Class Hierarchy</span></a></li>
<li><a href="functions.html"><span>Class Members</span></a></li>
</ul>
</div>
<div id="nav-path" class="navpath">
<ul>
<li class="navelem"><a class="el" href="namespaceWt.html">Wt</a> </li>
<li class="navelem"><a class="el" href="classWt_1_1SyncLock.html">SyncLock</a> </li>
</ul>
</div>
</div>
<div class="header">
<div class="summary">
<a href="#pub-methods">Public Member Functions</a> </div>
<div class="headertitle">
<div class="title">Wt::SyncLock< Lock > Class Template Reference</div> </div>
</div>
<div class="contents">
<!-- doxytag: class="Wt::SyncLock" -->
<p>An dead-lock avoidance adaptor for a Boost mutex lock.
<a href="classWt_1_1SyncLock.html#details">More...</a></p>
<p><code>#include <Wt/SyncLock></code></p>
<p><a href="classWt_1_1SyncLock-members.html">List of all members.</a></p>
<table class="memberdecls">
<tr><td colspan="2"><h2><a name="pub-methods"></a>
Public Member Functions</h2></td></tr>
<tr><td class="memTemplParams" colspan="2">template<class Mutex > </td></tr>
<tr><td class="memTemplItemLeft" align="right" valign="top"> </td><td class="memTemplItemRight" valign="bottom"><a class="el" href="classWt_1_1SyncLock.html#aa5851450deb27dcabcf963e40a643606">SyncLock</a> (Mutex &mutex)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Creates a RIIA lock. <a href="#aa5851450deb27dcabcf963e40a643606"></a><br/></td></tr>
<tr><td class="memTemplParams" colspan="2">template<class Mutex > </td></tr>
<tr><td class="memTemplItemLeft" align="right" valign="top"> </td><td class="memTemplItemRight" valign="bottom"><a class="el" href="classWt_1_1SyncLock.html#acdf8cecc66605cae95c090d29f043840">SyncLock</a> (Mutex &mutex, boost::defer_lock_t)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Creates a RIIA lock, but defers taking the lock. <a href="#acdf8cecc66605cae95c090d29f043840"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="classWt_1_1SyncLock.html#a191047ad7895339eecde9eb230be25ea">lock</a> ()</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Tries to acquire the lock, blocking while waiting. <a href="#a191047ad7895339eecde9eb230be25ea"></a><br/></td></tr>
</table>
<hr/><a name="details" id="details"></a><h2>Detailed Description</h2>
<div class="textblock"><h3>template<class Lock><br/>
class Wt::SyncLock< Lock ></h3>
<p>An dead-lock avoidance adaptor for a Boost mutex lock. </p>
<p>A SyncLock adapts a Boost mutex lock (such as boost::mutex::scoped_lock), and provides the same API as the original lock (it derives from it).</p>
<p>Just as can be expected by a lock, a call to <a class="el" href="classWt_1_1SyncLock.html#a191047ad7895339eecde9eb230be25ea" title="Tries to acquire the lock, blocking while waiting.">lock()</a> will block until the thread has exclusive access to the mutex.</p>
<p>While waiting to acquire the lock, however, the current <a class="el" href="classWt_1_1WApplication.html" title="Represents an application instance for a single session.">Wt::WApplication</a> lock, may be temporarily released in favor of another helper thread trying to acquire the application lock. Thus, you need to be aware that when the lock is taken, some other thread may have modified the current application state.</p>
<p>A sync lock is useful in the context of a deployment where multiple (or all) <a class="el" href="classWt_1_1WApplication.html" title="Represents an application instance for a single session.">WApplication</a> instances are running in a single process and communicating with each other (such as the built-in httpd). Then, this lock adaptor helps in avoiding a dead-lock situation when applications wants to access a shared resource protected by a mutex, which communicates to other applications while taking their update lock. In that case, it is likely that you will also want to iterate over all "registered" applications while holding the global mutex, and this creates a natural dead-lock scenario because you have two mutexes (global mutex, application mutex) which are sequentially aquired in a different order:</p>
<ul>
<li>application mutex -> global mutex, during an application request</li>
<li>global mutex -> application mutex, while propagating events to applications</li>
</ul>
<p>The altered behaviour of a call by application <em>A</em> to <a class="el" href="classWt_1_1SyncLock.html#a191047ad7895339eecde9eb230be25ea" title="Tries to acquire the lock, blocking while waiting.">lock()</a> is that this application <em>A</em>'s state may be updated by another thread (e.g. serving application <em>B</em>), which tries to take <em>A</em>'s update lock.</p>
<p>The following conventional locking code: </p>
<div class="fragment"><pre class="fragment"> boost::recursive_mutex::scoped_lock <a class="code" href="classWt_1_1SyncLock.html#a191047ad7895339eecde9eb230be25ea" title="Tries to acquire the lock, blocking while waiting.">lock</a>(mutex_);
</pre></div><p> is updated to a sync lock, by doing: </p>
<div class="fragment"><pre class="fragment"> <a class="code" href="classWt_1_1SyncLock.html" title="An dead-lock avoidance adaptor for a Boost mutex lock.">Wt::SyncLock<boost::recursive_mutex::scoped_lock></a> <a class="code" href="classWt_1_1SyncLock.html#a191047ad7895339eecde9eb230be25ea" title="Tries to acquire the lock, blocking while waiting.">lock</a>(mutex_);
</pre></div> </div><hr/><h2>Constructor & Destructor Documentation</h2>
<a class="anchor" id="aa5851450deb27dcabcf963e40a643606"></a><!-- doxytag: member="Wt::SyncLock::SyncLock" ref="aa5851450deb27dcabcf963e40a643606" args="(Mutex &mutex)" -->
<div class="memitem">
<div class="memproto">
<div class="memtemplate">
template<class Lock> </div>
<div class="memtemplate">
template<class Mutex > </div>
<table class="memname">
<tr>
<td class="memname"><a class="el" href="classWt_1_1SyncLock.html">Wt::SyncLock</a>< Lock >::<a class="el" href="classWt_1_1SyncLock.html">SyncLock</a> </td>
<td>(</td>
<td class="paramtype">Mutex & </td>
<td class="paramname"><em>mutex</em></td><td>)</td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Creates a RIIA lock. </p>
<p>Initializes and acquires exclusive access to the <code>mutex</code>. </p>
</div>
</div>
<a class="anchor" id="acdf8cecc66605cae95c090d29f043840"></a><!-- doxytag: member="Wt::SyncLock::SyncLock" ref="acdf8cecc66605cae95c090d29f043840" args="(Mutex &mutex, boost::defer_lock_t)" -->
<div class="memitem">
<div class="memproto">
<div class="memtemplate">
template<class Lock> </div>
<div class="memtemplate">
template<class Mutex > </div>
<table class="memname">
<tr>
<td class="memname"><a class="el" href="classWt_1_1SyncLock.html">Wt::SyncLock</a>< Lock >::<a class="el" href="classWt_1_1SyncLock.html">SyncLock</a> </td>
<td>(</td>
<td class="paramtype">Mutex & </td>
<td class="paramname"><em>mutex</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">boost::defer_lock_t </td>
<td class="paramname"> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Creates a RIIA lock, but defers taking the lock. </p>
<p>Initialize the lock but defers taking the lock.</p>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="classWt_1_1SyncLock.html#a191047ad7895339eecde9eb230be25ea" title="Tries to acquire the lock, blocking while waiting.">lock()</a> </dd></dl>
</div>
</div>
<hr/><h2>Member Function Documentation</h2>
<a class="anchor" id="a191047ad7895339eecde9eb230be25ea"></a><!-- doxytag: member="Wt::SyncLock::lock" ref="a191047ad7895339eecde9eb230be25ea" args="()" -->
<div class="memitem">
<div class="memproto">
<div class="memtemplate">
template<class Lock> </div>
<table class="memname">
<tr>
<td class="memname">void <a class="el" href="classWt_1_1SyncLock.html">Wt::SyncLock</a>< Lock >::lock </td>
<td>(</td>
<td class="paramname"></td><td>)</td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Tries to acquire the lock, blocking while waiting. </p>
<p>While an application <em>A</em> is waiting for the lock, its state may be updated by another application: another application <em>B</em> can succesfully take <em>A's</em> <a class="el" href="classWt_1_1WApplication_1_1UpdateLock.html">update lock</a>.</p>
<p>Therefore you need to be prepared to deal with application state changes while waiting for the lock. </p>
</div>
</div>
</div>
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark"> </span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark"> </span>Classes</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark"> </span>Namespaces</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark"> </span>Files</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark"> </span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark"> </span>Variables</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(6)"><span class="SelectionMark"> </span>Typedefs</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(7)"><span class="SelectionMark"> </span>Enumerations</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(8)"><span class="SelectionMark"> </span>Enumerator</a></div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0"
name="MSearchResults" id="MSearchResults">
</iframe>
</div>
<hr size="1"><address style="text-align: right; margin: 3px"><small>
Generated on Thu Nov 1 2012 for <a href="http://www.webtoolkit.eu/wt">the
C++ Web Toolkit (Wt)</a> by <a
href="http://www.doxygen.org/index.html"><img src="doxygen.png"
alt="doxygen" border="0" style="vertical-align: middle; display:
inline-block; height: 2em"></a> 1.7.5.1</small></address>
</body>
</html>
