]> git.saurik.com Git - wxWidgets.git/blame - interface/msgqueue.h
added interface headers with latest discussed changes
[wxWidgets.git] / interface / msgqueue.h
CommitLineData
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*/
30class wxMessageQueue<T>
31{
32public:
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};