added interface headers with latest discussed changes

[wxWidgets.git] / interface / msgqueue.h

diff --git a/interface/msgqueue.h b/interface/msgqueue.h
new file mode 100644 (file)
index 0000000..43d076c
--- /dev/null
+++ b/interface/msgqueue.h
@@ -0,0 +1,75 @@
+/////////////////////////////////////////////////////////////////////////////
+// Name:        msgqueue.h
+// Purpose:     documentation for wxMessageQueue<T> class
+// Author:      wxWidgets team
+// RCS-ID:      $Id$
+// Licence:     wxWindows license
+/////////////////////////////////////////////////////////////////////////////
+
+/**
+    @class wxMessageQueueT
+    @wxheader{msgqueue.h}
+    
+    wxMessageQueue allows passing messages between threads.\r
+    
+    This class should be typically used to communicate between the main and worker\r
+    threads. The main thread calls wxMessageQueue::Post and\r
+    the worker thread calls wxMessageQueue::Receive.\r
+    
+    For this class a message is an object of arbitrary type T. Notice that\r
+    often there is a some special message indicating that the thread\r
+    should terminate as there is no other way to gracefully shutdown a thread\r
+    waiting on the message queue.\r
+    
+    @nolibrary
+    @category{FIXME}
+    
+    @seealso
+    wxThread
+*/
+class wxMessageQueue<T> 
+{
+public:
+    /**
+        Returns @true if the object had been initialized successfully, @false \r
+        if an error occurred.
+    */
+#define bool IsOk()     /* implementation is private */
+
+    /**
+        Add a message to this queue and signal the threads waiting for messages\r
+        (i.e. the threads which called wxMessageQueue::Receive or\r
+        wxMessageQueue::ReceiveTimeout).\r
+        
+        This method is safe to call from multiple threads in parallel.
+    */
+    wxMessageQueueError Post(T const& msg);
+
+    /**
+        Block until a message becomes available in the queue. Waits indefinitely long\r
+        or until an error occurs.\r
+        
+        The message is returned in @e msg.
+    */
+    wxMessageQueueError Receive(T& msg);
+
+    /**
+        Block until a message becomes available in the queue, but no more than\r
+        @e timeout milliseconds has elapsed.\r
+        
+        If no message is available after @e timeout milliseconds then returns\r
+        @b wxMSGQUEUE_TIMEOUT.\r
+        
+        If @e timeout is 0 then checks for any messages present in the queue\r
+        and returns immediately without waiting.\r
+        
+        The message is returned in @e msg.
+    */
+    wxMessageQueueError ReceiveTimeout(long timeout, T& msg);
+
+    /**
+        Default and only constructor. Use wxMessageQueue::IsOk to check\r
+        if the object was successfully initialized.
+    */
+     wxMessageQueue();
+};