added a note that wxStringList is obsolete

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

diff --git a/docs/latex/wx/conditn.tex b/docs/latex/wx/conditn.tex
index 47cc257e810a5d70ce45550c0497807566d431af..88b04eeb289e3870c86d28d97960011e28080d2b 100644 (file)
--- a/docs/latex/wx/conditn.tex
+++ b/docs/latex/wx/conditn.tex
@@ -1,6 +1,73 @@
 \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} but, in marked contrast
+with the pthread conditions, this will still work as the missed signals are
+queued and \helpref{Wait()}{wxconditionwait} simply returns immediately if
+there are ny pending signals.
+
+However, the calls to \helpref{Broadcast()}{wxconditionbroadcast} are {\bf not} 
+queued and so it will only wake up the threads already waiting on the
+condition. Accordingly, you will probably want to use a mutex to ensure that
+the thread(s) you want to be waken up have indeed started to wait before
+calling \helpref{Broadcast()}{wxconditionbroadcast}.
+
+\wxheading{Example}
+
+This example shows how a main thread may launch a worker thread and wait until
+it starts running:
+
+\begin{verbatim}
+class MyWaitingThread : public wxThread
+{
+public:
+    MyWaitingThread(wxCondition *condition)
+    {
+        m_condition = condition;
+
+        Create();
+    }
+
+    virtual ExitCode Entry()
+    {
+        // let the main thread know that we started running
+        m_condition->Signal();
+
+        ... do our job ...
+
+        return 0;
+    }
+
+private:
+    wxCondition *m_condition;
+};
+
+int main()
+{
+    wxCondition condition;
+    MyWaitingThread *thread - new MyWaitingThread(&condition);
+
+    thread->Run();
+
+    // wait until the thread really starts running
+    condition.Wait();
+
+    ...
+
+    return 0;
+}
+\end{verbatim}
 
 \wxheading{Derived from}
 
@@ -42,18 +109,16 @@ Signals the object.
 
 \membersection{wxCondition::Wait}\label{wxconditionwait}
 
-\func{void}{Wait}{\param{wxMutex\&}{ mutex}}
+\func{void}{Wait}{\void}
 
 Waits indefinitely.
 
-\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.
 
 \wxheading{Parameters}
 
-\docparam{mutex}{wxMutex object.}
-
 \docparam{sec}{Timeout in seconds}
 
 \docparam{nsec}{Timeout nanoseconds component (added to {\it sec}).}