Some work on GTK focus handling and events.

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

diff --git a/docs/latex/wx/conditn.tex b/docs/latex/wx/conditn.tex
index 777a3cd226aaf48afb22db2f16aaaf3ab37a57ae..88b04eeb289e3870c86d28d97960011e28080d2b 100644 (file)
--- a/docs/latex/wx/conditn.tex
+++ b/docs/latex/wx/conditn.tex
@@ -5,12 +5,70 @@ 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
 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's finished, the latter thread will wait on the condition
+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).
 
 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}
 
 None.
 \wxheading{Derived from}
 
 None.


@@ -51,18 +109,16 @@ Signals the object.
 
 \membersection{wxCondition::Wait}\label{wxconditionwait}
 
 
 \membersection{wxCondition::Wait}\label{wxconditionwait}
 

-\func{void}{Wait}{\param{wxMutex\&}{ mutex}}
+\func{void}{Wait}{\void}

 
 Waits indefinitely.
 
 
 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}
 
 
 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}).}
 \docparam{sec}{Timeout in seconds}
 
 \docparam{nsec}{Timeout nanoseconds component (added to {\it sec}).}