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