interface/wx/msgqueue.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/msgqueue.h
   3 // Purpose:     interface of wxMessageQueue<T>
   4 // Author:      wxWidgets team
   5 // Licence:     wxWindows licence
   6 /////////////////////////////////////////////////////////////////////////////
   7
   8 /**
   9     Error codes for wxMessageQueue<> operations.
  10
  11     This enum contains the possible return value of wxMessageQueue<> methods.
  12
  13     @since 2.9.0
  14     @category{threading}
  15  */
  16 enum wxMessageQueueError
  17 {
  18     /// Indicates that the operation completed successfully.
  19     wxMSGQUEUE_NO_ERROR = 0,
  20
  21     /**
  22         Indicates that no messages were received before timeout expired.
  23
  24         This return value is only used by wxMessageQueue<>::ReceiveTimeout().
  25      */
  26     wxMSGQUEUE_TIMEOUT,
  27
  28     /// Some unexpected (and fatal) error has occurred.
  29     wxMSGQUEUE_MISC_ERROR
  30 };
  31
  32 /**
  33     wxMessageQueue allows passing messages between threads.
  34
  35     This class should be typically used to communicate between the main and worker
  36     threads. The main thread calls wxMessageQueue::Post and the worker thread
  37     calls wxMessageQueue::Receive.
  38
  39     @tparam T
  40         For this class a message is an object of arbitrary type T.
  41
  42     Notice that often there is a some special message indicating that the thread
  43     should terminate as there is no other way to gracefully shutdown a thread
  44     waiting on the message queue.
  45
  46     @since 2.9.0
  47
  48     @nolibrary
  49     @category{threading}
  50
  51     @see wxThread
  52 */
  53 template <typename T>
  54 class wxMessageQueue<T>
  55 {
  56 public:
  57     /**
  58         Default and only constructor.
  59         Use wxMessageQueue::IsOk to check if the object was successfully initialized.
  60     */
  61     wxMessageQueue();
  62
  63     /**
  64         Remove all messages from the queue.
  65
  66         This method is meant to be called from the same thread(s) that call
  67         Post() to discard any still pending requests if they became
  68         unnecessary.
  69
  70         @since 2.9.1
  71      */
  72     wxMessageQueueError Clear();
  73
  74     /**
  75         Returns @true if the object had been initialized successfully, @false
  76         if an error occurred.
  77     */
  78     bool IsOk() const;
  79
  80     /**
  81         Add a message to this queue and signal the threads waiting for messages
  82         (i.e. the threads which called wxMessageQueue::Receive or
  83         wxMessageQueue::ReceiveTimeout).
  84
  85         This method is safe to call from multiple threads in parallel.
  86     */
  87     wxMessageQueueError Post(T const& msg);
  88
  89     /**
  90         Block until a message becomes available in the queue.
  91         Waits indefinitely long or until an error occurs.
  92
  93         The message is returned in @a msg.
  94     */
  95     wxMessageQueueError Receive(T& msg);
  96
  97     /**
  98         Block until a message becomes available in the queue, but no more than
  99         @a timeout milliseconds has elapsed.
 100
 101         If no message is available after @a timeout milliseconds then returns
 102         @b wxMSGQUEUE_TIMEOUT.
 103
 104         If @a timeout is 0 then checks for any messages present in the queue
 105         and returns immediately without waiting.
 106
 107         The message is returned in @a msg.
 108     */
 109     wxMessageQueueError ReceiveTimeout(long timeout, T& msg);
 110 };
 111