%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Name:        msgqueue.tex
%% Purpose:     wxMessageQueue
%% Author:      Evgeniy Tarassov
%% Created:     2007-10-31
%% RCS-ID:      $Id: $
%% Copyright:   (C) 2007 TT-Solutions SARL
%% License:     wxWindows license
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{\class{wxMessageQueue<T>}}\label{wxmessagequeue}

wxMessageQueue allows passing messages between threads.

This class should be typically used to communicate between the main and worker
threads. The main thread calls \helpref{Post()}{wxmessagequeuepost} and
the worker thread calls \helpref{Receive()}{wxmessagequeuereceive}.

For this class a message is an object of arbitrary type T. Notice that
often there is a some special message indicating that the thread
should terminate as there is no other way to gracefully shutdown a thread
waiting on the message queue.

\wxheading{Derived from}

None.

\wxheading{Include files}

<wx/msgqueue.h>

\wxheading{Library}

None, this class implementation is entirely header-based.

\wxheading{See also}

\helpref{wxThread}{wxthread}


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


\membersection{wxMessageQueue::wxMessageQueue}\label{wxmessagequeuector}

\func{}{wxMessageQueue}{\void}

Default and only constructor. Use \helpref{IsOk}{wxmessagequeueisok} to check
if the object was successfully initialized.


\membersection{wxMessageQueue::IsOk}\label{wxmessagequeueisok}

\constfunc{bool }{IsOk}{\void}

Returns {\tt true} if the object had been initialized successfully, {\tt false} 
if an error occurred.


\membersection{wxMessageQueue::Post}\label{wxmessagequeuepost}

\func{wxMessageQueueError }{Post}{\param{T const\&}{ msg}}

Add a message to this queue and signal the threads waiting for messages
(i.e. the threads which called \helpref{Receive()}{wxmessagequeuereceive} or
\helpref{ReceiveTimeout()}{wxmessagequeuereceivetimeout}).

This method is safe to call from multiple threads in parallel.

\wxheading{Return value}

One of:

\twocolwidtha{7cm}
\begin{twocollist}\itemsep=0pt
\twocolitem{{\bf wxMSGQUEUE\_NO\_ERROR}}{There was no error.}
\twocolitem{{\bf wxMSGQUEUE\_MISC\_ERROR}}{A fatal error has occured.}
\end{twocollist}


\membersection{wxMessageQueue::Receive}\label{wxmessagequeuereceive}

\func{wxMessageQueueError }{Receive}{\param{T\&}{ msg}}

Block until a message becomes available in the queue. Waits indefinitely long
or until an error occurs.

The message is returned in \arg{msg}.

\wxheading{Return value}

One of:

\twocolwidtha{7cm}
\begin{twocollist}\itemsep=0pt
\twocolitem{{\bf wxMSGQUEUE\_NO\_ERROR}}{A message is available.}
\twocolitem{{\bf wxMSGQUEUE\_MISC\_ERROR}}{A fatal error has occured and no message returned.}
\end{twocollist}


\membersection{wxMessageQueue::ReceiveTimeout}\label{wxmessagequeuereceivetimeout}

\func{wxMessageQueueError }{ReceiveTimeout}{\param{long}{ timeout}, \param{T\&}{ msg}}

Block until a message becomes available in the queue, but no more than
\arg{timeout} milliseconds has elapsed.

If no message is available after \arg{timeout} milliseconds then returns
{\bf wxMSGQUEUE\_TIMEOUT}.

If \arg{timeout} is $0$ then checks for any messages present in the queue
and returns immediately without waiting.

The message is returned in \arg{msg}.

\wxheading{Return value}

One of:

\twocolwidtha{7cm}
\begin{twocollist}\itemsep=0pt
\twocolitem{{\bf wxMSGQUEUE\_NO\_ERROR}}{A message is available.}
\twocolitem{{\bf wxMSGQUEUE\_TIMEOUT}}{A timeout has occured. No message read.}
\twocolitem{{\bf wxMSGQUEUE\_MISC\_ERROR}}{A fatal error has occured.}
\end{twocollist}