docs/doxygen/overviews/thread.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        thread
   3 // Purpose:     topic overview
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /*!
  10
  11  @page overview_thread Multithreading overview
  12
  13  Classes: #wxThread, #wxMutex,
  14  #wxCriticalSection,
  15  #wxCondition
  16
  17  wxWidgets provides a complete set of classes encapsulating objects necessary in
  18  multithreaded (MT) programs: the #thread class itself and different
  19  synchronization objects: #mutexes and
  20  @ref criticalsection_overview with
  21  #conditions. The thread API in wxWidgets resembles to
  22  POSIX1.c threads API (a.k.a. pthreads), although several functions have
  23  different names and some features inspired by Win32 thread API are there as
  24  well.
  25
  26  These classes will hopefully make writing MT programs easier and they also
  27  provide some extra error checking (compared to the native (be it Win32 or Posix)
  28  thread API), however it is still a non-trivial undertaking especially for large
  29  projects. Before starting an MT application (or starting to add MT features to
  30  an existing one) it is worth asking oneself if there is no easier and safer way
  31  to implement the same functionality. Of course, in some situations threads
  32  really make sense (classical example is a server application which launches a
  33  new thread for each new client), but in others it might be a very poor choice
  34  (example: launching a separate thread when doing a long computation to show a
  35  progress dialog). Other implementation choices are available: for the progress
  36  dialog example it is far better to do the calculations in the
  37  @ref idleevent_overview or even simply do everything at once
  38  but call wxWindow::Update() periodically to update
  39  the screen.
  40
  41  If you do decide to use threads in your application, it is strongly recommended
  42  that no more than one thread calls GUI functions. The thread sample shows that
  43  it @e is possible for many different threads to call GUI functions at once
  44  (all the threads created in the sample access GUI), but it is a very poor design
  45  choice for anything except an example. The design which uses one GUI thread and
  46  several worker threads which communicate with the main one using events is much
  47  more robust and will undoubtedly save you countless problems (example: under
  48  Win32 a thread can only access GDI objects such as pens, brushes, c created by
  49  itself and not by the other threads).
  50
  51  For communication between secondary threads and the main thread, you may use
  52  wxEvtHandler::AddPendingEvent
  53  or its short version #wxPostEvent. These functions
  54  have a thread-safe implementation so that they can be used as they are for
  55  sending events from one thread to another. However there is no built in method
  56  to send messages to the worker threads and you will need to use the available
  57  synchronization classes to implement the solution which suits your needs
  58  yourself. In particular, please note that it is not enough to derive
  59  your class from #wxThread and
  60  #wxEvtHandler to send messages to it: in fact, this does
  61  not work at all.
  62
  63  */
  64
  65