X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/5159e01481609101d7bf20b3e32457346e631df6..92c0fc34c104c8d7c12d6a3b78ea232690fc23f4:/interface/wx/thread.h?ds=sidebyside

diff --git a/interface/wx/thread.h b/interface/wx/thread.h
index c454f8e925..61becf5847 100644
--- a/interface/wx/thread.h
+++ b/interface/wx/thread.h
@@ -2,8 +2,7 @@
 // Name:        thread.h
 // Purpose:     interface of all thread-related wxWidgets classes
 // Author:      wxWidgets team
-// RCS-ID:      $Id$
-// Licence:     wxWindows license
+// Licence:     wxWindows licence
 /////////////////////////////////////////////////////////////////////////////
 
 
@@ -51,8 +50,6 @@ enum wxCondError
         {
             m_mutex = mutex;
             m_condition = condition;
-
-            Create();
         }
 
         virtual ExitCode Entry()
@@ -172,6 +169,33 @@ public:
     */
     wxCondError Wait();
 
+    /**
+        Waits until the condition is signalled and the associated condition true.
+
+        This is a convenience overload that may be used to ignore spurious
+        awakenings while waiting for a specific condition to become true.
+
+        Equivalent to
+        @code
+        while ( !predicate() )
+        {
+            wxCondError e = Wait();
+            if ( e != wxCOND_NO_ERROR )
+                return e;
+        }
+        return wxCOND_NO_ERROR;
+        @endcode
+
+        The predicate would typically be a C++11 lambda:
+        @code
+        condvar.Wait([]{return value == 1;});
+        @endcode
+
+        @since 3.0
+    */
+    template<typename Functor>
+    wxCondError Wait(const Functor& predicate);
+
     /**
         Waits until the condition is signalled or the timeout has elapsed.
 
@@ -279,7 +303,7 @@ public:
 
     Example:
     @code
-        extern const wxEventType wxEVT_COMMAND_MYTHREAD_UPDATE;
+        wxDECLARE_EVENT(myEVT_THREAD_UPDATE, wxThreadEvent);
 
         class MyFrame : public wxFrame, public wxThreadHelper
         {
@@ -298,7 +322,7 @@ public:
 
             ...
             void DoStartALongTask();
-            void OnThreadUpdate(wxCommandEvent& evt);
+            void OnThreadUpdate(wxThreadEvent& evt);
             void OnClose(wxCloseEvent& evt);
             ...
 
@@ -309,14 +333,14 @@ public:
             char m_data[1024];
             wxCriticalSection m_dataCS; // protects field above
 
-            DECLARE_EVENT_TABLE()
+            wxDECLARE_EVENT_TABLE();
         };
 
-        DEFINE_EVENT_TYPE(wxEVT_COMMAND_MYTHREAD_UPDATE)
-        BEGIN_EVENT_TABLE(MyFrame, wxFrame)
-            EVT_COMMAND(wxID_ANY, wxEVT_COMMAND_MYTHREAD_UPDATE, MyFrame::OnThreadUpdate)
+        wxDEFINE_EVENT(myEVT_THREAD_UPDATE, wxThreadEvent)
+        wxBEGIN_EVENT_TABLE(MyFrame, wxFrame)
+            EVT_THREAD(wxID_ANY, myEVT_THREAD_UPDATE, MyFrame::OnThreadUpdate)
             EVT_CLOSE(MyFrame::OnClose)
-        END_EVENT_TABLE()
+        wxEND_EVENT_TABLE()
 
         void MyFrame::DoStartALongTask()
         {
@@ -355,7 +379,7 @@ public:
                 download_chunk(buffer, 1024);     // this takes time...
 
                 {
-                    // ensure noone reads m_data while we write it
+                    // ensure no one reads m_data while we write it
                     wxCriticalSectionLocker lock(m_dataCS);
                     memcpy(m_data+offset, buffer, 1024);
                     offset += 1024;
@@ -364,7 +388,7 @@ public:
 
                 // VERY IMPORTANT: do not call any GUI function inside this
                 //                 function; rather use wxQueueEvent():
-                wxQueueEvent(this, new wxCommandEvent(wxEVT_COMMAND_MYTHREAD_UPDATE));
+                wxQueueEvent(this, new wxThreadEvent(wxEVT_COMMAND_MYTHREAD_UPDATE));
                     // we used pointer 'this' assuming it's safe; see OnClose()
             }
 
@@ -386,7 +410,7 @@ public:
             Destroy();
         }
 
-        void MyFrame::OnThreadUpdate(wxCommandEvent&evt)
+        void MyFrame::OnThreadUpdate(wxThreadEvent& evt)
         {
             // ...do something... e.g. m_pGauge->Pulse();
 
@@ -399,7 +423,7 @@ public:
     @library{wxbase}
     @category{threading}
 
-    @see wxThread
+    @see wxThread, wxThreadEvent
 */
 class wxThreadHelper
 {
@@ -454,6 +478,43 @@ public:
     */
     virtual ExitCode Entry() = 0;
 
+    /**
+        Callback called by Delete() before actually deleting the thread.
+
+        This function can be overridden by the derived class to perform some
+        specific task when the thread is gracefully destroyed. Notice that it
+        will be executed in the context of the thread that called Delete() and
+        <b>not</b> in this thread's context.
+
+        TestDestroy() will be true for the thread before OnDelete() gets
+        executed.
+
+        @since 2.9.2
+
+        @see OnKill()
+    */
+    virtual void OnDelete();
+
+    /**
+        Callback called by Kill() before actually killing the thread.
+
+        This function can be overridden by the derived class to perform some
+        specific task when the thread is terminated. Notice that it will be
+        executed in the context of the thread that called Kill() and <b>not</b>
+        in this thread's context.
+
+        @since 2.9.2
+
+        @see OnDelete()
+    */
+    virtual void OnKill();
+
+    /**
+        @deprecated
+        Use CreateThread() instead.
+    */
+    wxThreadError Create(unsigned int stackSize = 0);
+
     /**
         Creates a new thread of the given @a kind.
 
@@ -507,11 +568,15 @@ enum wxCriticalSectionType
 
     Finally, you should try to use wxCriticalSectionLocker class whenever
     possible instead of directly using wxCriticalSection for the same reasons
-    wxMutexLocker is preferrable to wxMutex - please see wxMutex for an example.
+    wxMutexLocker is preferable to wxMutex - please see wxMutex for an example.
 
     @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
@@ -529,14 +594,28 @@ 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();
 
+    /**
+        Try to enter the critical section (same as trying to lock a mutex).
+        If it can't, immediately returns false.
+
+        @since 2.9.3
+    */
+    bool TryEnter();
+
     /**
         Leave the critical section allowing other threads use the global data
         protected by it. There is no error return for this function.
@@ -544,6 +623,46 @@ public:
     void Leave();
 };
 
+/**
+    The possible thread wait types.
+
+    @since 2.9.2
+*/
+enum wxThreadWait
+{
+    /**
+        No events are processed while waiting.
+
+        This is the default under all platforms except for wxMSW.
+     */
+    wxTHREAD_WAIT_BLOCK,
+
+    /**
+        Yield for event dispatching while waiting.
+
+        This flag is dangerous as it exposes the program using it to unexpected
+        reentrancies in the same way as calling wxYield() function does so you
+        are strongly advised to avoid its use and not wait for the thread
+        termination from the main (GUI) thread at all to avoid making your
+        application unresponsive.
+
+        Also notice that this flag is not portable as it is only implemented in
+        wxMSW and simply ignored under the other platforms.
+     */
+    wxTHREAD_WAIT_YIELD,
+
+    /**
+        Default wait mode for wxThread::Wait() and wxThread::Delete().
+
+        For compatibility reasons, the default wait mode is currently
+        wxTHREAD_WAIT_YIELD if WXWIN_COMPATIBILITY_2_8 is defined (and it is
+        by default). However, as mentioned above, you're strongly encouraged to
+        not use wxTHREAD_WAIT_YIELD and pass wxTHREAD_WAIT_BLOCK to wxThread
+        method explicitly.
+     */
+    wxTHREAD_WAIT_DEFAULT = wxTHREAD_WAIT_YIELD
+};
+
 /**
   The possible thread kinds.
 */
@@ -580,17 +699,6 @@ enum wxThreadError
     wxTHREAD_MISC_ERROR
 };
 
