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