Some work on GTK focus handling and events.

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

\section{\class{wxCondition}}\label{wxcondition}

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}

None.

\wxheading{Include files}

<wx/thread.h>

\wxheading{See also}

\helpref{wxThread}{wxthread}, \helpref{wxMutex}{wxmutex}

\latexignore{\rtfignore{\wxheading{Members}}}

\membersection{wxCondition::wxCondition}\label{wxconditionconstr}

\func{}{wxCondition}{\void}

Default constructor.

\membersection{wxCondition::\destruct{wxCondition}}

\func{}{\destruct{wxCondition}}{\void}

Destroys the wxCondition object.

\membersection{wxCondition::Broadcast}\label{wxconditionbroadcast}

\func{void}{Broadcast}{\void}

Broadcasts to all waiting objects.

\membersection{wxCondition::Signal}\label{wxconditionsignal}

\func{void}{Signal}{\void}

Signals the object.

\membersection{wxCondition::Wait}\label{wxconditionwait}

\func{void}{Wait}{\void}

Waits indefinitely.

\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{sec}{Timeout in seconds}

\docparam{nsec}{Timeout nanoseconds component (added to {\it sec}).}

\wxheading{Return value}

The second form returns if the signal was raised, or FALSE if there was a timeout.