From ae93dddfafa3de73101cde64f49622ead9fc34dd Mon Sep 17 00:00:00 2001 From: Francesco Montorsi Date: Thu, 5 Feb 2009 18:24:27 +0000 Subject: [PATCH] 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 | 37 ++++++++++++++++++++------------- interface/wx/thread.h | 10 +++++---- 2 files changed, 28 insertions(+), 19 deletions(-) diff --git a/docs/doxygen/overviews/thread.h b/docs/doxygen/overviews/thread.h index 08327e2993..a16b570533 100644 --- a/docs/doxygen/overviews/thread.h +++ b/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 -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 -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). -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 no more than one calls GUI functions. +If instead you choose to use threads in your application, it is strongly recommended +that no secondary threads call GUI functions. 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 0985caf1b6..d0641dfe17 100644 --- 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() - 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. @@ -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.