docs/doxygen/overviews/thread.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        thread.h
   3 // Purpose:     topic overview
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /*
  10     NOTE: we explicitely don't name wxMutexGUIEnter() and wxMutexGUILeave()
  11           as they're not safe. See also ticket #10366.
  12 */
  13
  14 /**
  15
  16 @page overview_thread Multithreading Overview
  17
  18 Classes: wxThread, wxThreadHelper, wxMutex, wxCriticalSection, wxCondition, wxSemaphore
  19
  20
  21 @section overview_thread_intro When to use multiple threads
  22
  23 wxWidgets provides a complete set of classes encapsulating objects necessary in
  24 multithreaded (MT) programs: the wxThread class itself and different
  25 synchronization objects: mutexes (see wxMutex) and critical sections (see
  26 wxCriticalSection)  with conditions (see wxCondition). The thread API in
  27 wxWidgets resembles to POSIX1.c threads API (a.k.a. pthreads), although several
  28 functions have different names and some features inspired by Win32 thread API
  29 are there as well.
  30
  31 These classes hopefully make writing MT programs easier and they also
  32 provide some extra error checking (compared to the native - be it Win32 or
  33 Posix - thread API), however it is still a non-trivial undertaking especially
  34 for large projects.
  35 Before starting an MT application (or starting to add MT
  36 features to an existing one) it is worth asking oneself if there is no easier
  37 and safer way to implement the same functionality.
  38 Of course, in some situations threads really make sense (classical example is a
  39 server application which launches a new thread for each new client), but in others
  40 it might be an overkill.
  41 On the other hand, the recent evolution of the computer hardware shows
  42 an important trend towards multi-core systems, which are better exploited using
  43 multiple threads (e.g. you may want to split a long task among as many threads
  44 as many CPU (cores) the system reports; see wxThread::GetCPUCount).
  45
  46 To implement non-blocking operations @e without using multiple threads you have
  47 two possible implementation choices:
  48 - use wxIdleEvent (e.g. to perform a long calculation while updating a progress dialog)
  49 - do everything at once but call wxWindow::Update() or wxApp::YieldFor(wxEVT_CATEGORY_UI)
  50   periodically to update the screen.
  51 If instead you choose to use threads in your application, please read also
  52 the following sections of this overview.
  53
  54 @section overview_thread_notes Important notes for multithreaded applications
  55
  56 When writing a multi-threaded application, it is strongly recommended
  57 that <b>no secondary threads call GUI functions</b>.
  58 The design which uses one GUI thread and several worker threads which communicate
  59 with the main one using @b events is much more robust and will undoubtedly save you
  60 countless problems (example: under Win32 a thread can only access GDI objects such
  61 as pens, brushes, device contexts created by itself and not by the other threads).
  62
  63 For communication between secondary threads and the main thread, you may use
  64 wxEvtHandler::QueueEvent or its short version ::wxQueueEvent. These functions
  65 have a thread-safe implementation so that they can be used as they are for
  66 sending events from one thread to another. However there is no built in method
  67 to send messages to the worker threads and you will need to use the available
  68 synchronization classes to implement the solution which suits your needs
  69 yourself. In particular, please note that it is not enough to derive
  70 your class from wxThread and wxEvtHandler to send messages to it: in fact, this
  71 does not work at all.
  72 You're instead encouraged to use wxThreadHelper as it greatly simplifies the
  73 communication and the sharing of resources.
  74
  75 You should also look at the wxThread docs for important notes about secondary
  76 threads and their deletion.
  77
  78 Last, remember that if wxEventLoopBase::YieldFor() is used directly or indirectly
  79 (e.g. through wxProgressDialog) in your code, then you may have both re-entrancy
  80 problems and also problems caused by the processing of events out of order.
  81 To resolve the last problem wxThreadEvent can be used: thanks to its implementation
  82 of the wxThreadEvent::GetEventCategory function wxThreadEvent classes in fact
  83 do not get processed by wxEventLoopBase::YieldFor() unless you specify the
  84 @c wxEVT_CATEGORY_THREAD flag.
  85
  86 See also the @sample{thread} for a sample showing some simple interactions
  87 between the main and secondary threads.
  88
  89 */
  90