Document wxDataViewListModel as common abstract base class for

[wxWidgets.git] / interface / wx / thread.h

diff --git a/interface/wx/thread.h b/interface/wx/thread.h
index 0d27327b2549fc4f0311c704cca257fa01e49fb0..34d98462fdbe1b16bf89f26aa0031a3ac2ce1a95 100644 (file)
--- a/interface/wx/thread.h
+++ b/interface/wx/thread.h
@@ -3,7 +3,7 @@
 // Purpose:     interface of all thread-related wxWidgets classes
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
-// Licence:     wxWindows license
+// Licence:     wxWindows licence
 /////////////////////////////////////////////////////////////////////////////
 
 
@@ -309,14 +309,14 @@ public:
             char m_data[1024];
             wxCriticalSection m_dataCS; // protects field above
 
-            DECLARE_EVENT_TABLE()
+            wxDECLARE_EVENT_TABLE();
         };
 
         wxDEFINE_EVENT(wxEVT_COMMAND_MYTHREAD_UPDATE, wxThreadEvent)
-        BEGIN_EVENT_TABLE(MyFrame, wxFrame)
+        wxBEGIN_EVENT_TABLE(MyFrame, wxFrame)
             EVT_COMMAND(wxID_ANY, wxEVT_COMMAND_MYTHREAD_UPDATE, MyFrame::OnThreadUpdate)
             EVT_CLOSE(MyFrame::OnClose)
-        END_EVENT_TABLE()
+        wxEND_EVENT_TABLE()
 
         void MyFrame::DoStartALongTask()
         {
@@ -518,6 +518,10 @@ enum wxCriticalSectionType
     @library{wxbase}
     @category{threading}
 
+    @note Critical sections can be used before the wxWidgets library is fully
+          initialized. In particular, it's safe to create global
+          wxCriticalSection instances.
+
     @see wxThread, wxCondition, wxCriticalSectionLocker
 */
 class wxCriticalSection
@@ -535,11 +539,17 @@ public:
     ~wxCriticalSection();
 
     /**
-        Enter the critical section (same as locking a mutex).
-
+        Enter the critical section (same as locking a mutex): if another thread
+        has already entered it, this call will block until the other thread
+        calls Leave().
         There is no error return for this function.
-        After entering the critical section protecting some global
-        data the thread running in critical section may safely use/modify it.
+
+        After entering the critical section protecting a data variable,
+        the thread running inside the critical section may safely use/modify it.
+
+        Note that entering the same critical section twice or more from the same
+        thread doesn't result in a deadlock; in this case in fact this function will
+        immediately return.
     */
     void Enter();
 
@@ -677,15 +687,15 @@ enum
         MyThread *m_pThread;
         wxCriticalSection m_pThreadCS;    // protects the m_pThread pointer
 
-        DECLARE_EVENT_TABLE()
+        wxDECLARE_EVENT_TABLE();
     };
 
-    BEGIN_EVENT_TABLE(MyFrame, wxFrame)
+    wxBEGIN_EVENT_TABLE(MyFrame, wxFrame)
         EVT_CLOSE(MyFrame::OnClose)
         EVT_MENU(Minimal_Start,  MyFrame::DoStartThread)
         EVT_COMMAND(wxID_ANY, wxEVT_COMMAND_MYTHREAD_UPDATE, MyFrame::OnThreadUpdate)
         EVT_COMMAND(wxID_ANY, wxEVT_COMMAND_MYTHREAD_COMPLETED, MyFrame::OnThreadCompletion)
-    END_EVENT_TABLE()
+    wxEND_EVENT_TABLE()
 
     wxDEFINE_EVENT(wxEVT_COMMAND_MYTHREAD_COMPLETED, wxThreadEvent)
     wxDEFINE_EVENT(wxEVT_COMMAND_MYTHREAD_UPDATE, wxThreadEvent)
@@ -778,7 +788,7 @@ enum
 
             if (m_pThread)         // does the thread still exist?
             {
-                m_out.Printf("MYFRAME: deleting thread");
+                wxMessageOutputDebug().Printf("MYFRAME: deleting thread");
 
                 if (m_pThread->Delete() != wxTHREAD_NO_ERROR )
                     wxLogError("Can't delete the thread!");
@@ -983,7 +993,10 @@ public:
 
     /**
         Returns the platform specific thread ID of the current thread as a long.
+
         This can be used to uniquely identify threads, even if they are not wxThreads.
+
+        @see GetMainId()
     */
     static wxThreadIdType GetCurrentId();
 
@@ -1001,6 +1014,15 @@ public:
     */
     wxThreadKind GetKind() const;
 
+    /**
+        Returns the thread ID of the main thread.
+
+        @see IsMain()
+
+        @since 2.9.1
+     */
+    static wxThreadIdType GetMainId();
+
     /**
         Gets the priority of the thread, between zero and 100.
 
@@ -1029,6 +1051,11 @@ public:
 
     /**
         Returns @true if the calling thread is the main application thread.
+
+        Main thread in the context of wxWidgets is the one which initialized
+        the library.
+
+        @see GetMainId(), GetCurrentId()
     */
     static bool IsMain();
 
@@ -1098,6 +1125,10 @@ public:
         of detached threads.
 
         This function can only be called from another thread context.
+        
+        Finally, note that once a thread has completed and its Entry() function
+        returns, you cannot call Run() on it again (an assert will fail in debug
+        builds or @c wxTHREAD_RUNNING will be returned in release builds).
     */
     wxThreadError Run();
 
@@ -1506,6 +1537,9 @@ public:
         Locks the mutex object.
         This is equivalent to LockTimeout() with infinite timeout.
 
+        Note that if this mutex is already locked by the caller thread,
+        this function doesn't block but rather immediately returns.
+
         @return One of: @c wxMUTEX_NO_ERROR, @c wxMUTEX_DEAD_LOCK.
     */
     wxMutexError Lock();