Don't use const bool.

[wxWidgets.git] / docs / latex / wx / tthreads.tex

diff --git a/docs/latex/wx/tthreads.tex b/docs/latex/wx/tthreads.tex
index eff2022d33a4736618ffcb6d7b89f33a8dd4e926..794dd727787937f5675763b8959e8749cd99ad29 100644 (file)
--- a/docs/latex/wx/tthreads.tex
+++ b/docs/latex/wx/tthreads.tex
@@ -1,7 +1,53 @@
 \section{Multithreading overview}\label{wxthreadoverview}
 
-Classes: \helpref{wxThread}{wxthread}, \helpref{wxMutex}{wxmutex},
-\helpref{wxCriticalSection}{wxcriticalsection},
+Classes: \helpref{wxThread}{wxthread}, \helpref{wxMutex}{wxmutex}, 
+\helpref{wxCriticalSection}{wxcriticalsection}, 
 \helpref{wxCondition}{wxcondition}
 
-TODO
+wxWidgets provides a complete set of classes encapsulating objects necessary in
+multithreaded (MT) programs: the \helpref{thread}{wxthread} class itself and different
+synchronization objects: \helpref{mutexes}{wxmutex} and 
+\helpref{critical sections}{wxcriticalsection} with 
+\helpref{conditions}{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 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 
+\helpref{idle handler}{wxidleevent} or even simply do everything at once
+but call \helpref{wxWindow::Update()}{wxwindowupdate} 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 {\it 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 
+\helpref{wxEvtHandler::AddPendingEvent}{wxevthandleraddpendingevent}
+or its short version \helpref{wxPostEvent}{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 \emph{not} enough to derive
+your class from \helpref{wxThread}{wxthread} and 
+\helpref{wxEvtHandler}{wxevthandler} to send messages to it: in fact, this does
+\emph{not} work at all.
+
+