1998-06-14 08:11:50 -04:00
|
|
|
\section{\class{wxMutex}}\label{wxmutex}
|
|
|
|
|
1999-01-02 18:02:30 -05:00
|
|
|
A mutex object is a synchronization object whose state is set to signaled when
|
|
|
|
it is not owned by any thread, and nonsignaled when it is owned. Its name comes
|
|
|
|
from its usefulness in coordinating mutually-exclusive access to a shared
|
2003-07-14 19:35:28 -04:00
|
|
|
resource as only one thread at a time can own a mutex object.
|
|
|
|
|
|
|
|
Mutexes may be recursive in the sense that a thread can lock a mutex which it
|
|
|
|
had already locked before (instead of dead locking the entire process in this
|
|
|
|
situation by starting to wait on a mutex which will never be released while the
|
|
|
|
thread is waiting) but using them is not recommended and they are {\bf not}
|
|
|
|
recursive by default. The reason for this is that recursive mutexes are not
|
|
|
|
supported by all Unix flavours and, worse, they cannot be used with
|
|
|
|
\helpref{wxCondition}{wxcondition}.
|
1999-01-02 18:02:30 -05:00
|
|
|
|
2005-11-18 20:07:56 -05:00
|
|
|
For example, when several threads use the data stored in the linked list,
|
|
|
|
modifications to the list should only be allowed to one thread at a time
|
1999-01-02 18:02:30 -05:00
|
|
|
because during a new node addition the list integrity is temporarily broken
|
|
|
|
(this is also called {\it program invariant}).
|
|
|
|
|
|
|
|
\wxheading{Example}
|
|
|
|
|
|
|
|
{\small%
|
|
|
|
\begin{verbatim}
|
|
|
|
// this variable has an "s_" prefix because it is static: seeing an "s_" in
|
|
|
|
// a multithreaded program is in general a good sign that you should use a
|
|
|
|
// mutex (or a critical section)
|
|
|
|
static wxMutex *s_mutexProtectingTheGlobalData;
|
|
|
|
|
|
|
|
// we store some numbers in this global array which is presumably used by
|
|
|
|
// several threads simultaneously
|
|
|
|
wxArrayInt s_data;
|
|
|
|
|
|
|
|
void MyThread::AddNewNode(int num)
|
|
|
|
{
|
|
|
|
// ensure that no other thread accesses the list
|
|
|
|
s_mutexProtectingTheGlobalList->Lock();
|
|
|
|
|
|
|
|
s_data.Add(num);
|
|
|
|
|
|
|
|
s_mutexProtectingTheGlobalList->Unlock();
|
|
|
|
}
|
|
|
|
|
2007-02-10 21:53:05 -05:00
|
|
|
// return true if the given number is greater than all array elements
|
1999-01-02 18:02:30 -05:00
|
|
|
bool MyThread::IsGreater(int num)
|
|
|
|
{
|
|
|
|
// before using the list we must acquire the mutex
|
|
|
|
wxMutexLocker lock(s_mutexProtectingTheGlobalData);
|
|
|
|
|
|
|
|
size_t count = s_data.Count();
|
|
|
|
for ( size_t n = 0; n < count; n++ )
|
|
|
|
{
|
|
|
|
if ( s_data[n] > num )
|
2003-01-17 19:16:34 -05:00
|
|
|
return false;
|
1999-01-02 18:02:30 -05:00
|
|
|
}
|
|
|
|
|
2003-01-17 19:16:34 -05:00
|
|
|
return true;
|
1999-01-02 18:02:30 -05:00
|
|
|
}
|
|
|
|
\end{verbatim}
|
|
|
|
}
|
|
|
|
|
|
|
|
Notice how wxMutexLocker was used in the second function to ensure that the
|
2003-01-17 19:16:34 -05:00
|
|
|
mutex is unlocked in any case: whether the function returns true or false
|
1999-01-02 18:02:30 -05:00
|
|
|
(because the destructor of the local object {\it lock} is always called). Using
|
|
|
|
this class instead of directly using wxMutex is, in general safer and is even
|
2001-04-08 18:49:09 -04:00
|
|
|
more so if your program uses C++ exceptions.
|
1998-06-14 08:11:50 -04:00
|
|
|
|
2003-07-14 19:35:28 -04:00
|
|
|
\wxheading{Constants}
|
|
|
|
|
|
|
|
\begin{verbatim}
|
|
|
|
enum wxMutexType
|
|
|
|
{
|
|
|
|
// normal mutex: try to always use this one
|
|
|
|
wxMUTEX_DEFAULT,
|
|
|
|
|
|
|
|
// recursive mutex: don't use these ones with wxCondition
|
|
|
|
wxMUTEX_RECURSIVE
|
|
|
|
};
|
|
|
|
\end{verbatim}
|
|
|
|
|
1998-06-14 08:11:50 -04:00
|
|
|
\wxheading{Derived from}
|
|
|
|
|
|
|
|
None.
|
|
|
|
|
1999-02-15 15:41:29 -05:00
|
|
|
\wxheading{Include files}
|
|
|
|
|
|
|
|
<wx/thread.h>
|
|
|
|
|
1998-06-14 08:11:50 -04:00
|
|
|
\wxheading{See also}
|
|
|
|
|
2000-03-14 19:21:49 -05:00
|
|
|
\helpref{wxThread}{wxthread}, \helpref{wxCondition}{wxcondition},
|
1999-01-02 18:02:30 -05:00
|
|
|
\helpref{wxMutexLocker}{wxmutexlocker}, \helpref{wxCriticalSection}{wxcriticalsection}
|
1998-06-14 08:11:50 -04:00
|
|
|
|
|
|
|
\latexignore{\rtfignore{\wxheading{Members}}}
|
|
|
|
|
2007-03-07 19:22:11 -05:00
|
|
|
|
2004-09-27 12:01:38 -04:00
|
|
|
\membersection{wxMutex::wxMutex}\label{wxmutexctor}
|
1998-06-14 08:11:50 -04:00
|
|
|
|
2003-07-14 19:35:28 -04:00
|
|
|
\func{}{wxMutex}{\param{wxMutexType }{type = {\tt wxMUTEX\_DEFAULT}}}
|
1998-06-14 08:11:50 -04:00
|
|
|
|
|
|
|
Default constructor.
|
|
|
|
|
2007-03-07 19:22:11 -05:00
|
|
|
|
2004-09-27 12:01:38 -04:00
|
|
|
\membersection{wxMutex::\destruct{wxMutex}}\label{wxmutexdtor}
|
1998-06-14 08:11:50 -04:00
|
|
|
|
|
|
|
\func{}{\destruct{wxMutex}}{\void}
|
|
|
|
|
|
|
|
Destroys the wxMutex object.
|
|
|
|
|
2007-03-07 19:22:11 -05:00
|
|
|
|
1998-06-14 08:11:50 -04:00
|
|
|
\membersection{wxMutex::Lock}\label{wxmutexlock}
|
|
|
|
|
|
|
|
\func{wxMutexError}{Lock}{\void}
|
|
|
|
|
2007-03-07 19:22:11 -05:00
|
|
|
Locks the mutex object. This is equivalent to
|
|
|
|
\helpref{LockTimeout}{wxmutexlocktimeout} with infinite timeout.
|
1998-06-14 08:11:50 -04:00
|
|
|
|
|
|
|
\wxheading{Return value}
|
|
|
|
|
|
|
|
One of:
|
|
|
|
|
|
|
|
\twocolwidtha{7cm}
|
|
|
|
\begin{twocollist}\itemsep=0pt
|
1999-01-02 18:02:30 -05:00
|
|
|
\twocolitem{{\bf wxMUTEX\_NO\_ERROR}}{There was no error.}
|
|
|
|
\twocolitem{{\bf wxMUTEX\_DEAD\_LOCK}}{A deadlock situation was detected.}
|
1998-06-14 08:11:50 -04:00
|
|
|
\end{twocollist}
|
|
|
|
|
2007-03-07 19:22:11 -05:00
|
|
|
|
|
|
|
\membersection{wxMutex::LockTimeout}\label{wxmutexlocktimeout}
|
|
|
|
|
|
|
|
\func{wxMutexError}{LockTimeout}{\param{unsigned long}{ msec}}
|
|
|
|
|
|
|
|
Try to lock the mutex object during the specified time interval.
|
|
|
|
|
|
|
|
\wxheading{Return value}
|
|
|
|
|
|
|
|
One of:
|
|
|
|
|
|
|
|
\twocolwidtha{7cm}
|
|
|
|
\begin{twocollist}\itemsep=0pt
|
|
|
|
\twocolitem{{\bf wxMUTEX\_NO\_ERROR}}{Mutex successfully locked.}
|
|
|
|
\twocolitem{{\bf wxMUTEX\_TIMEOUT}}{Mutex couldn't be acquired before timeout expiration.}
|
|
|
|
\twocolitem{{\bf wxMUTEX\_DEAD\_LOCK}}{A deadlock situation was detected.}
|
|
|
|
\end{twocollist}
|
|
|
|
|
|
|
|
|
1998-06-14 08:11:50 -04:00
|
|
|
\membersection{wxMutex::TryLock}\label{wxmutextrylock}
|
|
|
|
|
|
|
|
\func{wxMutexError}{TryLock}{\void}
|
|
|
|
|
|
|
|
Tries to lock the mutex object. If it can't, returns immediately with an error.
|
|
|
|
|
|
|
|
\wxheading{Return value}
|
|
|
|
|
|
|
|
One of:
|
|
|
|
|
|
|
|
\twocolwidtha{7cm}
|
|
|
|
\begin{twocollist}\itemsep=0pt
|
1999-01-02 18:02:30 -05:00
|
|
|
\twocolitem{{\bf wxMUTEX\_NO\_ERROR}}{There was no error.}
|
|
|
|
\twocolitem{{\bf wxMUTEX\_BUSY}}{The mutex is already locked by another thread.}
|
1998-06-14 08:11:50 -04:00
|
|
|
\end{twocollist}
|
|
|
|
|
2007-03-07 19:22:11 -05:00
|
|
|
|
1998-06-14 08:11:50 -04:00
|
|
|
\membersection{wxMutex::Unlock}\label{wxmutexunlock}
|
|
|
|
|
|
|
|
\func{wxMutexError}{Unlock}{\void}
|
|
|
|
|
|
|
|
Unlocks the mutex object.
|
|
|
|
|
|
|
|
\wxheading{Return value}
|
|
|
|
|
|
|
|
One of:
|
|
|
|
|
|
|
|
\twocolwidtha{7cm}
|
|
|
|
\begin{twocollist}\itemsep=0pt
|
1999-01-02 18:02:30 -05:00
|
|
|
\twocolitem{{\bf wxMUTEX\_NO\_ERROR}}{There was no error.}
|
2006-04-23 18:41:42 -04:00
|
|
|
\twocolitem{{\bf wxMUTEX\_UNLOCKED}}{The calling thread doesn't own the mutex.}
|
1998-06-14 08:11:50 -04:00
|
|
|
\end{twocollist}
|
|
|
|
|