interface/wx/msgqueue.h

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