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