]> git.saurik.com Git - wxWidgets.git/blob - interface/wx/msgqueue.h
Applied #14000 (wxRichTextXMLHandler interface fixes)
[wxWidgets.git] / 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