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