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 thread use the data stored in the linked list,
  17 modifications to the list should be only 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 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{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
 100 Default constructor.
 101
 102 \membersection{wxMutex::\destruct{wxMutex}}
 103
 104 \func{}{\destruct{wxMutex}}{\void}
 105
 106 Destroys the wxMutex object.
 107
 108 \membersection{wxMutex::Lock}\label{wxmutexlock}
 109
 110 \func{wxMutexError}{Lock}{\void}
 111
 112 Locks the mutex object.
 113
 114 \wxheading{Return value}
 115
 116 One 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
 129 Tries to lock the mutex object. If it can't, returns immediately with an error.
 130
 131 \wxheading{Return value}
 132
 133 One 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
 146 Unlocks the mutex object.
 147
 148 \wxheading{Return value}
 149
 150 One 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