remove mention of wxMutexGuiEnter/leave from the multithreading topic overview; docum...

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

diff --git a/docs/doxygen/overviews/thread.h b/docs/doxygen/overviews/thread.h
index 08327e2993bcd61e2b7aba03dfb1cdc78074b405..a16b570533290ffe57e2bfce8d761c3f3ed67164 100644 (file)
--- a/docs/doxygen/overviews/thread.h
+++ b/docs/doxygen/overviews/thread.h
@@ -6,6 +6,11 @@
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 
 // 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
 /**
 
 @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.
 
 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
-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
-for large projects. Before starting an MT application (or starting to add MT
+These classes hopefully make writing MT programs easier and they also
+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
+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
 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
-situations threads really make sense (classical example is a server application
-which launches a new thread for each new client), but in others it might be an
-overkill. On the other hand, the recent evolution of the computer hardware shows
+and safer way to implement the same functionality.
+Of course, in some situations threads really make sense (classical example is a
+server application which launches a new thread for each new client), but in others
+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).
 
 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
-two other possible implementation choices:
-- using 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.
+To implement non-blocking operations @e without using multiple threads you have
+two possible implementation choices:
+- use wxIdleEvent (e.g. to perform a long calculation while updating a progress dialog)
+- 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
-to use GUI functions from multiple threads, if you do decide to use threads in your
-application, it is strongly recommended that <b>no more than one calls GUI functions</b>.
+If instead you choose to use threads in your application, it is strongly recommended
+that <b>no secondary threads call 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
 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

diff --git a/interface/wx/thread.h b/interface/wx/thread.h
index 0985caf1b6f591ebbe045a8a9a5a32419ba3ffd6..d0641dfe1745139621c7d8f71411350f12b03d0a 100644 (file)
--- a/interface/wx/thread.h
+++ b/interface/wx/thread.h
@@ -863,9 +863,9 @@ enum
     as MFC.
 
     A workaround for some wxWidgets ports is calling wxMutexGUIEnter()
     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.
 
     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();
 
 */
 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
 /**
     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
     @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.
 
     @note Under GTK, no creation of top-level windows is allowed in any thread
           but the main one.