-/**
-   Defines the interval of priority
-*/
-enum
-{
-    WXTHREAD_MIN_PRIORITY      = 0u,
-    WXTHREAD_DEFAULT_PRIORITY  = 50u,
-    WXTHREAD_MAX_PRIORITY      = 100u
-};
-
-
 /**
     @class wxThread
 
@@ -610,10 +718,10 @@ enum
     @section thread_types Types of wxThreads
 
     There are two types of threads in wxWidgets: @e detached and @e joinable,
-    modeled after the the POSIX thread API. This is different from the Win32 API
+    modeled after the POSIX thread API. This is different from the Win32 API
     where all threads are joinable.
 
-    By default wxThreads in wxWidgets use the @b detached behavior.
+    By default wxThreads in wxWidgets use the @b detached behaviour.
     Detached threads delete themselves once they have completed, either by themselves
     when they complete processing or through a call to Delete(), and thus
     @b must be created on the heap (through the new operator, for example).
@@ -625,8 +733,8 @@ enum
 
     @code
     // declare a new type of event, to be used by our MyThread class:
-    extern const wxEventType wxEVT_COMMAND_MYTHREAD_COMPLETED;
-    extern const wxEventType wxEVT_COMMAND_MYTHREAD_UPDATE;
+    wxDECLARE_EVENT(wxEVT_COMMAND_MYTHREAD_COMPLETED, wxThreadEvent);
+    wxDECLARE_EVENT(wxEVT_COMMAND_MYTHREAD_UPDATE, wxThreadEvent);
     class MyFrame;
 
     class MyThread : public wxThread
@@ -663,50 +771,42 @@ enum
         // a resume routine would be nearly identic to DoPauseThread()
         void DoResumeThread() { ... }
 
-        void OnThreadCompletion(wxCommandEvent&);
+        void OnThreadUpdate(wxThreadEvent&);
+        void OnThreadCompletion(wxThreadEvent&);
         void OnClose(wxCloseEvent&);
 
     protected:
         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()
 
-    DEFINE_EVENT_TYPE(wxEVT_COMMAND_MYTHREAD_COMPLETED)
-    DEFINE_EVENT_TYPE(wxEVT_COMMAND_MYTHREAD_UPDATE)
+    wxDEFINE_EVENT(wxEVT_COMMAND_MYTHREAD_COMPLETED, wxThreadEvent)
+    wxDEFINE_EVENT(wxEVT_COMMAND_MYTHREAD_UPDATE, wxThreadEvent)
 
     void MyFrame::DoStartThread()
     {
         m_pThread = new MyThread(this);
 
-        if ( m_pThread->Create() != wxTHREAD_NO_ERROR )
+        if ( m_pThread->Run() != wxTHREAD_NO_ERROR )
         {
             wxLogError("Can't create the thread!");
             delete m_pThread;
             m_pThread = NULL;
         }
-        else
-        {
-            if (m_pThread->Run() != wxTHREAD_NO_ERROR )
-            {
-                wxLogError("Can't create the thread!");
-                delete m_pThread;
-                m_pThread = NULL;
-            }
 
-            // after the call to wxThread::Run(), the m_pThread pointer is "unsafe":
-            // at any moment the thread may cease to exist (because it completes its work).
-            // To avoid dangling pointers OnThreadExit() will set m_pThread
-            // to NULL when the thread dies.
-        }
+        // after the call to wxThread::Run(), the m_pThread pointer is "unsafe":
+        // at any moment the thread may cease to exist (because it completes its work).
+        // To avoid dangling pointers OnThreadExit() will set m_pThread
+        // to NULL when the thread dies.
     }
 
     wxThread::ExitCode MyThread::Entry()
@@ -715,13 +815,13 @@ enum
         {
             // ... do a bit of work...
 
-            wxQueueEvent(m_pHandler, new wxCommandEvent(wxEVT_COMMAND_MYTHREAD_UPDATE));
+            wxQueueEvent(m_pHandler, new wxThreadEvent(wxEVT_COMMAND_MYTHREAD_UPDATE));
         }
 
         // signal the event handler that this thread is going to be destroyed
         // NOTE: here we assume that using the m_pHandler pointer is safe,
         //       (in this case this is assured by the MyFrame destructor)
-        wxQueueEvent(m_pHandler, new wxCommandEvent(wxEVT_COMMAND_MYTHREAD_COMPLETED));
+        wxQueueEvent(m_pHandler, new wxThreadEvent(wxEVT_COMMAND_MYTHREAD_COMPLETED));
 
         return (wxThread::ExitCode)0;     // success
     }
@@ -734,12 +834,12 @@ enum
         m_pHandler->m_pThread = NULL;
     }
 
-    void MyFrame::OnThreadCompletion(wxCommandEvent&)
+    void MyFrame::OnThreadCompletion(wxThreadEvent&)
     {
         wxMessageOutputDebug().Printf("MYFRAME: MyThread exited!\n");
     }
 
-    void MyFrame::OnThreadUpdate(wxCommandEvent&)
+    void MyFrame::OnThreadUpdate(wxThreadEvent&)
     {
         wxMessageOutputDebug().Printf("MYFRAME: MyThread update...\n");
     }
@@ -771,7 +871,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!");
@@ -847,8 +947,7 @@ enum
 
     All threads other than the "main application thread" (the one running
     wxApp::OnInit() or the one your main function runs in, for example) are
-    considered "secondary threads". These include all threads created by Create()
-    or the corresponding constructors.
+    considered "secondary threads".
 
     GUI calls, such as those to a wxWindow or wxBitmap are explicitly not safe
     at all in secondary threads and could end your application prematurely.
@@ -857,9 +956,9 @@ enum
     as MFC.
 
     A workaround for some wxWidgets ports is calling wxMutexGUIEnter()
-    before any GUI calls and then calling wxMutexGUILeave() afterwords. However,
-    the recommended way is to simply process the GUI calls in the main thread
-    through an event that is posted by wxQueueEvent().
+    before any GUI calls and then calling wxMutexGUILeave() afterwords.
+    However, the recommended way is to simply process the GUI calls in the main
+    thread through an event that is posted by wxQueueEvent().
     This does not imply that calls to these classes are thread-safe, however,
     as most wxWidgets classes are not thread-safe, including wxString.
 
@@ -869,10 +968,10 @@ enum
     A common problem users experience with wxThread is that in their main thread
     they will check the thread every now and then to see if it has ended through
     IsRunning(), only to find that their application has run into problems
-    because the thread is using the default behavior (i.e. it's @b detached) and
+    because the thread is using the default behaviour (i.e. it's @b detached) and
     has already deleted itself.
     Naturally, they instead attempt to use joinable threads in place of the previous
-    behavior. However, polling a wxThread for when it has ended is in general a
+    behaviour. However, polling a wxThread for when it has ended is in general a
     bad idea - in fact calling a routine on any running wxThread should be avoided
     if possible. Instead, find a way to notify yourself when the thread has ended.
 
@@ -900,7 +999,7 @@ public:
     /**
         This constructor creates a new detached (default) or joinable C++
         thread object. It does not create or start execution of the real thread -
-        for this you should use the Create() and Run() methods.
+        for this you should use the Run() method.
 
         The possible values for @a kind parameters are:
           - @b wxTHREAD_DETACHED - Creates a detached thread.
@@ -927,7 +1026,13 @@ public:
         to it (Ignored on platforms that don't support setting it explicitly,
         eg. Unix system without @c pthread_attr_setstacksize).
 
-        If you do not specify the stack size,the system's default value is used.
+        If you do not specify the stack size, the system's default value is used.
+
+        @note
+            It is not necessary to call this method since 2.9.5, Run() will create
+            the thread internally. You only need to call Create() if you need to do
+            something with the thread (e.g. pass its ID to an external library)
+            before it starts.
 
         @warning
             It is a good idea to explicitly specify a value as systems'
@@ -939,7 +1044,7 @@ public:
             performance issues on those systems with small default stack since those
             typically use fully committed memory for the stack.
             On the contrary, if you use a lot of threads (say several hundred),
-            virtual adress space can get tight unless you explicitly specify a
+            virtual address space can get tight unless you explicitly specify a
             smaller amount of thread stack space for each thread.
 
         @return One of:
@@ -953,6 +1058,15 @@ public:
         Calling Delete() gracefully terminates a @b detached thread, either when
         the thread calls TestDestroy() or when it finishes processing.
 
+        @param rc
+            The thread exit code, if rc is not NULL.
+
+        @param waitMode
+            As described in wxThreadWait documentation, wxTHREAD_WAIT_BLOCK
+            should be used as the wait mode even although currently
+            wxTHREAD_WAIT_YIELD is for compatibility reasons. This parameter is
+            new in wxWidgets 2.9.2.
+
         @note
             This function works on a joinable thread but in that case makes
             the TestDestroy() function of the thread return @true and then
@@ -961,25 +1075,33 @@ public:
 
         See @ref thread_deletion for a broader explanation of this routine.
     */
