better Wait/Delete() docs (patch 1434085)

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@39093 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

docs/latex/wx/thread.tex

@@ -3,32 +3,13 @@
 A thread is basically a path of execution through a program. Threads are
 sometimes called {\it light-weight processes}, but the fundamental difference
 between threads and processes is that memory spaces of different processes are
-separated while all threads share the same address space. While it makes it
-much easier to share common data between several threads, it also makes it much
-easier to shoot oneself in the foot, so careful use of synchronization objects
-such as \helpref{mutexes}{wxmutex} and/or \helpref{critical sections}{wxcriticalsection} is recommended.
+separated while all threads share the same address space. 
 
-There are two types of threads in wxWidgets: {\it detached} and {\it joinable}
-ones, just as in the POSIX thread API (but unlike Win32 threads where all threads
-are joinable). The difference between the two is that only joinable threads
-can return a return code -- this is returned by the Wait() function. Detached
-threads (the default type) cannot be waited for.
-
-You shouldn't hurry to create all the threads joinable, however, because this
-has a disadvantage as well: you {\bf must} Wait() for a joinable thread or the
-system resources used by it will never be freed, and you also must delete the
-corresponding wxThread object yourself. In contrast, detached threads are of the
-"fire-and-forget" kind: you only have to start a detached thread and it will
-terminate and destroy itself.
-
-This means, of course, that all detached threads {\bf must} be created on the
-heap because the thread will call {\tt delete this;} upon termination. Joinable
-threads may be created on the stack although more usually they will be created
-on the heap as well. Don't create global thread objects because they allocate
-memory in their constructor, which will cause problems for the memory checking
-system. Finally, another consequence of the handling of the above is that you
-should never delete a detached thread yourself, as this will be done by the
-thread itself when it terminates.
+While it makes it much easier to share common data between several threads, it also 
+makes it much easier to shoot oneself in the foot, so careful use of synchronization 
+objects such as \helpref{mutexes}{wxmutex} or \helpref{critical sections}{wxcriticalsection} is recommended. In addition, don't create global thread 
+objects because they allocate memory in their constructor, which will cause 
+problems for the memory checking system.
 
 \wxheading{Derived from}
 
