]>
Commit | Line | Data |
---|---|---|
23324ae1 FM |
1 | ///////////////////////////////////////////////////////////////////////////// |
2 | // Name: msgqueue.h | |
3 | // Purpose: documentation for wxMessageQueue<T> class | |
4 | // Author: wxWidgets team | |
5 | // RCS-ID: $Id$ | |
6 | // Licence: wxWindows license | |
7 | ///////////////////////////////////////////////////////////////////////////// | |
8 | ||
9 | /** | |
10 | @class wxMessageQueueT | |
11 | @wxheader{msgqueue.h} | |
12 | ||
13 | wxMessageQueue allows passing messages between threads.\r | |
14 | ||
15 | This class should be typically used to communicate between the main and worker\r | |
16 | threads. The main thread calls wxMessageQueue::Post and\r | |
17 | the worker thread calls wxMessageQueue::Receive.\r | |
18 | ||
19 | For this class a message is an object of arbitrary type T. Notice that\r | |
20 | often there is a some special message indicating that the thread\r | |
21 | should terminate as there is no other way to gracefully shutdown a thread\r | |
22 | waiting on the message queue.\r | |
23 | ||
24 | @nolibrary | |
25 | @category{FIXME} | |
26 | ||
27 | @seealso | |
28 | wxThread | |
29 | */ | |
30 | class wxMessageQueue<T> | |
31 | { | |
32 | public: | |
33 | /** | |
34 | Returns @true if the object had been initialized successfully, @false \r | |
35 | if an error occurred. | |
36 | */ | |
37 | #define bool IsOk() /* implementation is private */ | |
38 | ||
39 | /** | |
40 | Add a message to this queue and signal the threads waiting for messages\r | |
41 | (i.e. the threads which called wxMessageQueue::Receive or\r | |
42 | wxMessageQueue::ReceiveTimeout).\r | |
43 | ||
44 | This method is safe to call from multiple threads in parallel. | |
45 | */ | |
46 | wxMessageQueueError Post(T const& msg); | |
47 | ||
48 | /** | |
49 | Block until a message becomes available in the queue. Waits indefinitely long\r | |
50 | or until an error occurs.\r | |
51 | ||
52 | The message is returned in @e msg. | |
53 | */ | |
54 | wxMessageQueueError Receive(T& msg); | |
55 | ||
56 | /** | |
57 | Block until a message becomes available in the queue, but no more than\r | |
58 | @e timeout milliseconds has elapsed.\r | |
59 | ||
60 | If no message is available after @e timeout milliseconds then returns\r | |
61 | @b wxMSGQUEUE_TIMEOUT.\r | |
62 | ||
63 | If @e timeout is 0 then checks for any messages present in the queue\r | |
64 | and returns immediately without waiting.\r | |
65 | ||
66 | The message is returned in @e msg. | |
67 | */ | |
68 | wxMessageQueueError ReceiveTimeout(long timeout, T& msg); | |
69 | ||
70 | /** | |
71 | Default and only constructor. Use wxMessageQueue::IsOk to check\r | |
72 | if the object was successfully initialized. | |
73 | */ | |
74 | wxMessageQueue(); | |
75 | }; |