docs/latex/wx/msgqueue.tex

   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::ReceiveTimeout}\label{wxmessagequeuereceivetimeout}
 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