remove mention of wxMutexGuiEnter/leave from the multithreading topic overview; document that wxMutexGuiEnter only works for wxMSW as the code seems to confirm this (see #10366)

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@58683 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

docs/doxygen/overviews/thread.h

@@ -6,6 +6,11 @@
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 
+/*
+    NOTE: we explicitely don't name wxMutexGUIEnter() and wxMutexGUILeave()
+          as they're not safe. See also ticket #10366.
+*/
+
 /**
 
 @page overview_thread Multithreading
@@ -20,27 +25,29 @@ wxWidgets resembles to POSIX1.c threads API (a.k.a. pthreads), although several
 functions have different names and some features inspired by Win32 thread API
 are there as well.
 
-These classes will hopefully make writing MT programs easier and they also
+These classes hopefully make writing MT programs easier and they also
-provide some extra error checking (compared to the native (be it Win32 or
+provide some extra error checking (compared to the native - be it Win32 or
-Posix) thread API), however it is still a non-trivial undertaking especially
+Posix - thread API), however it is still a non-trivial undertaking especially
-for large projects. Before starting an MT application (or starting to add MT
+for large projects.
+Before starting an MT application (or starting to add MT
 features to an existing one) it is worth asking oneself if there is no easier
-and safer way to implement the same functionality. Of course, in some
+and safer way to implement the same functionality.
-situations threads really make sense (classical example is a server application
+Of course, in some situations threads really make sense (classical example is a
-which launches a new thread for each new client), but in others it might be an
+server application which launches a new thread for each new client), but in others
-overkill. On the other hand, the recent evolution of the computer hardware shows
+it might be an overkill.
+On the other hand, the recent evolution of the computer hardware shows
 an important trend towards multi-core systems, which are better exploited using
 multiple threads (e.g. you may want to split a long task among as many threads
 as many CPU (cores) the system reports; see wxThread::GetCPUCount).
 
-To implement non-blocking operations without using multiple threads you have
+To implement non-blocking operations @e without using multiple threads you have
-two other possible implementation choices:
+two possible implementation choices:
-- using wxIdleEvent (e.g. to perform a long calculation while updating a progress dialog)
+- use wxIdleEvent (e.g. to perform a long calculation while updating a progress dialog)
-- simply do everything at once but call wxWindow::Update() periodically to update the screen.
+- do everything at once but call wxWindow::Update() or wxApp::YieldFor(wxEVT_CATEGORY_UI)
+  periodically to update the screen.
 
-Even if there are the ::wxMutexGuiEnter and ::wxMutexGuiLeave functions which allows
+If instead you choose to use threads in your application, it is strongly recommended
-to use GUI functions from multiple threads, if you do decide to use threads in your
+that <b>no secondary threads call GUI functions</b>.
-application, it is strongly recommended that <b>no more than one calls GUI functions</b>.
 The design which uses one GUI thread and several worker threads which communicate
 with the main one using @b events is much more robust and will undoubtedly save you
 countless problems (example: under Win32 a thread can only access GDI objects such

interface/wx/thread.h

@@ -863,9 +863,9 @@ enum
     as MFC.
 
     A workaround for some wxWidgets ports is calling wxMutexGUIEnter()
-    before any GUI calls and then calling wxMutexGUILeave() afterwords. However,
+    before any GUI calls and then calling wxMutexGUILeave() afterwords.
-    the recommended way is to simply process the GUI calls in the main thread
+    However, the recommended way is to simply process the GUI calls in the main
-    through an event that is posted by wxQueueEvent().
+    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.
 
@@ -1620,6 +1620,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
@@ -1645,7 +1647,7 @@ bool wxIsMainThread();
     @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.