remove C++ comment

[wxWidgets.git] / docs / latex / wx / mutex.tex

diff --git a/docs/latex/wx/mutex.tex b/docs/latex/wx/mutex.tex
index 8a8c1cc222623a8a310763a0ebd2ac7955b3b831..7f455980051972a19666162275480cfba9678278 100644 (file)
--- a/docs/latex/wx/mutex.tex
+++ b/docs/latex/wx/mutex.tex
@@ -3,10 +3,19 @@
 A mutex object is a synchronization object whose state is set to signaled when
 it is not owned by any thread, and nonsignaled when it is owned. Its name comes
 from its usefulness in coordinating mutually-exclusive access to a shared
 A mutex object is a synchronization object whose state is set to signaled when
 it is not owned by any thread, and nonsignaled when it is owned. Its name comes
 from its usefulness in coordinating mutually-exclusive access to a shared

-resource. Only one thread at a time can own a mutex object.
-
-For example, when several thread use the data stored in the linked list,
-modifications to the list should be only allowed to one thread at a time
+resource as only one thread at a time can own a mutex object.
+
+Mutexes may be recursive in the sense that a thread can lock a mutex which it
+had already locked before (instead of dead locking the entire process in this
+situation by starting to wait on a mutex which will never be released while the
+thread is waiting) but using them is not recommended under Unix and they are 
+{\bf not} recursive there by default. The reason for this is that recursive
+mutexes are not supported by all Unix flavours and, worse, they cannot be used
+with \helpref{wxCondition}{wxcondition}. On the other hand, Win32 mutexes are
+always recursive.
+
+For example, when several threads use the data stored in the linked list,
+modifications to the list should only be allowed to one thread at a time

 because during a new node addition the list integrity is temporarily broken
 (this is also called {\it program invariant}).
 
 because during a new node addition the list integrity is temporarily broken
 (this is also called {\it program invariant}).
 


@@ -33,7 +42,7 @@ because during a new node addition the list integrity is temporarily broken
         s_mutexProtectingTheGlobalList->Unlock();
     }
 
         s_mutexProtectingTheGlobalList->Unlock();
     }
 

-    // return TRUE the given number is greater than all array elements
+    // return true if the given number is greater than all array elements

     bool MyThread::IsGreater(int num)
     {
         // before using the list we must acquire the mutex
     bool MyThread::IsGreater(int num)
     {
         // before using the list we must acquire the mutex


@@ -43,19 +52,32 @@ because during a new node addition the list integrity is temporarily broken
         for ( size_t n = 0; n < count; n++ )
         {
             if ( s_data[n] > num )
         for ( size_t n = 0; n < count; n++ )
         {
             if ( s_data[n] > num )

-                return FALSE;
+                return false;

         }
 
         }
 

-        return TRUE;
+        return true;

     }
 \end{verbatim}
 }
 
 Notice how wxMutexLocker was used in the second function to ensure that the
     }
 \end{verbatim}
 }
 
 Notice how wxMutexLocker was used in the second function to ensure that the

-mutex is unlocked in any case: whether the function returns TRUE or FALSE
+mutex is unlocked in any case: whether the function returns true or false

 (because the destructor of the local object {\it lock} is always called). Using
 this class instead of directly using wxMutex is, in general safer and is even
 (because the destructor of the local object {\it lock} is always called). Using
 this class instead of directly using wxMutex is, in general safer and is even

-more so if yoor program uses C++ exceptions.
+more so if your program uses C++ exceptions.
+
+\wxheading{Constants}
+
+\begin{verbatim}
+enum wxMutexType
+{
+    // normal mutex: try to always use this one
+    wxMUTEX_DEFAULT,
+
+    // recursive mutex: don't use these ones with wxCondition
+    wxMUTEX_RECURSIVE
+};
+\end{verbatim}

 
 \wxheading{Derived from}
 
 
 \wxheading{Derived from}
 


@@ -65,36 +87,38 @@ None.
 
 <wx/thread.h>
 
 
 <wx/thread.h>
 

+\wxheading{Library}
+
+\helpref{wxBase}{librarieslist}
+

 \wxheading{See also}
 
 \wxheading{See also}
 

-\helpref{wxThread}{wxthread}, \helpref{wxCondition}{wxcondition},
+\helpref{wxThread}{wxthread}, \helpref{wxCondition}{wxcondition}, 

 \helpref{wxMutexLocker}{wxmutexlocker}, \helpref{wxCriticalSection}{wxcriticalsection}
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 
 \helpref{wxMutexLocker}{wxmutexlocker}, \helpref{wxCriticalSection}{wxcriticalsection}
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 

-\membersection{wxMutex::wxMutex}\label{wxmutexconstr}

 
 

-\func{}{wxMutex}{\void}
+\membersection{wxMutex::wxMutex}\label{wxmutexctor}
+
+\func{}{wxMutex}{\param{wxMutexType }{type = {\tt wxMUTEX\_DEFAULT}}}

 
 Default constructor.
 
 
 Default constructor.
 

