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 and they are {\bf not}
  12 recursive by default. The reason for this is that recursive mutexes are not
  13 supported by all Unix flavours and, worse, they cannot be used with
  14 \helpref{wxCondition}{wxcondition}.
  15
  16 For example, when several threads use the data stored in the linked list,
  17 modifications to the list should only be allowed to one thread at a time
  18 because 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 if 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
  62 Notice how wxMutexLocker was used in the second function to ensure that the
  63 mutex 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
  65 this class instead of directly using wxMutex is, in general safer and is even
  66 more so if your program uses C++ exceptions.
  67
  68 \wxheading{Constants}
  69
  70 \begin{verbatim}
  71 enum 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
  83 None.
  84
  85 \wxheading{Include files}
  86
  87 <wx/thread.h>
  88
  89 \wxheading{Library}
  90
  91 \helpref{wxBase}{librarieslist}
  92
  93 \wxheading{See also}
  94
  95 \helpref{wxThread}{wxthread}, \helpref{wxCondition}{wxcondition},
  96 \helpref{wxMutexLocker}{wxmutexlocker}, \helpref{wxCriticalSection}{wxcriticalsection}
  97
  98 \latexignore{\rtfignore{\wxheading{Members}}}
  99
 100
 101 \membersection{wxMutex::wxMutex}\label{wxmutexctor}
 102
 103 \func{}{wxMutex}{\param{wxMutexType }{type = {\tt wxMUTEX\_DEFAULT}}}
 104
 105 Default constructor.
 106
 107
 108 \membersection{wxMutex::\destruct{wxMutex}}\label{wxmutexdtor}
 109
 110 \func{}{\destruct{wxMutex}}{\void}
 111
 112 Destroys the wxMutex object.
 113
 114
 115 \membersection{wxMutex::Lock}\label{wxmutexlock}
 116
 117 \func{wxMutexError}{Lock}{\void}
 118
 119 Locks the mutex object. This is equivalent to
 120 \helpref{LockTimeout}{wxmutexlocktimeout} with infinite timeout.
 121
 122 \wxheading{Return value}
 123
 124 One of:
 125
 126 \twocolwidtha{7cm}
 127 \begin{twocollist}\itemsep=0pt
 128 \twocolitem{{\bf wxMUTEX\_NO\_ERROR}}{There was no error.}
 129 \twocolitem{{\bf wxMUTEX\_DEAD\_LOCK}}{A deadlock situation was detected.}
 130 \end{twocollist}
 131
 132
 133 \membersection{wxMutex::LockTimeout}\label{wxmutexlocktimeout}
 134
 135 \func{wxMutexError}{LockTimeout}{\param{unsigned long}{ msec}}
 136
 137 Try to lock the mutex object during the specified time interval.
 138
 139 \wxheading{Return value}
 140
 141 One of:
 142
 143 \twocolwidtha{7cm}
 144 \begin{twocollist}\itemsep=0pt
 145 \twocolitem{{\bf wxMUTEX\_NO\_ERROR}}{Mutex successfully locked.}
 146 \twocolitem{{\bf wxMUTEX\_TIMEOUT}}{Mutex couldn't be acquired before timeout expiration.}
 147 \twocolitem{{\bf wxMUTEX\_DEAD\_LOCK}}{A deadlock situation was detected.}
 148 \end{twocollist}
 149
 150
 151 \membersection{wxMutex::TryLock}\label{wxmutextrylock}
 152
 153 \func{wxMutexError}{TryLock}{\void}
 154
 155 Tries to lock the mutex object. If it can't, returns immediately with an error.
 156
 157 \wxheading{Return value}
 158
 159 One of:
 160
 161 \twocolwidtha{7cm}
 162 \begin{twocollist}\itemsep=0pt
 163 \twocolitem{{\bf wxMUTEX\_NO\_ERROR}}{There was no error.}
 164 \twocolitem{{\bf wxMUTEX\_BUSY}}{The mutex is already locked by another thread.}
 165 \end{twocollist}
 166
 167
 168 \membersection{wxMutex::Unlock}\label{wxmutexunlock}
 169
 170 \func{wxMutexError}{Unlock}{\void}
 171
 172 Unlocks the mutex object.
 173
 174 \wxheading{Return value}
 175
 176 One of:
 177
 178 \twocolwidtha{7cm}
 179 \begin{twocollist}\itemsep=0pt
 180 \twocolitem{{\bf wxMUTEX\_NO\_ERROR}}{There was no error.}
 181 \twocolitem{{\bf wxMUTEX\_UNLOCKED}}{The calling thread doesn't own the mutex.}
 182 \end{twocollist}
 183