-    wxThreadError Delete(void** rc = NULL);
+    wxThreadError Delete(ExitCode *rc = NULL,
+                         wxThreadWait waitMode = wxTHREAD_WAIT_BLOCK);
 
     /**
         Returns the number of system CPUs or -1 if the value is unknown.
 
+        For multi-core systems the returned value is typically the total number
+        of @e cores, since the OS usually abstract a single N-core CPU
+        as N different cores.
+
         @see SetConcurrency()
     */
     static int GetCPUCount();
 
     /**
         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 unsigned long GetCurrentId();
+    static wxThreadIdType GetCurrentId();
 
     /**
         Gets the thread identifier: this is a platform dependent number that uniquely
         identifies the thread throughout the system during its existence
-        (i.e. the thread identifiers may be reused).
+        (i.e.\ the thread identifiers may be reused).
     */
     wxThreadIdType GetId() const;
 
@@ -991,17 +1113,23 @@ public:
     wxThreadKind GetKind() const;
 
     /**
-        Gets the priority of the thread, between zero and 100.
+        Returns the thread ID of the main thread.
+
+        @see IsMain()
+
+        @since 2.9.1
+     */
+    static wxThreadIdType GetMainId();
 
-        The following priorities are defined:
-          - @b WXTHREAD_MIN_PRIORITY: 0
-          - @b WXTHREAD_DEFAULT_PRIORITY: 50
-          - @b WXTHREAD_MAX_PRIORITY: 100
+    /**
+        Gets the priority of the thread, between 0 (lowest) and 100 (highest).
+
+        @see SetPriority()
     */
     unsigned int GetPriority() const;
 
     /**
-        Returns @true if the thread is alive (i.e. started and not terminating).
+        Returns @true if the thread is alive (i.e.\ started and not terminating).
 
         Note that this function can only safely be used with joinable threads, not
         detached ones as the latter delete themselves and so when the real thread is
@@ -1018,6 +1146,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();
 
@@ -1058,17 +1191,6 @@ public:
     */
     wxThreadError Kill();
 
