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{See also}
  65
  66 \helpref{wxThread}{wxthread}, \helpref{wxCondition}{wxcondition},
  67 \helpref{wxMutexLocker}{wxmutexlocker}, \helpref{wxCriticalSection}{wxcriticalsection}
  68
  69 \latexignore{\rtfignore{\wxheading{Members}}}
  70
  71 \membersection{wxMutex::wxMutex}\label{wxmutexconstr}
  72
  73 \func{}{wxMutex}{\void}
  74
  75 Default constructor.
  76
  77 \membersection{wxMutex::\destruct{wxMutex}}
  78
  79 \func{}{\destruct{wxMutex}}{\void}
  80
  81 Destroys the wxMutex object.
  82
  83 \membersection{wxMutex::IsLocked}\label{wxmutexislocked}
  84
  85 \constfunc{bool}{IsLocked}{\void}
  86
  87 Returns TRUE if the mutex is locked, FALSE otherwise.
  88
  89 \membersection{wxMutex::Lock}\label{wxmutexlock}
  90
  91 \func{wxMutexError}{Lock}{\void}
  92
  93 Locks the mutex object.
  94
  95 \wxheading{Return value}
  96
  97 One of:
  98
  99 \twocolwidtha{7cm}
 100 \begin{twocollist}\itemsep=0pt
 101 \twocolitem{{\bf wxMUTEX\_NO\_ERROR}}{There was no error.}
 102 \twocolitem{{\bf wxMUTEX\_DEAD\_LOCK}}{A deadlock situation was detected.}
 103 \twocolitem{{\bf wxMUTEX\_BUSY}}{The mutex is already locked by another thread.}
 104 \end{twocollist}
 105
 106 \membersection{wxMutex::TryLock}\label{wxmutextrylock}
 107
 108 \func{wxMutexError}{TryLock}{\void}
 109
 110 Tries to lock the mutex object. If it can't, returns immediately with an error.
 111
 112 \wxheading{Return value}
 113
 114 One of:
 115
 116 \twocolwidtha{7cm}
 117 \begin{twocollist}\itemsep=0pt
 118 \twocolitem{{\bf wxMUTEX\_NO\_ERROR}}{There was no error.}
 119 \twocolitem{{\bf wxMUTEX\_DEAD\_LOCK}}{A deadlock situation was detected.}
 120 \twocolitem{{\bf wxMUTEX\_BUSY}}{The mutex is already locked by another thread.}
 121 \end{twocollist}
 122
 123 \membersection{wxMutex::Unlock}\label{wxmutexunlock}
 124
 125 \func{wxMutexError}{Unlock}{\void}
 126
 127 Unlocks the mutex object.
 128
 129 \wxheading{Return value}
 130
 131 One of:
 132
 133 \twocolwidtha{7cm}
 134 \begin{twocollist}\itemsep=0pt
 135 \twocolitem{{\bf wxMUTEX\_NO\_ERROR}}{There was no error.}
 136 \twocolitem{{\bf wxMUTEX\_DEAD\_LOCK}}{A deadlock situation was detected.}
 137 \twocolitem{{\bf wxMUTEX\_BUSY}}{The mutex is already locked by another thread.}
 138 \twocolitem{{\bf wxMUTEX\_UNLOCKED}}{The calling thread tries to unlock an unlocked mutex.}
 139 \end{twocollist}
 140
 141