fixed another return FALSE in a function returning a pointer (patch 545046)

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

diff --git a/docs/latex/wx/conditn.tex b/docs/latex/wx/conditn.tex
index 47cc257e810a5d70ce45550c0497807566d431af..44ba4395096cba093bed5a68f6f8afc1a2e9d351 100644 (file)
--- a/docs/latex/wx/conditn.tex
+++ b/docs/latex/wx/conditn.tex
@@ -1,6 +1,78 @@
 \section{\class{wxCondition}}\label{wxcondition}
 
-Condition class for code protection in multithreaded applications.
+wxCondition variables correspond to pthread conditions or to Win32 event
+objects. They may be used in a multithreaded application to wait until the
+given condition becomes true which happens when the condition becomes signaled.
+
+For example, if a worker thread is doing some long task and another thread has
+to wait until it is finished, the latter thread will wait on the condition
+object and the worker thread will signal it on exit (this example is not
+perfect because in this particular case it would be much better to just 
+\helpref{Wait()}{wxthreadwait} for the worker thread, but if there are several
+worker threads it already makes much more sense).
+
+Note that a call to \helpref{Signal()}{wxconditionsignal} may happen before the
+other thread calls \helpref{Wait()}{wxconditionwait} and, just as with the
+pthread conditions, the signal is then lost and so if you want to be sure to
+get it you must use a mutex together with the condition variable.
+
+\wxheading{Example}
+
+This example shows how a main thread may launch a worker thread which starts
+running and then waits until the main thread signals it to continue:
+
+\begin{verbatim}
+class MyWaitingThread : public wxThread
+{
+public:
+    MyWaitingThread(wxMutex *mutex, wxCondition *condition)
+    {
+        m_mutex = mutex;
+        m_condition = condition;
+
+        Create();
+    }
+
+    virtual ExitCode Entry()
+    {
+        // wait for the signal from the main thread: it is absolutely necessary
+        // to look the mutex before doing it!
+        m_mutex->Lock();
+        m_condition->Signal();
+        m_mutex->Unlock();
+
+        ... do our job ...
+
+        return 0;
+    }
+
+private:
+    wxCondition *m_condition;
+};
+
+int main()
+{
+    wxMutex mutex;
+    wxCondition condition(mutex);
+
+    for ( int i = 0; i < 10; i++ )
+    {
+        MyWaitingThread *thread = new MyWaitingThread(&mutex, &condition);
+
+        thread->Run();
+    }
+
+    // wake up one of the threads
+    condition.Signal();
+
+    // wake up all the other ones
+    condition.Broadcast();
+
+    ... wait until they terminate or do something else ...
+
+    return 0;
+}
+\end{verbatim}
 
 \wxheading{Derived from}
 
@@ -18,41 +90,60 @@ None.
 
 \membersection{wxCondition::wxCondition}\label{wxconditionconstr}
 
-\func{}{wxCondition}{\void}
+\func{}{wxCondition}{\param{wxMutex\& }{mutex}}
 
-Default constructor.
+Default and only constructor. The {\it mutex} must be locked by the caller
+before calling \helpref{Wait}{wxconditionwait} function.
 
 \membersection{wxCondition::\destruct{wxCondition}}
 
 \func{}{\destruct{wxCondition}}{\void}
 
-Destroys the wxCondition object.
+Destroys the wxCondition object. The destructor is not virtual so this class
+should not be used polymorphically.
 
 \membersection{wxCondition::Broadcast}\label{wxconditionbroadcast}
 
 \func{void}{Broadcast}{\void}
 
-Broadcasts to all waiting objects.
+Broadcasts to all waiting threads, waking all of them up. Note that this method
+may be called whether the mutex associated with this condition is locked or
+not.
+
+\wxheading{See also}
+
+\helpref{wxCondition::Signal}{wxconditionsignal}
 
 \membersection{wxCondition::Signal}\label{wxconditionsignal}
 
 \func{void}{Signal}{\void}
 
-Signals the object.
+Signals the object waking up at most one thread. If several threads are waiting
+on the same condition, the exact thread which is woken up is undefined. If no
+threads are waiting, the signal is lost and the condition would have to be
+signalled again to wake up any thread which may start waiting on it later.
+
+Note that this method may be called whether the mutex associated with this
+condition is locked or not.
+
+\wxheading{See also}
+
+\helpref{wxCondition::Broadcast}{wxconditionbroadcast}
 
 \membersection{wxCondition::Wait}\label{wxconditionwait}
 
-\func{void}{Wait}{\param{wxMutex\&}{ mutex}}
+\func{void}{Wait}{\void}
 
-Waits indefinitely.
+Waits until the condition is signalled.
 
-\func{bool}{Wait}{\param{wxMutex\&}{ mutex}, \param{unsigned long}{ sec}, \param{unsigned long}{ nsec}}
+\func{bool}{Wait}{\param{unsigned long}{ sec}, \param{unsigned long}{ nsec}}
 
-Waits until a signal is raised or the timeout has elapsed.
+Waits until the condition is signalled or the timeout has elapsed.
 
-\wxheading{Parameters}
+Note that the mutex associated with this condition {\bf must} be acquired by
+the thread before calling this method.
 
-\docparam{mutex}{wxMutex object.}
+\wxheading{Parameters}
 
 \docparam{sec}{Timeout in seconds}
 
@@ -60,5 +151,7 @@ Waits until a signal is raised or the timeout has elapsed.
 
 \wxheading{Return value}
 
-The second form returns if the signal was raised, or FALSE if there was a timeout.
+The second form returns {\tt TRUE} if the condition has been signalled, or
+{\tt FALSE} if it returned because the timeout has elapsed.
+