-    /**
-        Called when the thread exits.
-
-        This function is called in the context of the thread associated with the
-        wxThread object, not in the context of the main thread.
-        This function will not be called if the thread was @ref Kill() killed.
-
-        This function should never be called directly.
-    */
-    virtual void OnExit();
-
     /**
         Suspends the thread.
 
@@ -1089,7 +1211,7 @@ public:
     wxThreadError Resume();
 
     /**
-        Starts the thread execution. Should be called after Create().
+        Starts the thread execution.
 
         Note that once you Run() a @b detached thread, @e any function call you do
         on the thread pointer (you must allocate it on the heap) is @e "unsafe";
@@ -1098,6 +1220,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();
 
@@ -1114,13 +1240,13 @@ public:
     static bool SetConcurrency(size_t level);
 
     /**
-        Sets the priority of the thread, between 0 and 100.
-        It can only be set after calling Create() but before calling Run().
+        Sets the priority of the thread, between 0 (lowest) and 100 (highest).
 
-        The following priorities are defined:
-          - @b WXTHREAD_MIN_PRIORITY: 0
-          - @b WXTHREAD_DEFAULT_PRIORITY: 50
-          - @b WXTHREAD_MAX_PRIORITY: 100
+        The following symbolic constants can be used in addition to raw
+        values in 0..100 range:
+          - @c wxPRIORITY_MIN: 0
+          - @c wxPRIORITY_DEFAULT: 50
+          - @c wxPRIORITY_MAX: 100
     */
     void SetPriority(unsigned int priority);
 
