/////////////////////////////////////////////////////////////////////////////
-// Name: thread
+// Name: thread.h
// Purpose: topic overview
// Author: wxWidgets team
// RCS-ID: $Id$
-// Licence: wxWindows license
+// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
-/*!
-
- @page overview_thread Multithreading overview
-
- Classes: #wxThread, #wxMutex,
- #wxCriticalSection,
- #wxCondition
-
- wxWidgets provides a complete set of classes encapsulating objects necessary in
- multithreaded (MT) programs: the #thread class itself and different
- synchronization objects: #mutexes and
- @ref criticalsection_overview with
- #conditions. The thread API in 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 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 a very poor choice
- (example: launching a separate thread when doing a long computation to show a
- progress dialog). Other implementation choices are available: for the progress
- dialog example it is far better to do the calculations in the
- @ref idleevent_overview or even simply do everything at once
- but call wxWindow::Update() periodically to update
- the screen.
-
- If you do decide to use threads in your application, it is strongly recommended
- that no more than one thread calls GUI functions. The thread sample shows that
- it @e is possible for many different threads to call GUI functions at once
- (all the threads created in the sample access GUI), but it is a very poor design
- choice for anything except an example. The design which uses one GUI thread and
- several worker threads which communicate with the main one using events is much
- more robust and will undoubtedly save you countless problems (example: under
- Win32 a thread can only access GDI objects such as pens, brushes, c created by
- itself and not by the other threads).
-
- For communication between secondary threads and the main thread, you may use
- wxEvtHandler::AddPendingEvent
- or its short version #wxPostEvent. These functions
- have a thread-safe implementation so that they can be used as they are for
- sending events from one thread to another. However there is no built in method
- to send messages to the worker threads and you will need to use the available
- synchronization classes to implement the solution which suits your needs
- yourself. In particular, please note that it is not enough to derive
- your class from #wxThread and
- #wxEvtHandler to send messages to it: in fact, this does
- not work at all.
-
- */
+/*
+ NOTE: we explicitly don't name wxMutexGUIEnter() and wxMutexGUILeave()
+ as they're not safe. See also ticket #10366.
+*/
+/**
+@page overview_thread Multithreading Overview
+
+@tableofcontents
+
+wxWidgets provides a complete set of classes encapsulating objects necessary in
+multi-threaded (MT) applications: the wxThread class itself and different
+synchronization objects: mutexes (see wxMutex) and critical sections (see
+wxCriticalSection) with conditions (see wxCondition). The thread API in
+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 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 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 @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.
+
+If instead you choose to use threads in your application, please read the
+following section of this overview.
+
+@see wxThread, wxThreadHelper, wxMutex, wxCriticalSection, wxCondition,
+ wxSemaphore
+
+
+
+@section overview_thread_notes Important Notes for Multi-threaded Applications
+
+When writing a multi-threaded 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 as pens,
+brushes, device contexts created by itself and not by the other threads).
+
+For communication between secondary threads and the main thread, you may use
+wxEvtHandler::QueueEvent or its short version ::wxQueueEvent. These functions
+have a thread-safe implementation so that they can be used as they are for
+sending events from one thread to another. However there is no built in method
+to send messages to the worker threads and you will need to use the available
+synchronization classes to implement the solution which suits your needs
+yourself. In particular, please note that it is not enough to derive your class
+from wxThread and wxEvtHandler to send messages to it: in fact, this does not
+work at all. You're instead encouraged to use wxThreadHelper as it greatly
+simplifies the communication and the sharing of resources.
+
+You should also look at the wxThread docs for important notes about secondary
+threads and their deletion.
+
+Last, remember that if wxEventLoopBase::YieldFor() is used directly or
+indirectly (e.g. through wxProgressDialog) in your code, then you may have both
+re-entrancy problems and also problems caused by the processing of events out
+of order. To resolve the last problem wxThreadEvent can be used: thanks to its
+implementation of the wxThreadEvent::GetEventCategory function wxThreadEvent
+classes in fact do not get processed by wxEventLoopBase::YieldFor() unless you
+specify the @c wxEVT_CATEGORY_THREAD flag.
+
+See also the @sample{thread} for a sample showing some simple interactions
+between the main and secondary threads.
+
+*/
projects / wxWidgets.git / blobdiff