1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html><head><meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
<title>Loki: Loki::LevelMutex< MutexPolicy, DefaultLevel, ErrorPolicy, WaitPolicy > Class Template Reference</title>
<link href="tabs.css" rel="stylesheet" type="text/css">
<link href="doxygen.css" rel="stylesheet" type="text/css">
</head><body>
<!-- Generated by Doxygen 1.5.8 -->
<div class="navigation" id="top">
<div class="tabs">
<ul>
<li><a href="main.html"><span>Main Page</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>
<form action="search.php" method="get">
<table cellspacing="0" cellpadding="0" border="0">
<tr>
<td><label> <u>S</u>earch for </label></td>
<td><input type="text" name="query" value="" size="20" accesskey="s"/></td>
</tr>
</table>
</form>
</li>
</ul>
</div>
<div class="tabs">
<ul>
<li><a href="annotated.html"><span>Class List</span></a></li>
<li><a href="classes.html"><span>Class Index</span></a></li>
<li><a href="hierarchy.html"><span>Class Hierarchy</span></a></li>
<li><a href="functions.html"><span>Class Members</span></a></li>
</ul>
</div>
<div class="navpath"><a class="el" href="a00192.html">Loki</a>::<a class="el" href="a00070.html">LevelMutex</a>
</div>
</div>
<div class="contents">
<h1>Loki::LevelMutex< MutexPolicy, DefaultLevel, ErrorPolicy, WaitPolicy > Class Template Reference</h1><!-- doxytag: class="Loki::LevelMutex" --><!-- doxytag: inherits="Loki::LevelMutexInfo" --><code>#include <LevelMutex.h></code>
<p>
<div class="dynheader">
Inheritance diagram for Loki::LevelMutex< MutexPolicy, DefaultLevel, ErrorPolicy, WaitPolicy >:</div>
<div class="dynsection">
<center><font size="2">[<a target="top" href="graph_legend.html">legend</a>]</font></center></div>
<div class="dynheader">
Collaboration diagram for Loki::LevelMutex< MutexPolicy, DefaultLevel, ErrorPolicy, WaitPolicy >:</div>
<div class="dynsection">
<center><font size="2">[<a target="top" href="graph_legend.html">legend</a>]</font></center></div>
<p>
<a href="a00336.html">List of all members.</a><table border="0" cellpadding="0" cellspacing="0">
<tr><td></td></tr>
<tr><td colspan="2"><br><h2>Public Member Functions</h2></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top"> </td><td class="memItemRight" valign="bottom"><a class="el" href="a00070.html#e770e4e5ec2fa120d016eb23b56d988b">LevelMutex</a> (unsigned int level=DefaultLevel)</td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top"><a class="anchor" name="b1670bea535a28e439a991fad4056ec2"></a><!-- doxytag: member="Loki::LevelMutex::~LevelMutex" ref="b1670bea535a28e439a991fad4056ec2" args="(void)" -->
</td><td class="memItemRight" valign="bottom"><a class="el" href="a00070.html#b1670bea535a28e439a991fad4056ec2">~LevelMutex</a> (void)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">The destructor. <br></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top">const volatile MutexPolicy & </td><td class="memItemRight" valign="bottom"><a class="el" href="a00070.html#9a9abaa6b4148b9b02bd279615872e90">GetMutexPolicy</a> (void) const volatile</td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top">virtual MutexErrors::Type </td><td class="memItemRight" valign="bottom"><a class="el" href="a00070.html#042a7938dafd6f149cfd7da46478c0c9">TryLock</a> (void) volatile</td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top">virtual MutexErrors::Type </td><td class="memItemRight" valign="bottom"><a class="el" href="a00070.html#95d3742db062548201986f482a9c9b9d">Lock</a> (void) volatile</td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top">virtual MutexErrors::Type </td><td class="memItemRight" valign="bottom"><a class="el" href="a00070.html#d4ac0c2a33ff3d98ec0a83f70ce145da">Lock</a> (unsigned int milliSeconds) volatile</td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top">virtual MutexErrors::Type </td><td class="memItemRight" valign="bottom"><a class="el" href="a00070.html#553a379257af57ceaef9ed48b0dc8b70">Unlock</a> (void) volatile</td></tr>
</table>
<hr><a name="_details"></a><h2>Detailed Description</h2>
<h3>template<class MutexPolicy, unsigned int DefaultLevel, class ErrorPolicy = ::Loki::ThrowOnBadDesignMutexError, class WaitPolicy = ::Loki::NoMutexWait><br>
class Loki::LevelMutex< MutexPolicy, DefaultLevel, ErrorPolicy, WaitPolicy ></h3>
Levelized mutex class prevents deadlocks by requiring programs to lock mutexes in the same order, and unlock them in reverse order. This is accomplished by forcing each mutex to have a level and forcing code to lock mutexes with higher levels before locking mutexes at lower levels. If you want to lock several mutexes, they must be locked in decreasing order by level, or if they are all of the same level, then locked by <a class="el" href="a00071.html#dde650eae1cad8b4723e68cdb9130283">LevelMutex::MultiLock</a>.<p>
<dl class="user" compact><dt><b>Features</b></dt><dd><ul>
<li>Immune: Very unlikely to deadlock since all mutexes are locked in the same order and unlocked in reverse order.</li><li>Scalable: Can handle any number of mutexes.</li><li>Efficient: Many operations occur in constant time, and most operations require no more than O(m) steps.</li><li>Exception safe: All operations provide strong safety or don't throw.</li><li>Extendable: Can work with existing mutexes through policy-based design.</li><li>Easily Extended: Derived classes only need to implement 5 functions and a mutex to get all the features of this class.</li><li>Re-Entrant: Allows for re-entrancy even if mutexes in policy classes don't.</li><li>Cost-Free: No resource allocations occur in <a class="el" href="a00070.html">LevelMutex</a> - although user-defined policy classes may allocate resources.</li><li>Compact: Each <a class="el" href="a00070.html">LevelMutex</a> object is small.</li><li>Portable: As long as your compiler and libraries can meet the requirements.</li><li>Robust: Maintains data integrity even if exceptions occur in policy classes.</li><li>Affording: Several functions provide information about a mutex which allows client code to easily choose correct actions.</li></ul>
</dd></dl>
<dl class="user" compact><dt><b>Requirements</b></dt><dd><ul>
<li>Your compiler must allow for thread-specific data.</li><li>You must have a threading or mutex library.</li></ul>
</dd></dl>
<dl class="user" compact><dt><b>Policy-Based Design</b></dt><dd>This class hosts 3 policies and a default level. The policy-based design allows users to write their own policies to extend the behaviors of <a class="el" href="a00070.html">LevelMutex</a>. The paragraphs below say how to design a class for each policy.<ul>
<li>MutexPolicy The mutex policy class.</li><li>defaultLevel A level for existing client code that calls a default constructor.</li><li>ErrorPolicy How the mutex should handle error conditions.</li><li>WaitPolicy Whether a thread should wait, and how long in some internal loops.</li></ul>
</dd></dl>
<dl class="user" compact><dt><b>MutexPolicy</b></dt><dd>A policy class that wraps a low-level mutex. <a class="el" href="a00192.html">Loki</a> provides two policy classes for the actual mutex (<a class="el" href="a00133.html">SpinLevelMutex</a> and <a class="el" href="a00126.html">SleepLevelMutex</a>), both of which wrap either pthreads or the Windows CRITICAL_SECTION. If you want to use a mutex mechanism besides one of those, then all you have to do is provide a class which wraps the mutex and implements these functions. explicit SpinLevelMutex( unsigned int level ); virtual ~SpinLevelMutex( void ); virtual MutexErrors::Type <a class="el" href="a00070.html#95d3742db062548201986f482a9c9b9d">Lock( void ) volatile</a>; virtual MutexErrors::Type <a class="el" href="a00070.html#042a7938dafd6f149cfd7da46478c0c9">TryLock( void ) volatile</a>; virtual MutexErrors::Type <a class="el" href="a00070.html#553a379257af57ceaef9ed48b0dc8b70">Unlock( void ) volatile</a>; Indeed, since the base class does most of the work, and provides all the interace and functionality to client classes, a derived class has very few requirements. It only needs to implement a single constructor, the destructor, some virtual functions, and whatever data members it requires. You don't actually need to declare those functions as virtual if the policy class is not a base or child class. In the parlance of design patterns, <a class="el" href="a00070.html">LevelMutex</a> is a Template, and the MutexPolicy is a Strategy.</dd></dl>
<dl class="user" compact><dt><b>DefaultLevel</b></dt><dd>The template class requires a default level to use inside the default constructor. Some existing code calls instantiates mutexes with a default constructor, so the mutex must know what level to use there. Please do not use zero or UnlockedLevel as the default level.</dd></dl>
<dl class="user" compact><dt><b>ErrorPolicy</b></dt><dd>This policy specifies how to handle error conditions. The mutexes can return errors, assert, or throw exceptions. I recommend that debug code use asserts, release code use exceptions, and unit-testing code just return errors. The error policy class only needs to implement one function: static MutexErrors::Type CheckError( MutexErrors::Type error, unsigned int level );</dd></dl>
<dl class="user" compact><dt><b>WaitPolicy</b></dt><dd>This states whether the mutex should wait within some tight internal loops, how the waiting is done, and for how long. A wait policy class could sleep, do nothing, check if other objects need attention, or check if the program received events or notices from the operating system. It only needs to implement one function: static void Wait( void );</dd></dl>
<dl class="user" compact><dt><b>Per-Function Usage</b></dt><dd>If you implement a function with a static local mutex, then you have to insure the function is not called from a lower level via call-backs, virtual functions in interface classes. If the function does get called from a lower level, you are setting up a potential deadlock. <a class="el" href="a00070.html">LevelMutex</a> will detect that by checking the current level and the local mutex's level, so it will refuse to lock the local mutex.</dd></dl>
<dl class="user" compact><dt><b>Per-Object Usage</b></dt><dd>If you use a mutex as a data member of an object to protect that object, then I recommend specifying which functions are volatile and which are not, and then only use the mutex within the volatile functions. You may also want to provide accessor functions so that client code can lock and unlock the mutex either to allow for calling multiple operations without having to lock and unlock before and after each operation, or so they can lock it along with several other objects at the same level.</dd></dl>
<dl class="user" compact><dt><b>Per-Class Usage</b></dt><dd>If you make a static data member within a class, you can use that to lock any resources shared by those objects, or to require threads to act on only one object at a time. You may also want to provide static accessor functions so that client code can lock several other resources at the same level. </dd></dl>
<hr><h2>Constructor & Destructor Documentation</h2>
<a class="anchor" name="e770e4e5ec2fa120d016eb23b56d988b"></a><!-- doxytag: member="Loki::LevelMutex::LevelMutex" ref="e770e4e5ec2fa120d016eb23b56d988b" args="(unsigned int level=DefaultLevel)" -->
<div class="memitem">
<div class="memproto">
<div class="memtemplate">
template<class MutexPolicy , unsigned int DefaultLevel, class ErrorPolicy = ::Loki::ThrowOnBadDesignMutexError, class WaitPolicy = ::Loki::NoMutexWait> </div>
<table class="memname">
<tr>
<td class="memname"><a class="el" href="a00070.html">Loki::LevelMutex</a>< MutexPolicy, DefaultLevel, ErrorPolicy, WaitPolicy >::<a class="el" href="a00070.html">LevelMutex</a> </td>
<td>(</td>
<td class="paramtype">unsigned int </td>
<td class="paramname"> <em>level</em> = <code>DefaultLevel</code> </td>
<td> ) </td>
<td><code> [inline, explicit]</code></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>
This constructor allows callers to replace the default level with another value. It also acts as the default constructor for existing code which uses default construction for mutexes. This is the only time the DefaultLevel template parameter gets used.
<p>References <a class="el" href="a00242.html#l00545">Loki::LevelMutexInfo::IsValid()</a>.</p>
<p>
<div class="dynheader">
Here is the call graph for this function:</div>
<div class="dynsection">
</div>
</div>
</div><p>
<hr><h2>Member Function Documentation</h2>
<a class="anchor" name="9a9abaa6b4148b9b02bd279615872e90"></a><!-- doxytag: member="Loki::LevelMutex::GetMutexPolicy" ref="9a9abaa6b4148b9b02bd279615872e90" args="(void) const volatile" -->
<div class="memitem">
<div class="memproto">
<div class="memtemplate">
template<class MutexPolicy , unsigned int DefaultLevel, class ErrorPolicy = ::Loki::ThrowOnBadDesignMutexError, class WaitPolicy = ::Loki::NoMutexWait> </div>
<table class="memname">
<tr>
<td class="memname">const volatile MutexPolicy& <a class="el" href="a00070.html">Loki::LevelMutex</a>< MutexPolicy, DefaultLevel, ErrorPolicy, WaitPolicy >::GetMutexPolicy </td>
<td>(</td>
<td class="paramtype">void </td>
<td class="paramname"> </td>
<td> ) </td>
<td> const volatile<code> [inline]</code></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>
These functions allow callers to access the mutex in case they need to modify specific values in the MutexPolicy (e.g. - sleep time, functors to call as tasks, etc...) There is one function for every combination of const and volatile qualifiers so callers get a reference to a MutexPolicy with the proper qualifiers.
</div>
</div><p>
<a class="anchor" name="d4ac0c2a33ff3d98ec0a83f70ce145da"></a><!-- doxytag: member="Loki::LevelMutex::Lock" ref="d4ac0c2a33ff3d98ec0a83f70ce145da" args="(unsigned int milliSeconds) volatile" -->
<div class="memitem">
<div class="memproto">
<div class="memtemplate">
template<class MutexPolicy , unsigned int DefaultLevel, class ErrorPolicy = ::Loki::ThrowOnBadDesignMutexError, class WaitPolicy = ::Loki::NoMutexWait> </div>
<table class="memname">
<tr>
<td class="memname">virtual MutexErrors::Type <a class="el" href="a00070.html">Loki::LevelMutex</a>< MutexPolicy, DefaultLevel, ErrorPolicy, WaitPolicy >::Lock </td>
<td>(</td>
<td class="paramtype">unsigned int </td>
<td class="paramname"> <em>milliSeconds</em> </td>
<td> ) </td>
<td> volatile<code> [inline, virtual]</code></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>
Attempts to lock mutex, but only waits for a limited amount of time before it gives up. Will return quickly if an error occurs before any attempt to lock. This may throw an exception if the lock failed or an error occurred - if that is what the error policy specifies. <dl compact><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>milliSeconds</em> </td><td>How long to wait. </td></tr>
</table>
</dl>
<dl class="return" compact><dt><b>Returns:</b></dt><dd>An error condition if any occurred, else Success. </dd></dl>
<p>Implements <a class="el" href="a00071.html#5782b9fd9734d95a38ff86ef9532c89b">Loki::LevelMutexInfo</a>.</p>
<p>References <a class="el" href="a00243.html#l00208">Loki::LevelMutexInfo::GetLevel()</a>, <a class="el" href="a00242.html#l00575">Loki::LevelMutexInfo::IsLockedByCurrentThread()</a>, <a class="el" href="a00242.html#l00545">Loki::LevelMutexInfo::IsValid()</a>, and <a class="el" href="a00242.html#l00653">Loki::LevelMutexInfo::PostLock()</a>.</p>
<p>
<div class="dynheader">
Here is the call graph for this function:</div>
<div class="dynsection">
</div>
</div>
</div><p>
<a class="anchor" name="95d3742db062548201986f482a9c9b9d"></a><!-- doxytag: member="Loki::LevelMutex::Lock" ref="95d3742db062548201986f482a9c9b9d" args="(void) volatile" -->
<div class="memitem">
<div class="memproto">
<div class="memtemplate">
template<class MutexPolicy , unsigned int DefaultLevel, class ErrorPolicy = ::Loki::ThrowOnBadDesignMutexError, class WaitPolicy = ::Loki::NoMutexWait> </div>
<table class="memname">
<tr>
<td class="memname">virtual MutexErrors::Type <a class="el" href="a00070.html">Loki::LevelMutex</a>< MutexPolicy, DefaultLevel, ErrorPolicy, WaitPolicy >::Lock </td>
<td>(</td>
<td class="paramtype">void </td>
<td class="paramname"> </td>
<td> ) </td>
<td> volatile<code> [inline, virtual]</code></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>
Blocking call will attempt to lock mutex and wait until it can lock. This may throw an exception if the lock failed or an error occurred - if that is what the error policy specifies. <dl class="return" compact><dt><b>Returns:</b></dt><dd>An error condition if any occurred, else Success. </dd></dl>
<p>Implements <a class="el" href="a00071.html#c0e21e08ee9974533a4da5008452bd04">Loki::LevelMutexInfo</a>.</p>
<p>References <a class="el" href="a00243.html#l00208">Loki::LevelMutexInfo::GetLevel()</a>, <a class="el" href="a00242.html#l00575">Loki::LevelMutexInfo::IsLockedByCurrentThread()</a>, <a class="el" href="a00242.html#l00545">Loki::LevelMutexInfo::IsValid()</a>, and <a class="el" href="a00242.html#l00653">Loki::LevelMutexInfo::PostLock()</a>.</p>
<p>
<div class="dynheader">
Here is the call graph for this function:</div>
<div class="dynsection">
</div>
</div>
</div><p>
<a class="anchor" name="042a7938dafd6f149cfd7da46478c0c9"></a><!-- doxytag: member="Loki::LevelMutex::TryLock" ref="042a7938dafd6f149cfd7da46478c0c9" args="(void) volatile" -->
<div class="memitem">
<div class="memproto">
<div class="memtemplate">
template<class MutexPolicy , unsigned int DefaultLevel, class ErrorPolicy = ::Loki::ThrowOnBadDesignMutexError, class WaitPolicy = ::Loki::NoMutexWait> </div>
<table class="memname">
<tr>
<td class="memname">virtual MutexErrors::Type <a class="el" href="a00070.html">Loki::LevelMutex</a>< MutexPolicy, DefaultLevel, ErrorPolicy, WaitPolicy >::TryLock </td>
<td>(</td>
<td class="paramtype">void </td>
<td class="paramname"> </td>
<td> ) </td>
<td> volatile<code> [inline, virtual]</code></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>
Tries to lock mutex, and returns immediately if mutex already locked by another thread. It will return immediately with a value of AlreadyLocked if the mutex was locked by a different thread. It may throw an exception or assert when errors occur if the ErrorPolicy class implements that behavior. <dl class="return" compact><dt><b>Returns:</b></dt><dd>An error condition if any occurred, else Success. </dd></dl>
<p>Implements <a class="el" href="a00071.html#32f89bf087b932de0cdd1151116779b4">Loki::LevelMutexInfo</a>.</p>
<p>References <a class="el" href="a00243.html#l00208">Loki::LevelMutexInfo::GetLevel()</a>, <a class="el" href="a00243.html#l00214">Loki::LevelMutexInfo::GetLockCount()</a>, <a class="el" href="a00242.html#l00545">Loki::LevelMutexInfo::IsValid()</a>, and <a class="el" href="a00242.html#l00653">Loki::LevelMutexInfo::PostLock()</a>.</p>
<p>
<div class="dynheader">
Here is the call graph for this function:</div>
<div class="dynsection">
</div>
</div>
</div><p>
<a class="anchor" name="553a379257af57ceaef9ed48b0dc8b70"></a><!-- doxytag: member="Loki::LevelMutex::Unlock" ref="553a379257af57ceaef9ed48b0dc8b70" args="(void) volatile" -->
<div class="memitem">
<div class="memproto">
<div class="memtemplate">
template<class MutexPolicy , unsigned int DefaultLevel, class ErrorPolicy = ::Loki::ThrowOnBadDesignMutexError, class WaitPolicy = ::Loki::NoMutexWait> </div>
<table class="memname">
<tr>
<td class="memname">virtual MutexErrors::Type <a class="el" href="a00070.html">Loki::LevelMutex</a>< MutexPolicy, DefaultLevel, ErrorPolicy, WaitPolicy >::Unlock </td>
<td>(</td>
<td class="paramtype">void </td>
<td class="paramname"> </td>
<td> ) </td>
<td> volatile<code> [inline, virtual]</code></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>
Unlocks the mutex, or returns an error condition. This may throw an exception if the lock failed or an error occurred - if that is what the error policy specifies. <dl class="return" compact><dt><b>Returns:</b></dt><dd>An error condition if any occurred, else Success. </dd></dl>
<p>Implements <a class="el" href="a00071.html#01c9af5cb0f6870585b864b4557e9242">Loki::LevelMutexInfo</a>.</p>
<p>References <a class="el" href="a00243.html#l00208">Loki::LevelMutexInfo::GetLevel()</a>, <a class="el" href="a00242.html#l00545">Loki::LevelMutexInfo::IsValid()</a>, <a class="el" href="a00242.html#l00653">Loki::LevelMutexInfo::PostLock()</a>, and <a class="el" href="a00242.html#l00669">Loki::LevelMutexInfo::PreUnlock()</a>.</p>
<p>
<div class="dynheader">
Here is the call graph for this function:</div>
<div class="dynsection">
</div>
</div>
</div><p>
<hr>The documentation for this class was generated from the following file:<ul>
<li><a class="el" href="a00158.html">LevelMutex.h</a></ul>
</div>
<hr size="1"><address style="text-align: right;"><small>Generated on Thu Jan 29 18:51:43 2009 for Loki by
<a href="http://www.doxygen.org/index.html">
<img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.5.8 </small></address>
</body>
</html>
|