@@ -1162,9 +1288,15 @@ public:
 
         This function can only be called from another thread context.
 
+        @param flags
+            As described in wxThreadWait documentation, wxTHREAD_WAIT_BLOCK
+            should be used as the wait mode even although currently
+            wxTHREAD_WAIT_YIELD is for compatibility reasons. This parameter is
+            new in wxWidgets 2.9.2.
+
         See @ref thread_deletion for a broader explanation of this routine.
     */
-    ExitCode Wait();
+    ExitCode Wait(wxThreadWait flags = wxTHREAD_WAIT_BLOCK);
 
     /**
         Give the rest of the thread's time-slice to the system allowing the other
@@ -1227,6 +1359,19 @@ protected:
         OnExit() will be called just before exiting.
     */
     void Exit(ExitCode exitcode = 0);
+
+private:
+
+    /**
+        Called when the thread exits.
+
+        This function is called in the context of the thread associated with the
+        wxThread object, not in the context of the main thread.
+        This function will not be called if the thread was @ref Kill() killed.
+
+        This function should never be called directly.
+    */
+    virtual void OnExit();
 };
 
 
@@ -1493,6 +1638,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();
@@ -1525,7 +1673,7 @@ public:
 // Global functions/macros
 // ============================================================================
 
-/** @ingroup group_funcmacro_thread */
+/** @addtogroup group_funcmacro_thread */
 //@{
 
 /**
@@ -1608,6 +1756,8 @@ public:
 */
 bool wxIsMainThread();
 
+
+
 /**
     This function must be called when any thread other than the main GUI thread
     wants to get access to the GUI library. This function will block the
@@ -1626,14 +1776,14 @@ bool wxIsMainThread();
         wxMutexGuiEnter();
 
         // Call GUI here:
-        my_window-DrawSomething();
+        my_window->DrawSomething();
 
         wxMutexGuiLeave();
     }
     @endcode
 
     This function is only defined on platforms which support preemptive
-    threads.
+    threads and only works under some ports (wxMSW currently).
 
     @note Under GTK, no creation of top-level windows is allowed in any thread
           but the main one.