interface/msgqueue.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        msgqueue.h
   3 // Purpose:     interface of wxMessageQueue<T>
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @wxheader{msgqueue.h}
  11
  12     wxMessageQueue allows passing messages between threads.
  13
  14     This class should be typically used to communicate between the main and worker
  15     threads. The main thread calls wxMessageQueue::Post and
  16     the worker thread calls wxMessageQueue::Receive.
  17
  18     For this class a message is an object of arbitrary type T. Notice that
  19     often there is a some special message indicating that the thread
  20     should terminate as there is no other way to gracefully shutdown a thread
  21     waiting on the message queue.
  22
  23     @nolibrary
  24     @category{FIXME}
  25
  26     @see wxThread
  27 */
  28 class wxMessageQueue<T>
  29 {
  30 public:
  31     /**
  32         Returns @true if the object had been initialized successfully, @false
  33         if an error occurred.
  34     */
  35     bool IsOk() const;
  36
  37     /**
  38         Add a message to this queue and signal the threads waiting for messages
  39         (i.e. the threads which called wxMessageQueue::Receive or
  40         wxMessageQueue::ReceiveTimeout).
  41         This method is safe to call from multiple threads in parallel.
  42     */
  43     wxMessageQueueError Post(T const& msg);
  44
  45     /**
  46         Block until a message becomes available in the queue. Waits indefinitely long
  47         or until an error occurs.
  48         The message is returned in @e msg.
  49     */
  50     wxMessageQueueError Receive(T& msg);
  51
  52     /**
  53         Block until a message becomes available in the queue, but no more than
  54         @a timeout milliseconds has elapsed.
  55         If no message is available after @a timeout milliseconds then returns
  56         @b wxMSGQUEUE_TIMEOUT.
  57         If @a timeout is 0 then checks for any messages present in the queue
  58         and returns immediately without waiting.
  59         The message is returned in @e msg.
  60     */
  61     wxMessageQueueError ReceiveTimeout(long timeout, T& msg);
  62
  63     /**
  64         Default and only constructor. Use wxMessageQueue::IsOk to check
  65         if the object was successfully initialized.
  66     */
  67     wxMessageQueue();
  68 };
  69