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
|
<!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"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<title>wxWidgets: wxMutex Class Reference</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="extra_stylesheet.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<div id="page_container">
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0" style="width: 100%;">
<tbody>
<tr>
<td id="projectlogo">
<a href="http://www.wxwidgets.org/" target="_new">
<img alt="wxWidgets" src="logo.png"/>
</a>
</td>
<td style="padding-left: 0.5em; text-align: right;">
<span id="projectnumber">Version: 3.0.2</span>
</td>
</tr>
</tbody>
</table>
</div>
<!-- Generated by Doxygen 1.8.2 -->
<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>Categories</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>
</ul>
</div>
<div id="navrow2" class="tabs2">
<ul class="tablist">
<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><!-- top -->
<div class="header">
<div class="summary">
<a href="#pub-methods">Public Member Functions</a> |
<a href="classwx_mutex-members.html">List of all members</a> </div>
<div class="headertitle">
<div class="title">wxMutex Class Reference<div class="ingroups"><a class="el" href="group__group__class__threading.html">Threading</a></div></div> </div>
</div><!--header-->
<div class="contents">
<p><code>#include <wx/thread.h></code></p>
<a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
<div class="textblock"><p>A mutex object is a synchronization object whose state is set to signaled when it is not owned by any thread, and nonsignaled when it is owned. </p>
<p>Its name comes from its usefulness in coordinating mutually-exclusive access to a shared resource as only one thread at a time can own a mutex object.</p>
<p>Mutexes may be recursive in the sense that a thread can lock a mutex which it had already locked before (instead of dead locking the entire process in this situation by starting to wait on a mutex which will never be released while the thread is waiting) but using them is not recommended under Unix and they are <b>not</b> recursive by default. The reason for this is that recursive mutexes are not supported by all Unix flavours and, worse, they cannot be used with <a class="el" href="classwx_condition.html" title="wxCondition variables correspond to pthread conditions or to Win32 event objects.">wxCondition</a>.</p>
<p>For example, when several threads use the data stored in the linked list, modifications to the list should only be allowed to one thread at a time because during a new node addition the list integrity is temporarily broken (this is also called <em>program</em> <em>invariant</em>).</p>
<div class="fragment"><div class="line"><span class="comment">// this variable has an "s_" prefix because it is static: seeing an "s_" in</span></div>
<div class="line"><span class="comment">// a multithreaded program is in general a good sign that you should use a</span></div>
<div class="line"><span class="comment">// mutex (or a critical section)</span></div>
<div class="line"><span class="keyword">static</span> <a class="code" href="classwx_mutex.html" title="A mutex object is a synchronization object whose state is set to signaled when it is not owned by any...">wxMutex</a> *s_mutexProtectingTheGlobalData;</div>
<div class="line"></div>
<div class="line"><span class="comment">// we store some numbers in this global array which is presumably used by</span></div>
<div class="line"><span class="comment">// several threads simultaneously</span></div>
<div class="line"><a class="code" href="dynarray_8h.html#add87f199292e36ee87efd6d7f0d4ee66" title="Predefined specialization of wxArray<T> for standard types.">wxArrayInt</a> s_data;</div>
<div class="line"></div>
<div class="line"><span class="keywordtype">void</span> MyThread::AddNewNode(<span class="keywordtype">int</span> num)</div>
<div class="line">{</div>
<div class="line"> <span class="comment">// ensure that no other thread accesses the list</span></div>
<div class="line"> s_mutexProtectingTheGlobalList-><a class="code" href="classwx_mutex.html#a5291e0e421262f420051390421ba0d09" title="Locks the mutex object.">Lock</a>();</div>
<div class="line"></div>
<div class="line"> s_data.Add(num);</div>
<div class="line"></div>
<div class="line"> s_mutexProtectingTheGlobalList->Unlock();</div>
<div class="line">}</div>
<div class="line"></div>
<div class="line"><span class="comment">// return true if the given number is greater than all array elements</span></div>
<div class="line"><span class="keywordtype">bool</span> MyThread::IsGreater(<span class="keywordtype">int</span> num)</div>
<div class="line">{</div>
<div class="line"> <span class="comment">// before using the list we must acquire the mutex</span></div>
<div class="line"> <a class="code" href="classwx_mutex_locker.html" title="This is a small helper class to be used with wxMutex objects.">wxMutexLocker</a> lock(s_mutexProtectingTheGlobalData);</div>
<div class="line"></div>
<div class="line"> <span class="keywordtype">size_t</span> count = s_data.Count();</div>
<div class="line"> <span class="keywordflow">for</span> ( <span class="keywordtype">size_t</span> n = 0; n < count; n++ )</div>
<div class="line"> {</div>
<div class="line"> <span class="keywordflow">if</span> ( s_data[n] > num )</div>
<div class="line"> <span class="keywordflow">return</span> <span class="keyword">false</span>;</div>
<div class="line"> }</div>
<div class="line"></div>
<div class="line"> <span class="keywordflow">return</span> <span class="keyword">true</span>;</div>
<div class="line">}</div>
</div><!-- fragment --><p>Notice how <a class="el" href="classwx_mutex_locker.html" title="This is a small helper class to be used with wxMutex objects.">wxMutexLocker</a> was used in the second function to ensure that the mutex is unlocked in any case: whether the function returns true or false (because the destructor of the local object <em>lock</em> is always called). Using this class instead of directly using <a class="el" href="classwx_mutex.html" title="A mutex object is a synchronization object whose state is set to signaled when it is not owned by any...">wxMutex</a> is, in general, safer and is even more so if your program uses C++ exceptions.</p>
<h2></h2>
<div><span class="lib">Library:</span>  <span class="lib_text"><a class="el" href="page_libs.html#page_libs_wxbase">wxBase</a></span></div><div><span class="category">Category:</span>  <span class="category_text"><a class="el" href="group__group__class__threading.html">Threading</a></span></div><dl class="section see"><dt>See Also</dt><dd><a class="el" href="classwx_thread.html" title="A thread is basically a path of execution through a program.">wxThread</a>, <a class="el" href="classwx_condition.html" title="wxCondition variables correspond to pthread conditions or to Win32 event objects.">wxCondition</a>, <a class="el" href="classwx_mutex_locker.html" title="This is a small helper class to be used with wxMutex objects.">wxMutexLocker</a>, <a class="el" href="classwx_critical_section.html" title="A critical section object is used for exactly the same purpose as a wxMutex.">wxCriticalSection</a> </dd></dl>
</div><table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="pub-methods"></a>
Public Member Functions</h2></td></tr>
<tr class="memitem:af5854c82759e233a3ecfcd683d857288"><td class="memItemLeft" align="right" valign="top"> </td><td class="memItemRight" valign="bottom"><a class="el" href="classwx_mutex.html#af5854c82759e233a3ecfcd683d857288">wxMutex</a> (<a class="el" href="interface_2wx_2thread_8h.html#a20ab09ca102b0bef60c0f8eb9aad3ff3">wxMutexType</a> type=<a class="el" href="interface_2wx_2thread_8h.html#a20ab09ca102b0bef60c0f8eb9aad3ff3a7ca355fef99b37a12554e4fd425b072b">wxMUTEX_DEFAULT</a>)</td></tr>
<tr class="memdesc:af5854c82759e233a3ecfcd683d857288"><td class="mdescLeft"> </td><td class="mdescRight">Default constructor. <a href="#af5854c82759e233a3ecfcd683d857288"></a><br/></td></tr>
<tr class="separator:af5854c82759e233a3ecfcd683d857288"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:aca15d3e1f04cf77b25b8a25a37c7281d"><td class="memItemLeft" align="right" valign="top"> </td><td class="memItemRight" valign="bottom"><a class="el" href="classwx_mutex.html#aca15d3e1f04cf77b25b8a25a37c7281d">~wxMutex</a> ()</td></tr>
<tr class="memdesc:aca15d3e1f04cf77b25b8a25a37c7281d"><td class="mdescLeft"> </td><td class="mdescRight">Destroys the <a class="el" href="classwx_mutex.html" title="A mutex object is a synchronization object whose state is set to signaled when it is not owned by any...">wxMutex</a> object. <a href="#aca15d3e1f04cf77b25b8a25a37c7281d"></a><br/></td></tr>
<tr class="separator:aca15d3e1f04cf77b25b8a25a37c7281d"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:a5291e0e421262f420051390421ba0d09"><td class="memItemLeft" align="right" valign="top"><a class="el" href="interface_2wx_2thread_8h.html#ac8c1ee75d2a2da3be8eabc629f71c1a7">wxMutexError</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="classwx_mutex.html#a5291e0e421262f420051390421ba0d09">Lock</a> ()</td></tr>
<tr class="memdesc:a5291e0e421262f420051390421ba0d09"><td class="mdescLeft"> </td><td class="mdescRight">Locks the mutex object. <a href="#a5291e0e421262f420051390421ba0d09"></a><br/></td></tr>
<tr class="separator:a5291e0e421262f420051390421ba0d09"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:a1e22609b14aefe8a248b2e48bca51415"><td class="memItemLeft" align="right" valign="top"><a class="el" href="interface_2wx_2thread_8h.html#ac8c1ee75d2a2da3be8eabc629f71c1a7">wxMutexError</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="classwx_mutex.html#a1e22609b14aefe8a248b2e48bca51415">LockTimeout</a> (unsigned long msec)</td></tr>
<tr class="memdesc:a1e22609b14aefe8a248b2e48bca51415"><td class="mdescLeft"> </td><td class="mdescRight">Try to lock the mutex object during the specified time interval. <a href="#a1e22609b14aefe8a248b2e48bca51415"></a><br/></td></tr>
<tr class="separator:a1e22609b14aefe8a248b2e48bca51415"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:a4485a8234390d1adc69426337069602b"><td class="memItemLeft" align="right" valign="top"><a class="el" href="interface_2wx_2thread_8h.html#ac8c1ee75d2a2da3be8eabc629f71c1a7">wxMutexError</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="classwx_mutex.html#a4485a8234390d1adc69426337069602b">TryLock</a> ()</td></tr>
<tr class="memdesc:a4485a8234390d1adc69426337069602b"><td class="mdescLeft"> </td><td class="mdescRight">Tries to lock the mutex object. <a href="#a4485a8234390d1adc69426337069602b"></a><br/></td></tr>
<tr class="separator:a4485a8234390d1adc69426337069602b"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:aad45c7189e66d6d49eeaf1135ab24af7"><td class="memItemLeft" align="right" valign="top"><a class="el" href="interface_2wx_2thread_8h.html#ac8c1ee75d2a2da3be8eabc629f71c1a7">wxMutexError</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="classwx_mutex.html#aad45c7189e66d6d49eeaf1135ab24af7">Unlock</a> ()</td></tr>
<tr class="memdesc:aad45c7189e66d6d49eeaf1135ab24af7"><td class="mdescLeft"> </td><td class="mdescRight">Unlocks the mutex object. <a href="#aad45c7189e66d6d49eeaf1135ab24af7"></a><br/></td></tr>
<tr class="separator:aad45c7189e66d6d49eeaf1135ab24af7"><td class="memSeparator" colspan="2"> </td></tr>
</table>
<h2 class="groupheader">Constructor & Destructor Documentation</h2>
<a class="anchor" id="af5854c82759e233a3ecfcd683d857288"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">wxMutex::wxMutex </td>
<td>(</td>
<td class="paramtype"><a class="el" href="interface_2wx_2thread_8h.html#a20ab09ca102b0bef60c0f8eb9aad3ff3">wxMutexType</a> </td>
<td class="paramname"><em>type</em> = <code><a class="el" href="interface_2wx_2thread_8h.html#a20ab09ca102b0bef60c0f8eb9aad3ff3a7ca355fef99b37a12554e4fd425b072b">wxMUTEX_DEFAULT</a></code></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Default constructor. </p>
</div>
</div>
<a class="anchor" id="aca15d3e1f04cf77b25b8a25a37c7281d"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">wxMutex::~wxMutex </td>
<td>(</td>
<td class="paramname"></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Destroys the <a class="el" href="classwx_mutex.html" title="A mutex object is a synchronization object whose state is set to signaled when it is not owned by any...">wxMutex</a> object. </p>
</div>
</div>
<h2 class="groupheader">Member Function Documentation</h2>
<a class="anchor" id="a5291e0e421262f420051390421ba0d09"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="interface_2wx_2thread_8h.html#ac8c1ee75d2a2da3be8eabc629f71c1a7">wxMutexError</a> wxMutex::Lock </td>
<td>(</td>
<td class="paramname"></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Locks the mutex object. </p>
<p>This is equivalent to <a class="el" href="classwx_mutex.html#a1e22609b14aefe8a248b2e48bca51415" title="Try to lock the mutex object during the specified time interval.">LockTimeout()</a> with infinite timeout.</p>
<p>Note that if this mutex is already locked by the caller thread, this function doesn't block but rather immediately returns.</p>
<dl class="section return"><dt>Returns</dt><dd>One of: <code>wxMUTEX_NO_ERROR</code>, <code>wxMUTEX_DEAD_LOCK</code>. </dd></dl>
</div>
</div>
<a class="anchor" id="a1e22609b14aefe8a248b2e48bca51415"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="interface_2wx_2thread_8h.html#ac8c1ee75d2a2da3be8eabc629f71c1a7">wxMutexError</a> wxMutex::LockTimeout </td>
<td>(</td>
<td class="paramtype">unsigned long </td>
<td class="paramname"><em>msec</em></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Try to lock the mutex object during the specified time interval. </p>
<dl class="section return"><dt>Returns</dt><dd>One of: <code>wxMUTEX_NO_ERROR</code>, <code>wxMUTEX_DEAD_LOCK</code>, <code>wxMUTEX_TIMEOUT</code>. </dd></dl>
</div>
</div>
<a class="anchor" id="a4485a8234390d1adc69426337069602b"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="interface_2wx_2thread_8h.html#ac8c1ee75d2a2da3be8eabc629f71c1a7">wxMutexError</a> wxMutex::TryLock </td>
<td>(</td>
<td class="paramname"></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Tries to lock the mutex object. </p>
<p>If it can't, returns immediately with an error.</p>
<dl class="section return"><dt>Returns</dt><dd>One of: <code>wxMUTEX_NO_ERROR</code>, <code>wxMUTEX_BUSY</code>. </dd></dl>
</div>
</div>
<a class="anchor" id="aad45c7189e66d6d49eeaf1135ab24af7"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="interface_2wx_2thread_8h.html#ac8c1ee75d2a2da3be8eabc629f71c1a7">wxMutexError</a> wxMutex::Unlock </td>
<td>(</td>
<td class="paramname"></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Unlocks the mutex object. </p>
<dl class="section return"><dt>Returns</dt><dd>One of: <code>wxMUTEX_NO_ERROR</code>, <code>wxMUTEX_UNLOCKED</code>. </dd></dl>
</div>
</div>
</div><!-- contents -->
<address class="footer">
<small>
Generated on Thu Nov 27 2014 13:46:51 for wxWidgets by <a href="http://www.doxygen.org/index.html" target="_new">Doxygen</a> 1.8.2
</small>
</address>
<script src="wxwidgets.js" type="text/javascript"></script>
</div><!-- #page_container -->
</body>
</html>
|
