added wxFontMapper::Get/Set

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

diff --git a/docs/latex/wx/conditn.tex b/docs/latex/wx/conditn.tex
index 777a3cd226aaf48afb22db2f16aaaf3ab37a57ae..44ba4395096cba093bed5a68f6f8afc1a2e9d351 100644 (file)
--- a/docs/latex/wx/conditn.tex
+++ b/docs/latex/wx/conditn.tex
@@ -5,12 +5,75 @@ 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'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).
 
+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}
 
 None.
@@ -27,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}
 
@@ -69,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.
+