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     @since 2.9.0
  24
  25     @nolibrary
  26     @category{threading}
  27
  28     @see wxThread
  29 */
  30 template <typename T>
  31 class wxMessageQueue<T>
  32 {
  33 public:
  34     /**
  35         Default and only constructor.
  36         Use wxMessageQueue::IsOk to check if the object was successfully initialized.
  37     */
  38     wxMessageQueue();
  39
  40     /**
  41         Remove all messages from the queue.
  42
  43         This method is meant to be called from the same thread(s) that call
  44         Post() to discard any still pending requests if they became
  45         unnecessary.
  46
  47         @since 2.9.1
  48      */
  49     wxMessageQueueError Clear();
  50
  51     /**
  52         Returns @true if the object had been initialized successfully, @false
  53         if an error occurred.
  54     */
  55     bool IsOk() const;
  56
  57     /**
  58         Add a message to this queue and signal the threads waiting for messages
  59         (i.e. the threads which called wxMessageQueue::Receive or
  60         wxMessageQueue::ReceiveTimeout).
  61
  62         This method is safe to call from multiple threads in parallel.
  63     */
  64     wxMessageQueueError Post(T const& msg);
  65
  66     /**
  67         Block until a message becomes available in the queue.
  68         Waits indefinitely long or until an error occurs.
  69
  70         The message is returned in @a msg.
  71     */
  72     wxMessageQueueError Receive(T& msg);
  73
  74     /**
  75         Block until a message becomes available in the queue, but no more than
  76         @a timeout milliseconds has elapsed.
  77
  78         If no message is available after @a timeout milliseconds then returns
  79         @b wxMSGQUEUE_TIMEOUT.
  80
  81         If @a timeout is 0 then checks for any messages present in the queue
  82         and returns immediately without waiting.
  83
  84         The message is returned in @a msg.
  85     */
  86     wxMessageQueueError ReceiveTimeout(long timeout, T& msg);
  87 };
  88