interface/msgqueue.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        msgqueue.h
   3 // Purpose:     documentation for wxMessageQueue<T> class
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxMessageQueueT
  11     @wxheader{msgqueue.h}
  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 wxMessageQueue::Post and
  17     the worker thread calls wxMessageQueue::Receive.
  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     @nolibrary
  25     @category{FIXME}
  26
  27     @seealso
  28     wxThread
  29 */
  30 class wxMessageQueue<T>
  31 {
  32 public:
  33     /**
  34         Returns @true if the object had been initialized successfully, @false
  35         if an error occurred.
  36     */
  37 #define bool IsOk()     /* implementation is private */
  38
  39     /**
  40         Add a message to this queue and signal the threads waiting for messages
  41         (i.e. the threads which called wxMessageQueue::Receive or
  42         wxMessageQueue::ReceiveTimeout).
  43
  44         This method is safe to call from multiple threads in parallel.
  45     */
  46     wxMessageQueueError Post(T const& msg);
  47
  48     /**
  49         Block until a message becomes available in the queue. Waits indefinitely long
  50         or until an error occurs.
  51
  52         The message is returned in @e msg.
  53     */
  54     wxMessageQueueError Receive(T& msg);
  55
  56     /**
  57         Block until a message becomes available in the queue, but no more than
  58         @e timeout milliseconds has elapsed.
  59
  60         If no message is available after @e timeout milliseconds then returns
  61         @b wxMSGQUEUE_TIMEOUT.
  62
  63         If @e timeout is 0 then checks for any messages present in the queue
  64         and returns immediately without waiting.
  65
  66         The message is returned in @e msg.
  67     */
  68     wxMessageQueueError ReceiveTimeout(long timeout, T& msg);
  69
  70     /**
  71         Default and only constructor. Use wxMessageQueue::IsOk to check
  72         if the object was successfully initialized.
  73     */
  74     wxMessageQueue();
  75 };