]> git.saurik.com Git - wxWidgets.git/blob - docs/latex/wx/mutex.tex
interface headers reviewed
[wxWidgets.git] / docs / latex / wx / mutex.tex
1 \section{\class{wxMutex}}\label{wxmutex}
2
3 A mutex object is a synchronization object whose state is set to signaled when
4 it is not owned by any thread, and nonsignaled when it is owned. Its name comes
5 from its usefulness in coordinating mutually-exclusive access to a shared
6 resource as only one thread at a time can own a mutex object.
7
8 Mutexes may be recursive in the sense that a thread can lock a mutex which it
9 had already locked before (instead of dead locking the entire process in this
10 situation by starting to wait on a mutex which will never be released while the
11 thread is waiting) but using them is not recommended under Unix and they are
12 {\bf not} recursive there by default. The reason for this is that recursive
13 mutexes are not supported by all Unix flavours and, worse, they cannot be used
14 with \helpref{wxCondition}{wxcondition}. On the other hand, Win32 mutexes are
15 always recursive.
16
17 For example, when several threads use the data stored in the linked list,
18 modifications to the list should only be allowed to one thread at a time
19 because during a new node addition the list integrity is temporarily broken
20 (this is also called {\it program invariant}).
21
22 \wxheading{Example}
23
24 {\small%
25 \begin{verbatim}
26 // this variable has an "s_" prefix because it is static: seeing an "s_" in
27 // a multithreaded program is in general a good sign that you should use a
28 // mutex (or a critical section)
29 static wxMutex *s_mutexProtectingTheGlobalData;
30
31 // we store some numbers in this global array which is presumably used by
32 // several threads simultaneously
33 wxArrayInt s_data;
34
35 void MyThread::AddNewNode(int num)
36 {
37 // ensure that no other thread accesses the list
38 s_mutexProtectingTheGlobalList->Lock();
39
40 s_data.Add(num);
41
42 s_mutexProtectingTheGlobalList->Unlock();
43 }
44
45 // return true if the given number is greater than all array elements
46 bool MyThread::IsGreater(int num)
47 {
48 // before using the list we must acquire the mutex
49 wxMutexLocker lock(s_mutexProtectingTheGlobalData);
50
51 size_t count = s_data.Count();
52 for ( size_t n = 0; n < count; n++ )
53 {
54 if ( s_data[n] > num )
55 return false;
56 }
57
58 return true;
59 }
60 \end{verbatim}
61 }
62
63 Notice how wxMutexLocker was used in the second function to ensure that the
64 mutex is unlocked in any case: whether the function returns true or false
65 (because the destructor of the local object {\it lock} is always called). Using
66 this class instead of directly using wxMutex is, in general safer and is even
67 more so if your program uses C++ exceptions.
68
69 \wxheading{Constants}
70
71 \begin{verbatim}
72 enum wxMutexType
73 {
74 // normal mutex: try to always use this one
75 wxMUTEX_DEFAULT,
76
77 // recursive mutex: don't use these ones with wxCondition
78 wxMUTEX_RECURSIVE
79 };
80 \end{verbatim}
81
82 \wxheading{Derived from}
83
84 None.
85
86 \wxheading{Include files}
87
88 <wx/thread.h>
89
90 \wxheading{Library}
91
92 \helpref{wxBase}{librarieslist}
93
94 \wxheading{See also}
95
96 \helpref{wxThread}{wxthread}, \helpref{wxCondition}{wxcondition},
97 \helpref{wxMutexLocker}{wxmutexlocker}, \helpref{wxCriticalSection}{wxcriticalsection}
98
99 \latexignore{\rtfignore{\wxheading{Members}}}
100
101
102 \membersection{wxMutex::wxMutex}\label{wxmutexctor}
103
104 \func{}{wxMutex}{\param{wxMutexType }{type = {\tt wxMUTEX\_DEFAULT}}}
105
106 Default constructor.
107
108
109 \membersection{wxMutex::\destruct{wxMutex}}\label{wxmutexdtor}
110
111 \func{}{\destruct{wxMutex}}{\void}
112
113 Destroys the wxMutex object.
114
115
116 \membersection{wxMutex::Lock}\label{wxmutexlock}
117
118 \func{wxMutexError}{Lock}{\void}
119
120 Locks the mutex object. This is equivalent to
121 \helpref{LockTimeout}{wxmutexlocktimeout} with infinite timeout.
122
123 \wxheading{Return value}
124
125 One of:
126
127 \twocolwidtha{7cm}
128 \begin{twocollist}\itemsep=0pt
129 \twocolitem{{\bf wxMUTEX\_NO\_ERROR}}{There was no error.}
130 \twocolitem{{\bf wxMUTEX\_DEAD\_LOCK}}{A deadlock situation was detected.}
131 \end{twocollist}
132
133
134 \membersection{wxMutex::LockTimeout}\label{wxmutexlocktimeout}
135
136 \func{wxMutexError}{LockTimeout}{\param{unsigned long}{ msec}}
137
138 Try to lock the mutex object during the specified time interval.
139
140 \wxheading{Return value}
141
142 One of:
143
144 \twocolwidtha{7cm}
145 \begin{twocollist}\itemsep=0pt
146 \twocolitem{{\bf wxMUTEX\_NO\_ERROR}}{Mutex successfully locked.}
147 \twocolitem{{\bf wxMUTEX\_TIMEOUT}}{Mutex couldn't be acquired before timeout expiration.}
148 \twocolitem{{\bf wxMUTEX\_DEAD\_LOCK}}{A deadlock situation was detected.}
149 \end{twocollist}
150
151
152 \membersection{wxMutex::TryLock}\label{wxmutextrylock}
153
154 \func{wxMutexError}{TryLock}{\void}
155
156 Tries to lock the mutex object. If it can't, returns immediately with an error.
157
158 \wxheading{Return value}
159
160 One of:
161
162 \twocolwidtha{7cm}
163 \begin{twocollist}\itemsep=0pt
164 \twocolitem{{\bf wxMUTEX\_NO\_ERROR}}{There was no error.}
165 \twocolitem{{\bf wxMUTEX\_BUSY}}{The mutex is already locked by another thread.}
166 \end{twocollist}
167
168
169 \membersection{wxMutex::Unlock}\label{wxmutexunlock}
170
171 \func{wxMutexError}{Unlock}{\void}
172
173 Unlocks the mutex object.
174
175 \wxheading{Return value}
176
177 One of:
178
179 \twocolwidtha{7cm}
180 \begin{twocollist}\itemsep=0pt
181 \twocolitem{{\bf wxMUTEX\_NO\_ERROR}}{There was no error.}
182 \twocolitem{{\bf wxMUTEX\_UNLOCKED}}{The calling thread doesn't own the mutex.}
183 \end{twocollist}
184