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