-\membersection{wxMutex::\destruct{wxMutex}}
+
+\membersection{wxMutex::\destruct{wxMutex}}\label{wxmutexdtor}

 
 \func{}{\destruct{wxMutex}}{\void}
 
 Destroys the wxMutex object.
 
 
 \func{}{\destruct{wxMutex}}{\void}
 
 Destroys the wxMutex object.
 

-\membersection{wxMutex::IsLocked}\label{wxmutexislocked}
-
-\constfunc{bool}{IsLocked}{\void}
-
-Returns TRUE if the mutex is locked, FALSE otherwise.

 
 \membersection{wxMutex::Lock}\label{wxmutexlock}
 
 \func{wxMutexError}{Lock}{\void}
 
 
 \membersection{wxMutex::Lock}\label{wxmutexlock}
 
 \func{wxMutexError}{Lock}{\void}
 

-Locks the mutex object.
+Locks the mutex object. This is equivalent to 
+\helpref{LockTimeout}{wxmutexlocktimeout} with infinite timeout.

 
 \wxheading{Return value}
 
 
 \wxheading{Return value}
 


@@ -104,9 +128,27 @@ One of:
 \begin{twocollist}\itemsep=0pt
 \twocolitem{{\bf wxMUTEX\_NO\_ERROR}}{There was no error.}
 \twocolitem{{\bf wxMUTEX\_DEAD\_LOCK}}{A deadlock situation was detected.}
 \begin{twocollist}\itemsep=0pt
 \twocolitem{{\bf wxMUTEX\_NO\_ERROR}}{There was no error.}
 \twocolitem{{\bf wxMUTEX\_DEAD\_LOCK}}{A deadlock situation was detected.}

-\twocolitem{{\bf wxMUTEX\_BUSY}}{The mutex is already locked by another thread.}

 \end{twocollist}
 
 \end{twocollist}
 

+
+\membersection{wxMutex::LockTimeout}\label{wxmutexlocktimeout}
+
+\func{wxMutexError}{LockTimeout}{\param{unsigned long}{ msec}}
+
+Try to lock the mutex object during the specified time interval.
+
+\wxheading{Return value}
+
+One of:
+
+\twocolwidtha{7cm}
+\begin{twocollist}\itemsep=0pt
+\twocolitem{{\bf wxMUTEX\_NO\_ERROR}}{Mutex successfully locked.}
+\twocolitem{{\bf wxMUTEX\_TIMEOUT}}{Mutex couldn't be acquired before timeout expiration.}
+\twocolitem{{\bf wxMUTEX\_DEAD\_LOCK}}{A deadlock situation was detected.}
+\end{twocollist}
+
+

 \membersection{wxMutex::TryLock}\label{wxmutextrylock}
 
 \func{wxMutexError}{TryLock}{\void}
 \membersection{wxMutex::TryLock}\label{wxmutextrylock}
 
 \func{wxMutexError}{TryLock}{\void}


@@ -120,10 +162,10 @@ One of:
 \twocolwidtha{7cm}
 \begin{twocollist}\itemsep=0pt
 \twocolitem{{\bf wxMUTEX\_NO\_ERROR}}{There was no error.}
 \twocolwidtha{7cm}
 \begin{twocollist}\itemsep=0pt
 \twocolitem{{\bf wxMUTEX\_NO\_ERROR}}{There was no error.}

-\twocolitem{{\bf wxMUTEX\_DEAD\_LOCK}}{A deadlock situation was detected.}

 \twocolitem{{\bf wxMUTEX\_BUSY}}{The mutex is already locked by another thread.}
 \end{twocollist}
 
 \twocolitem{{\bf wxMUTEX\_BUSY}}{The mutex is already locked by another thread.}
 \end{twocollist}
 

+

 \membersection{wxMutex::Unlock}\label{wxmutexunlock}
 
 \func{wxMutexError}{Unlock}{\void}
 \membersection{wxMutex::Unlock}\label{wxmutexunlock}
 
 \func{wxMutexError}{Unlock}{\void}


@@ -137,9 +179,6 @@ One of:
 \twocolwidtha{7cm}
 \begin{twocollist}\itemsep=0pt
 \twocolitem{{\bf wxMUTEX\_NO\_ERROR}}{There was no error.}
 \twocolwidtha{7cm}
 \begin{twocollist}\itemsep=0pt
 \twocolitem{{\bf wxMUTEX\_NO\_ERROR}}{There was no error.}

-\twocolitem{{\bf wxMUTEX\_DEAD\_LOCK}}{A deadlock situation was detected.}
-\twocolitem{{\bf wxMUTEX\_BUSY}}{The mutex is already locked by another thread.}
-\twocolitem{{\bf wxMUTEX\_UNLOCKED}}{The calling thread tries to unlock an unlocked mutex.}
+\twocolitem{{\bf wxMUTEX\_UNLOCKED}}{The calling thread doesn't own the mutex.}

 \end{twocollist}
 
 \end{twocollist}
 

-