no changes, just come cleanup and more comments

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

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%\r
%% Name:        msgqueue.tex\r
%% Purpose:     wxMessageQueue\r
%% Author:      Evgeniy Tarassov\r
%% Created:     2007-10-31\r
%% RCS-ID:      $Id: $\r
%% Copyright:   (C) 2007 TT-Solutions SARL\r
%% License:     wxWindows license\r
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%\r
\r
\section{\class{wxMessageQueue<T>}}\label{wxmessagequeue}\r
\r
wxMessageQueue allows passing messages between threads.\r
\r
This class should be typically used to communicate between the main and worker\r
threads. The main thread calls \helpref{Post()}{wxmessagequeuepost} and\r
the worker thread calls \helpref{Receive()}{wxmessagequeuereceive}.\r
\r
For this class a message is an object of arbitrary type T. Notice that\r
often there is a some special message indicating that the thread\r
should terminate as there is no other way to gracefully shutdown a thread\r
waiting on the message queue.\r
\r
\wxheading{Derived from}\r
\r
None.\r
\r
\wxheading{Include files}\r
\r
<wx/msgqueue.h>\r
\r
\wxheading{Library}\r
\r
None, this class implementation is entirely header-based.\r
\r
\wxheading{See also}\r
\r
\helpref{wxThread}{wxthread}\r
\r
\r
\latexignore{\rtfignore{\wxheading{Members}}}\r
\r
\r
\membersection{wxMessageQueue::wxMessageQueue}\label{wxmessagequeuector}\r
\r
\func{}{wxMessageQueue}{\void}\r
\r
Default and only constructor. Use \helpref{IsOk}{wxmessagequeueisok} to check\r
if the object was successfully initialized.\r
\r
\r
\membersection{wxMessageQueue::IsOk}\label{wxmessagequeueisok}\r
\r
\constfunc{bool }{IsOk}{\void}\r
\r
Returns {\tt true} if the object had been initialized successfully, {\tt false} \r
if an error occurred.\r
\r
\r
\membersection{wxMessageQueue::Post}\label{wxmessagequeuepost}\r
\r
\func{wxMessageQueueError }{Post}{\param{T const\&}{ msg}}\r
\r
Add a message to this queue and signal the threads waiting for messages\r
(i.e. the threads which called \helpref{Receive()}{wxmessagequeuereceive} or\r
\helpref{ReceiveTimeout()}{wxmessagequeuereceivetimeout}).\r
\r
This method is safe to call from multiple threads in parallel.\r
\r
\wxheading{Return value}\r
\r
One of:\r
\r
\twocolwidtha{7cm}\r
\begin{twocollist}\itemsep=0pt\r
\twocolitem{{\bf wxMSGQUEUE\_NO\_ERROR}}{There was no error.}\r
\twocolitem{{\bf wxMSGQUEUE\_MISC\_ERROR}}{A fatal error has occured.}\r
\end{twocollist}\r
\r
\r
\membersection{wxMessageQueue::Receive}\label{wxmessagequeuereceive}\r
\r
\func{wxMessageQueueError }{Receive}{\param{T\&}{ msg}}\r
\r
Block until a message becomes available in the queue. Waits indefinitely long\r
or until an error occurs.\r
\r
The message is returned in \arg{msg}.\r
\r
\wxheading{Return value}\r
\r
One of:\r
\r
\twocolwidtha{7cm}\r
\begin{twocollist}\itemsep=0pt\r
\twocolitem{{\bf wxMSGQUEUE\_NO\_ERROR}}{A message is available.}\r
\twocolitem{{\bf wxMSGQUEUE\_MISC\_ERROR}}{A fatal error has occured and no message returned.}\r
\end{twocollist}\r
\r
\r
\membersection{wxMessageQueue::ReceiveTimeout}\label{wxmessagequeuereceivetimeout}\r
\r
\func{wxMessageQueueError }{ReceiveTimeout}{\param{long}{ timeout}, \param{T\&}{ msg}}\r
\r
Block until a message becomes available in the queue, but no more than\r
\arg{timeout} milliseconds has elapsed.\r
\r
If no message is available after \arg{timeout} milliseconds then returns\r
{\bf wxMSGQUEUE\_TIMEOUT}.\r
\r
If \arg{timeout} is $0$ then checks for any messages present in the queue\r
and returns immediately without waiting.\r
\r
The message is returned in \arg{msg}.\r
\r
\wxheading{Return value}\r
\r
One of:\r
\r
\twocolwidtha{7cm}\r
\begin{twocollist}\itemsep=0pt\r
\twocolitem{{\bf wxMSGQUEUE\_NO\_ERROR}}{A message is available.}\r
\twocolitem{{\bf wxMSGQUEUE\_TIMEOUT}}{A timeout has occured. No message read.}\r
\twocolitem{{\bf wxMSGQUEUE\_MISC\_ERROR}}{A fatal error has occured.}\r
\end{twocollist}\r
\r