@@ -44,6 +25,101 @@ None.
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 
+\membersection{Types of wxThreads}\label{typeswxthread}
+
+There are two types of threads in wxWidgets: {\it detached} and {\it joinable},
+modeled after the the POSIX thread API. This is different from the Win32 API
+where all threads are joinable. 
+
+By default wxThreads in wxWidgets use the detached behavior. Detached threads
+delete themselves once they have completed, either by themselves when they complete 
+processing or through a call to \helpref{wxThread::Delete}{wxthreaddelete}, and thus 
+must be created on the heap (through the new operator, for example). Conversely, 
+joinable threads do not delete themselves when they are done processing and as such
+are safe to create on the stack. Joinable threads also provide the ability
+for one to get value it returned from \helpref{wxThread::Entry}{wxthreadentry}
+through \helpref{wxThread::Wait}{wxthreadwait}.
+
+You shouldn't hurry to create all the threads joinable, however, because this
+has a disadvantage as well: you {\bf must} Wait() for a joinable thread or the
+system resources used by it will never be freed, and you also must delete the
+corresponding wxThread object yourself if you did not create it on the stack. In 
+contrast, detached threads are of the "fire-and-forget" kind: you only have to start 
+a detached thread and it will terminate and destroy itself.
+
+\membersection{wxThread deletion}\label{deletionwxthread}
+
+Regardless of whether it has terminated or not, you should call 
+\helpref{wxThread::Wait}{wxthreadwait} on a joinable thread to release its
+memory, as outlined in \helpref{Types of wxThreads}{typeswxthread}. If you created
+a joinable thread on the heap, remember to delete it manually with the delete 
+operator or similar means as only detached threads handle this type of memory 
+management.
+
+Since detached threads delete themselves when they are finished processing,
+you should take care when calling a routine on one. If you are certain the 
+thread is still running and would like to end it, you may call 
+\helpref{wxThread::Delete}{wxthreaddelete} to gracefully end it (which implies
+that the thread will be deleted after that call to Delete()). It should be
+implied that you should never attempt to delete a detached thread with the 
+delete operator or similar means. 
+
+As mentioned, \helpref{wxThread::Wait}{wxthreadwait} or 
+\helpref{wxThread::Delete}{wxthreaddelete} attempts to gracefully terminate
+a joinable and detached thread, respectively. It does this by waiting until
+the thread in question calls \helpref{wxThread::TestDestroy}{wxthreadtestdestroy}
+or ends processing (returns from \helpref{wxThread::Entry}{wxthreadentry}).
+
+Obviously, if the thread does call TestDestroy() and does not end the calling
+thread will come to halt. This is why it is important to call TestDestroy() in
+the Entry() routine of your threads as often as possible.
+
+As a last resort you can end the thread immediately through 
+\helpref{wxThread::Kill}{wxthreadkill}. It is strongly recommended that you
+do not do this, however, as it does not free the resources associated with
+the object (although the wxThread object of detached threads will still be
+deleted) and could leave the C runtime library in an undefined state.
+
+\membersection{wxWidgets calls in secondary threads}\label{secondarywxthread}
+
+All threads other then the "main application thread" (the one
+\helpref{wxApp::OnInit}{wxapponinit} or your main function runs in, for 
+example) are considered "secondary threads". These include all threads created 
+by \helpref{wxThread::Create}{wxthreadcreate} or the corresponding constructors.
+
+GUI calls, such as those to a \helpref{wxWindow}{wxwindow} or 
+\helpref{wxBitmap}{wxbitmap} are explicitly not safe at all in secondary threads 
+and could end your application prematurely. This is due to several reasons,
+including the underlying native API and the fact that wxThread does not run a 
+GUI event loop similar to other APIs as MFC. 
+
+A workaround that works on some wxWidgets ports is calling \helpref{wxMutexGUIEnter}{wxmutexguienter} 
+before any GUI calls and then calling \helpref{wxMutexGUILeave}{wxmutexguileave} afterwords. However,
+the recommended way is to simply process the GUI calls in the main thread 
+through an event that is posted by either \helpref{wxPostEvent}{wxpostevent} or
+\helpref{wxEvtHandler::AddPendingEvent}{wxevthandleraddpendingevent}. This does 
+not imply that calls to these classes are thread-safe, however, as most 
+wxWidgets classes are not thread-safe, including wxString.
+
+\membersection{Don't poll a wxThread}\label{dontpollwxthread}
+
+A common problem users experience with wxThread is that in their main thread
+they will check the thread every now and then to see if it has ended through
+\helpref{wxThread::IsRunning}{wxthreadisrunning}, only to find that their 
+application has run into problems because the thread is using the default
+behavior and has already deleted itself. Naturally, they instead attempt to
+use joinable threads in place of the previous behavior.
+
+However, polling a wxThread for when it has ended is in general a bad idea -
+in fact calling a routine on any running wxThread should be avoided if 
+possible. Instead, find a way to notify yourself when the thread has ended.
+Usually you only need to notify the main thread, in which case you can post
+an event to it via \helpref{wxPostEvent}{wxpostevent} or
+\helpref{wxEvtHandler::AddPendingEvent}{wxevthandleraddpendingevent}. In 
+the case of secondary threads you can call a routine of another class
+when the thread is about to complete processing and/or set the value
+of a variable, possibly using \helpref{mutexes}{wxmutex} and/or other 
+synchronization means if necessary.
 
 \membersection{wxThread::wxThread}\label{wxthreadctor}
 
@@ -57,8 +133,8 @@ The possible values for {\it kind} parameters are:
 
 \twocolwidtha{7cm}
 \begin{twocollist}\itemsep=0pt
-\twocolitem{{\bf wxTHREAD\_DETACHED}}{Create a detached thread.}
-\twocolitem{{\bf wxTHREAD\_JOINABLE}}{Create a joinable thread}
+\twocolitem{{\bf wxTHREAD\_DETACHED}}{Creates a detached thread.}
+\twocolitem{{\bf wxTHREAD\_JOINABLE}}{Creates a joinable thread.}
 \end{twocollist}
 
 
@@ -115,31 +191,18 @@ One of:
 
 \membersection{wxThread::Delete}\label{wxthreaddelete}
 
-\func{void}{Delete}{\void}
+\func{wxThreadError}{Delete}{\void}
 
-Calling \helpref{Delete}{wxthreaddelete} is a graceful way to terminate the
-thread. It asks the thread to terminate and, if the thread code is well
-written, the thread will terminate after the next call to 
-\helpref{TestDestroy}{wxthreadtestdestroy} which should happen quite soon.
+Calling \helpref{Delete}{wxthreaddelete} gracefully terminates a 
+detached thread, either when the thread calls \helpref{TestDestroy}{wxthreadtestdestroy} or finished processing.
 
-However, if the thread doesn't call \helpref{TestDestroy}{wxthreadtestdestroy}
-often enough (or at all), the function will not return immediately, but wait
-until the thread terminates. As it may take a long time, and the message processing
-is not stopped during this function execution, message handlers may be
-called from inside it!
+(Note that while this could work on a joinable thread you simply should not
+call this routine on one as afterwards you may not be able to call 
+\helpref{wxThread::Wait}{wxthreadwait} to free the memory of that thread).
 
-Delete() may be called for a thread in any state: running, paused or even not
-yet created. Moreover, it must be called if \helpref{Create}{wxthreadcreate} or
-\helpref{Run}{wxthreadrun} fail in order to free the memory occupied by the
-thread object. However, you should not call Delete() on a detached thread which
-already terminated -- doing so will probably result in a crash because the
-thread object doesn't exist any more.
-
-For detached threads Delete() will also delete the C++ thread object, but it
-will not do this for joinable ones.
-
-This function can only be called from another thread context.
+See \helpref{wxThread deletion}{deletionwxthread} for a broader explanation of this routine.
 
+%%FIXME: What does this return and why?
 
 \membersection{wxThread::Entry}\label{wxthreadentry}
 
@@ -262,7 +325,8 @@ This method may only be safely used for joinable threads, see the remark in
 Immediately terminates the target thread. {\bf This function is dangerous and should
 be used with extreme care (and not used at all whenever possible)!} The resources
 allocated to the thread will not be freed and the state of the C runtime library
-may become inconsistent. Use \helpref{Delete()}{wxthreaddelete} instead.
+may become inconsistent. Use \helpref{Delete()}{wxthreaddelete} for detached 
+threads or \helpref{Wait()}{wxthreadwait} for joinable threads instead.
 
 For detached threads Kill() will also delete the associated C++ object.
 However this will not happen for joinable threads and this means that you will
@@ -397,9 +461,13 @@ See also \helpref{Sleep()}{wxthreadsleep}.
 
 \constfunc{ExitCode}{Wait}{\void}
 
-Waits until the thread terminates and returns its exit code or {\tt (ExitCode)-1} on error.
+Gracefully terminates a joinable thread, either when the thread calls 
+\helpref{TestDestroy}{wxthreadtestdestroy} or finished processing, and 
+returns the value the thread returned from 
+\helpref{wxThread::Entry}{wxthreadentry} or {\tt (ExitCode)-1} on error. 
 
 You can only Wait() for joinable (not detached) threads.
 
 This function can only be called from another thread context.
 
+See \helpref{wxThread deletion}{deletionwxthread} for a broader explanation of this routine.