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

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% 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::Receive}\label{wxmessagequeuereceive}

\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}
Commit	Line	Data
6aaee6af VZ	1	%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
	2	%% Name: msgqueue.tex
	3	%% Purpose: wxMessageQueue
	4	%% Author: Evgeniy Tarassov
	5	%% Created: 2007-10-31
	6	%% RCS-ID: $Id: $
	7	%% Copyright: (C) 2007 TT-Solutions SARL
	8	%% License: wxWindows license
	9	%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
	10
	11	\section{\class{wxMessageQueue<T>}}\label{wxmessagequeue}
	12
	13	wxMessageQueue allows passing messages between threads.
	14
	15	This class should be typically used to communicate between the main and worker
	16	threads. The main thread calls \helpref{Post()}{wxmessagequeuepost} and
	17	the worker thread calls \helpref{Receive()}{wxmessagequeuereceive}.
	18
	19	For this class a message is an object of arbitrary type T. Notice that
	20	often there is a some special message indicating that the thread
	21	should terminate as there is no other way to gracefully shutdown a thread
	22	waiting on the message queue.
	23
	24	\wxheading{Derived from}
	25
	26	None.
	27
	28	\wxheading{Include files}
	29
	30	<wx/msgqueue.h>
	31
	32	\wxheading{Library}
	33
	34	None, this class implementation is entirely header-based.
	35
	36	\wxheading{See also}
	37
	38	\helpref{wxThread}{wxthread}
	39
	40
	41	\latexignore{\rtfignore{\wxheading{Members}}}
	42
	43
	44	\membersection{wxMessageQueue::wxMessageQueue}\label{wxmessagequeuector}
	45
	46	\func{}{wxMessageQueue}{\void}
	47
	48	Default and only constructor. Use \helpref{IsOk}{wxmessagequeueisok} to check
	49	if the object was successfully initialized.
	50
	51
	52	\membersection{wxMessageQueue::IsOk}\label{wxmessagequeueisok}
	53
	54	\constfunc{bool }{IsOk}{\void}
	55
	56	Returns {\tt true} if the object had been initialized successfully, {\tt false}
	57	if an error occurred.
	58
	59
	60	\membersection{wxMessageQueue::Post}\label{wxmessagequeuepost}
	61
	62	\func{wxMessageQueueError }{Post}{\param{T const\&}{ msg}}
	63
	64	Add a message to this queue and signal the threads waiting for messages
65	(i.e. the threads which called \helpref{Receive()}{wxmessagequeuereceive} or
66	\helpref{ReceiveTimeout()}{wxmessagequeuereceivetimeout}).
67
68	This method is safe to call from multiple threads in parallel.
69
70	\wxheading{Return value}
71
72	One of:
73
74	\twocolwidtha{7cm}
75	\begin{twocollist}\itemsep=0pt
76	\twocolitem{{\bf wxMSGQUEUE\_NO\_ERROR}}{There was no error.}
77	\twocolitem{{\bf wxMSGQUEUE\_MISC\_ERROR}}{A fatal error has occured.}
78	\end{twocollist}
79
80
81	\membersection{wxMessageQueue::Receive}\label{wxmessagequeuereceive}
82
83	\func{wxMessageQueueError }{Receive}{\param{T\&}{ msg}}
84
85	Block until a message becomes available in the queue. Waits indefinitely long
86	or until an error occurs.
87
88	The message is returned in \arg{msg}.
89
90	\wxheading{Return value}
91
92	One of:
93
94	\twocolwidtha{7cm}
95	\begin{twocollist}\itemsep=0pt
96	\twocolitem{{\bf wxMSGQUEUE\_NO\_ERROR}}{A message is available.}
97	\twocolitem{{\bf wxMSGQUEUE\_MISC\_ERROR}}{A fatal error has occured and no message returned.}
98	\end{twocollist}
99
100
101	\membersection{wxMessageQueue::Receive}\label{wxmessagequeuereceive}
102
103	\func{wxMessageQueueError }{ReceiveTimeout}{\param{long}{ timeout}, \param{T\&}{ msg}}
104
105	Block until a message becomes available in the queue, but no more than
106	\arg{timeout} milliseconds has elapsed.
107
108	If no message is available after \arg{timeout} milliseconds then returns
109	{\bf wxMSGQUEUE\_TIMEOUT}.
110
111	If \arg{timeout} is $0$ then checks for any messages present in the queue
112	and returns immediately without waiting.
113
114	The message is returned in \arg{msg}.
115
116	\wxheading{Return value}
117
118	One of:
119
120	\twocolwidtha{7cm}
121	\begin{twocollist}\itemsep=0pt
122	\twocolitem{{\bf wxMSGQUEUE\_NO\_ERROR}}{A message is available.}
123	\twocolitem{{\bf wxMSGQUEUE\_TIMEOUT}}{A timeout has occured. No message read.}
124	\twocolitem{{\bf wxMSGQUEUE\_MISC\_ERROR}}{A fatal error has occured.}
125	\end{twocollist}
126