source: trunk/doc/html/qmutex.html@ 190

Last change on this file since 190 was 190, checked in by rudi, 14 years ago

reference documentation added
File size: 7.4 KB
Line 
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2<!-- /home/espenr/tmp/qt-3.3.8-espenr-2499/qt-x11-free-3.3.8/src/tools/qmutex_unix.cpp:333 -->
3<html>
4<head>
5<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
6<title>QMutex Class</title>
7<style type="text/css"><!--
8fn { margin-left: 1cm; text-indent: -1cm; }
9a:link { color: #004faf; text-decoration: none }
10a:visited { color: #672967; text-decoration: none }
11body { background: #ffffff; color: black; }
12--></style>
13</head>
14<body>
15
16<table border="0" cellpadding="0" cellspacing="0" width="100%">
17<tr bgcolor="#E5E5E5">
18<td valign=center>
19 <a href="index.html">
20<font color="#004faf">Home</font></a>
21 | <a href="classes.html">
22<font color="#004faf">All&nbsp;Classes</font></a>
23 | <a href="mainclasses.html">
24<font color="#004faf">Main&nbsp;Classes</font></a>
25 | <a href="annotated.html">
26<font color="#004faf">Annotated</font></a>
27 | <a href="groups.html">
28<font color="#004faf">Grouped&nbsp;Classes</font></a>
29 | <a href="functions.html">
30<font color="#004faf">Functions</font></a>
31</td>
32<td align="right" valign="center"><img src="logo32.png" align="right" width="64" height="32" border="0"></td></tr></table><h1 align=center>QMutex Class Reference</h1>
33
34<p>The QMutex class provides access serialization between threads.
35<a href="#details">More...</a>
36<p>All the functions in this class are <a href="threads.html#threadsafe">thread-safe</a> when Qt is built with thread support.</p>
37<p><tt>#include &lt;<a href="qmutex-h.html">qmutex.h</a>&gt;</tt>
38<p><a href="qmutex-members.html">List of all member functions.</a>
39<h2>Public Members</h2>
40<ul>
41<li class=fn><a href="#QMutex"><b>QMutex</b></a> ( bool&nbsp;recursive = FALSE )</li>
42<li class=fn>virtual <a href="#~QMutex"><b>~QMutex</b></a> ()</li>
43<li class=fn>void <a href="#lock"><b>lock</b></a> ()</li>
44<li class=fn>void <a href="#unlock"><b>unlock</b></a> ()</li>
45<li class=fn>bool <a href="#locked"><b>locked</b></a> ()</li>
46<li class=fn>bool <a href="#tryLock"><b>tryLock</b></a> ()</li>
47</ul>
48<hr><a name="details"></a><h2>Detailed Description</h2>
49
50
51
52The QMutex class provides access serialization between threads.
53<p>
54
55<p> The purpose of a QMutex is to protect an object, data structure or
56section of code so that only one thread can access it at a time
57(This is similar to the Java <tt>synchronized</tt> keyword). For
58example, say there is a method which prints a message to the user
59on two lines:
60<p> <pre>
61 int number = 6;
62
63 void method1()
64 {
65 number *= 5;
66 number /= 4;
67 }
68
69 void method2()
70 {
71 number *= 3;
72 number /= 2;
73 }
74 </pre>
75
76<p> If these two methods are called in succession, the following happens:
77<p> <pre>
78 // method1()
79 number *= 5; // number is now 30
80 number /= 4; // number is now 7
81
82 // method2()
83 number *= 3; // nubmer is now 21
84 number /= 2; // number is now 10
85 </pre>
86
87<p> If these two methods are called simultaneously from two threads then the
88following sequence could result:
89<p> <pre>
90 // Thread 1 calls method1()
91 number *= 5; // number is now 30
92
93 // Thread 2 calls method2().
94 //
95 // Most likely Thread 1 has been put to sleep by the operating
96 // system to allow Thread 2 to run.
97 number *= 3; // number is now 90
98 number /= 2; // number is now 45
99
100 // Thread 1 finishes executing.
101 number /= 4; // number is now 11, instead of 10
102 </pre>
103
104<p> If we add a mutex, we should get the result we want:
105<p> <pre>
106 QMutex mutex;
107 int number = 6;
108
109 void method1()
110 {
111 mutex.<a href="#lock">lock</a>();
112 number *= 5;
113 number /= 4;
114 mutex.<a href="#unlock">unlock</a>();
115 }
116
117 void method2()
118 {
119 mutex.<a href="#lock">lock</a>();
120 number *= 3;
121 number /= 2;
122 mutex.<a href="#unlock">unlock</a>();
123 }
124 </pre>
125
126<p> Then only one thread can modify <tt>number</tt> at any given time and
127the result is correct. This is a trivial example, of course, but
128applies to any other case where things need to happen in a
129particular sequence.
130<p> When you call <a href="#lock">lock</a>() in a thread, other threads that try to call
131lock() in the same place will block until the thread that got the
132lock calls <a href="#unlock">unlock</a>(). A non-blocking alternative to lock() is
133<a href="#tryLock">tryLock</a>().
134<p>See also <a href="environment.html">Environment Classes</a> and <a href="thread.html">Threading</a>.
135
136<hr><h2>Member Function Documentation</h2>
137<h3 class=fn><a name="QMutex"></a>QMutex::QMutex ( bool&nbsp;recursive = FALSE )
138</h3>
139Constructs a new mutex. The mutex is created in an unlocked state.
140A recursive mutex is created if <em>recursive</em> is TRUE; a normal
141mutex is created if <em>recursive</em> is FALSE (the default). With a
142recursive mutex, a thread can lock the same mutex multiple times
143and it will not be unlocked until a corresponding number of
144<a href="#unlock">unlock</a>() calls have been made.
145
146<h3 class=fn><a name="~QMutex"></a>QMutex::~QMutex ()<tt> [virtual]</tt>
147</h3>
148Destroys the mutex.
149<p> <b>Warning:</b> If you destroy a mutex that still holds a lock the
150resultant behavior is undefined.
151
152<h3 class=fn>void <a name="lock"></a>QMutex::lock ()
153</h3>
154Attempt to lock the mutex. If another thread has locked the mutex
155then this call will <em>block</em> until that thread has unlocked it.
156<p> <p>See also <a href="#unlock">unlock</a>() and <a href="#locked">locked</a>().
157
158<h3 class=fn>bool <a name="locked"></a>QMutex::locked ()
159</h3>
160Returns TRUE if the mutex is locked by another thread; otherwise
161returns FALSE.
162<p> <b>Warning:</b> Due to differing implementations of recursive mutexes on
163various platforms, calling this function from the same thread that
164previously locked the mutex will return undefined results.
165<p> <p>See also <a href="#lock">lock</a>() and <a href="#unlock">unlock</a>().
166
167<h3 class=fn>bool <a name="tryLock"></a>QMutex::tryLock ()
168</h3>
169Attempt to lock the mutex. If the lock was obtained, this function
170returns TRUE. If another thread has locked the mutex, this
171function returns FALSE, instead of waiting for the mutex to become
172available, i.e. it does not block.
173<p> If the lock was obtained, the mutex must be unlocked with <a href="#unlock">unlock</a>()
174before another thread can successfully lock it.
175<p> <p>See also <a href="#lock">lock</a>(), <a href="#unlock">unlock</a>(), and <a href="#locked">locked</a>().
176
177<h3 class=fn>void <a name="unlock"></a>QMutex::unlock ()
178</h3>
179Unlocks the mutex. Attempting to unlock a mutex in a different
180thread to the one that locked it results in an error. Unlocking a
181mutex that is not locked results in undefined behaviour (varies
182between different Operating Systems' thread implementations).
183<p> <p>See also <a href="#lock">lock</a>() and <a href="#locked">locked</a>().
184
185<!-- eof -->
186<hr><p>
187This file is part of the <a href="index.html">Qt toolkit</a>.
188Copyright &copy; 1995-2007
189<a href="http://www.trolltech.com/">Trolltech</a>. All Rights Reserved.<p><address><hr><div align=center>
190<table width=100% cellspacing=0 border=0><tr>
191<td>Copyright &copy; 2007
192<a href="troll.html">Trolltech</a><td align=center><a href="trademarks.html">Trademarks</a>
193<td align=right><div align=right>Qt 3.3.8</div>
194</table></div></address></body>
195</html>
Note: See TracBrowser for help on using the repository browser.