diff options
Diffstat (limited to 'doc/html/qmutex.html')
| -rw-r--r-- | doc/html/qmutex.html | 195 |
1 files changed, 195 insertions, 0 deletions
diff --git a/doc/html/qmutex.html b/doc/html/qmutex.html new file mode 100644 index 0000000..853e811 --- /dev/null +++ b/doc/html/qmutex.html @@ -0,0 +1,195 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<!-- /home/espenr/tmp/qt-3.3.8-espenr-2499/qt-x11-free-3.3.8/src/tools/qmutex_unix.cpp:333 --> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>QMutex Class</title> +<style type="text/css"><!-- +fn { margin-left: 1cm; text-indent: -1cm; } +a:link { color: #004faf; text-decoration: none } +a:visited { color: #672967; text-decoration: none } +body { background: #ffffff; color: black; } +--></style> +</head> +<body> + +<table border="0" cellpadding="0" cellspacing="0" width="100%"> +<tr bgcolor="#E5E5E5"> +<td valign=center> + <a href="index.html"> +<font color="#004faf">Home</font></a> + | <a href="classes.html"> +<font color="#004faf">All Classes</font></a> + | <a href="mainclasses.html"> +<font color="#004faf">Main Classes</font></a> + | <a href="annotated.html"> +<font color="#004faf">Annotated</font></a> + | <a href="groups.html"> +<font color="#004faf">Grouped Classes</font></a> + | <a href="functions.html"> +<font color="#004faf">Functions</font></a> +</td> +<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> + +<p>The QMutex class provides access serialization between threads. +<a href="#details">More...</a> +<p>All the functions in this class are <a href="threads.html#threadsafe">thread-safe</a> when Qt is built with thread support.</p> +<p><tt>#include <<a href="qmutex-h.html">qmutex.h</a>></tt> +<p><a href="qmutex-members.html">List of all member functions.</a> +<h2>Public Members</h2> +<ul> +<li class=fn><a href="#QMutex"><b>QMutex</b></a> ( bool recursive = FALSE )</li> +<li class=fn>virtual <a href="#~QMutex"><b>~QMutex</b></a> ()</li> +<li class=fn>void <a href="#lock"><b>lock</b></a> ()</li> +<li class=fn>void <a href="#unlock"><b>unlock</b></a> ()</li> +<li class=fn>bool <a href="#locked"><b>locked</b></a> ()</li> +<li class=fn>bool <a href="#tryLock"><b>tryLock</b></a> ()</li> +</ul> +<hr><a name="details"></a><h2>Detailed Description</h2> + + + +The QMutex class provides access serialization between threads. +<p> + +<p> The purpose of a QMutex is to protect an object, data structure or +section of code so that only one thread can access it at a time +(This is similar to the Java <tt>synchronized</tt> keyword). For +example, say there is a method which prints a message to the user +on two lines: +<p> <pre> + int number = 6; + + void method1() + { + number *= 5; + number /= 4; + } + + void method2() + { + number *= 3; + number /= 2; + } + </pre> + +<p> If these two methods are called in succession, the following happens: +<p> <pre> + // method1() + number *= 5; // number is now 30 + number /= 4; // number is now 7 + + // method2() + number *= 3; // nubmer is now 21 + number /= 2; // number is now 10 + </pre> + +<p> If these two methods are called simultaneously from two threads then the +following sequence could result: +<p> <pre> + // Thread 1 calls method1() + number *= 5; // number is now 30 + + // Thread 2 calls method2(). + // + // Most likely Thread 1 has been put to sleep by the operating + // system to allow Thread 2 to run. + number *= 3; // number is now 90 + number /= 2; // number is now 45 + + // Thread 1 finishes executing. + number /= 4; // number is now 11, instead of 10 + </pre> + +<p> If we add a mutex, we should get the result we want: +<p> <pre> + QMutex mutex; + int number = 6; + + void method1() + { + mutex.<a href="#lock">lock</a>(); + number *= 5; + number /= 4; + mutex.<a href="#unlock">unlock</a>(); + } + + void method2() + { + mutex.<a href="#lock">lock</a>(); + number *= 3; + number /= 2; + mutex.<a href="#unlock">unlock</a>(); + } + </pre> + +<p> Then only one thread can modify <tt>number</tt> at any given time and +the result is correct. This is a trivial example, of course, but +applies to any other case where things need to happen in a +particular sequence. +<p> When you call <a href="#lock">lock</a>() in a thread, other threads that try to call +lock() in the same place will block until the thread that got the +lock calls <a href="#unlock">unlock</a>(). A non-blocking alternative to lock() is +<a href="#tryLock">tryLock</a>(). +<p>See also <a href="environment.html">Environment Classes</a> and <a href="thread.html">Threading</a>. + +<hr><h2>Member Function Documentation</h2> +<h3 class=fn><a name="QMutex"></a>QMutex::QMutex ( bool recursive = FALSE ) +</h3> +Constructs a new mutex. The mutex is created in an unlocked state. +A recursive mutex is created if <em>recursive</em> is TRUE; a normal +mutex is created if <em>recursive</em> is FALSE (the default). With a +recursive mutex, a thread can lock the same mutex multiple times +and it will not be unlocked until a corresponding number of +<a href="#unlock">unlock</a>() calls have been made. + +<h3 class=fn><a name="~QMutex"></a>QMutex::~QMutex ()<tt> [virtual]</tt> +</h3> +Destroys the mutex. +<p> <b>Warning:</b> If you destroy a mutex that still holds a lock the +resultant behavior is undefined. + +<h3 class=fn>void <a name="lock"></a>QMutex::lock () +</h3> +Attempt to lock the mutex. If another thread has locked the mutex +then this call will <em>block</em> until that thread has unlocked it. +<p> <p>See also <a href="#unlock">unlock</a>() and <a href="#locked">locked</a>(). + +<h3 class=fn>bool <a name="locked"></a>QMutex::locked () +</h3> +Returns TRUE if the mutex is locked by another thread; otherwise +returns FALSE. +<p> <b>Warning:</b> Due to differing implementations of recursive mutexes on +various platforms, calling this function from the same thread that +previously locked the mutex will return undefined results. +<p> <p>See also <a href="#lock">lock</a>() and <a href="#unlock">unlock</a>(). + +<h3 class=fn>bool <a name="tryLock"></a>QMutex::tryLock () +</h3> +Attempt to lock the mutex. If the lock was obtained, this function +returns TRUE. If another thread has locked the mutex, this +function returns FALSE, instead of waiting for the mutex to become +available, i.e. it does not block. +<p> If the lock was obtained, the mutex must be unlocked with <a href="#unlock">unlock</a>() +before another thread can successfully lock it. +<p> <p>See also <a href="#lock">lock</a>(), <a href="#unlock">unlock</a>(), and <a href="#locked">locked</a>(). + +<h3 class=fn>void <a name="unlock"></a>QMutex::unlock () +</h3> +Unlocks the mutex. Attempting to unlock a mutex in a different +thread to the one that locked it results in an error. Unlocking a +mutex that is not locked results in undefined behaviour (varies +between different Operating Systems' thread implementations). +<p> <p>See also <a href="#lock">lock</a>() and <a href="#locked">locked</a>(). + +<!-- eof --> +<hr><p> +This file is part of the <a href="index.html">Qt toolkit</a>. +Copyright © 1995-2007 +<a href="http://www.trolltech.com/">Trolltech</a>. All Rights Reserved.<p><address><hr><div align=center> +<table width=100% cellspacing=0 border=0><tr> +<td>Copyright © 2007 +<a href="troll.html">Trolltech</a><td align=center><a href="trademarks.html">Trademarks</a> +<td align=right><div align=right>Qt 3.3.8</div> +</table></div></address></body> +</html> |