qmutex(3qt)

1QMutex(3qt)                                                        QMutex(3qt)
2
3
4

NAME

6       QMutex - Access serialization between threads
7

SYNOPSIS

9       All the functions in this class are thread-safe when Qt is built with
10       thread support.</p>
11
12       #include <qmutex.h>
13
14   Public Members
15       QMutex ( bool recursive = FALSE )
16       virtual ~QMutex ()
17       void lock ()
18       void unlock ()
19       bool locked ()
20       bool tryLock ()
21

DESCRIPTION

23       The QMutex class provides access serialization between threads.
24
25       The purpose of a QMutex is to protect an object, data structure or
26       section of code so that only one thread can access it at a time (This
27       is similar to the Java synchronized keyword). For example, say there is
28       a method which prints a message to the user on two lines:
29
30           int number = 6;
31           void method1()
32           {
33               number *= 5;
34               number /= 4;
35           }
36           void method2()
37           {
38               number *= 3;
39               number /= 2;
40           }
41
42       If these two methods are called in succession, the following happens:
43
44           // method1()
45           number *= 5;        // number is now 30
46           number /= 4;        // number is now 7
47           // method2()
48           number *= 3;        // nubmer is now 21
49           number /= 2;        // number is now 10
50
51       If these two methods are called simultaneously from two threads then
52       the following sequence could result:
53
54           // Thread 1 calls method1()
55           number *= 5;        // number is now 30
56           // Thread 2 calls method2().
57           //
58           // Most likely Thread 1 has been put to sleep by the operating
59           // system to allow Thread 2 to run.
60           number *= 3;        // number is now 90
61           number /= 2;        // number is now 45
62           // Thread 1 finishes executing.
63           number /= 4;        // number is now 11, instead of 10
64
65       If we add a mutex, we should get the result we want:
66
67           QMutex mutex;
68           int number = 6;
69           void method1()
70           {
71               mutex.lock();
72               number *= 5;
73               number /= 4;
74               mutex.unlock();
75           }
76           void method2()
77           {
78               mutex.lock();
79               number *= 3;
80               number /= 2;
81               mutex.unlock();
82           }
83
84       Then only one thread can modify number at any given time and the result
85       is correct. This is a trivial example, of course, but applies to any
86       other case where things need to happen in a particular sequence.
87
88       When you call lock() in a thread, other threads that try to call lock()
89       in the same place will block until the thread that got the lock calls
90       unlock(). A non-blocking alternative to lock() is tryLock().
91
92       See also Environment Classes and Threading.
93

MEMBER FUNCTION DOCUMENTATION

QMutex::QMutex ( bool recursive = FALSE )

96       Constructs a new mutex. The mutex is created in an unlocked state. A
97       recursive mutex is created if recursive is TRUE; a normal mutex is
98       created if recursive is FALSE (the default). With a recursive mutex, a
99       thread can lock the same mutex multiple times and it will not be
100       unlocked until a corresponding number of unlock() calls have been made.
101

QMutex::~QMutex () [virtual]

103       Destroys the mutex.
104
105       Warning: If you destroy a mutex that still holds a lock the resultant
106       behavior is undefined.
107

void QMutex::lock ()

109       Attempt to lock the mutex. If another thread has locked the mutex then
110       this call will block until that thread has unlocked it.
111
112       See also unlock() and locked().
113

bool QMutex::locked ()

115       Returns TRUE if the mutex is locked by another thread; otherwise
116       returns FALSE.
117
118       Warning: Due to differing implementations of recursive mutexes on
119       various platforms, calling this function from the same thread that
120       previously locked the mutex will return undefined results.
121
122       See also lock() and unlock().
123

bool QMutex::tryLock ()

125       Attempt to lock the mutex. If the lock was obtained, this function
126       returns TRUE. If another thread has locked the mutex, this function
127       returns FALSE, instead of waiting for the mutex to become available,
128       i.e. it does not block.
129
130       If the lock was obtained, the mutex must be unlocked with unlock()
131       before another thread can successfully lock it.
132
133       See also lock(), unlock(), and locked().
134

void QMutex::unlock ()

136       Unlocks the mutex. Attempting to unlock a mutex in a different thread
137       to the one that locked it results in an error. Unlocking a mutex that
138       is not locked results in undefined behaviour (varies between different
139       Operating Systems' thread implementations).
140
141       See also lock() and locked().
142
143

COPYRIGHT

149       Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com.  See the
150       license file included in the distribution for a complete license
151       statement.
152

AUTHOR

154       Generated automatically from the source code.
155

BUGS

157       If you find a bug in Qt, please report it as described in
158       http://doc.trolltech.com/bughowto.html.  Good bug reports help us to
159       help you. Thank you.
160
161       The definitive Qt documentation is provided in HTML format; it is
162       located at $QTDIR/doc/html and can be read using Qt Assistant or with a
163       web browser. This man page is provided as a convenience for those users
164       who prefer man pages, although this format is not officially supported
165       by Trolltech.
166
167       If you find errors in this manual page, please report them to qt-
168       bugs@trolltech.com.  Please include the name of the manual page
169       (qmutex.3qt) and the Qt version (3.3.8).
170
171
172
173Trolltech AS                    2 February 2007                    QMutex(3qt)