From c9c537e6b06e7ca0160de52b7a91901aef0381e0 Mon Sep 17 00:00:00 2001 From: Vadim Zeitlin Date: Sat, 6 May 2006 22:40:19 +0000 Subject: [PATCH] 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 | 168 +++++++++++++++++++++++++++------------ 1 file changed, 118 insertions(+), 50 deletions(-) diff --git a/docs/latex/wx/thread.tex b/docs/latex/wx/thread.tex index 537f574b27..12f9020b74 100644 --- a/docs/latex/wx/thread.tex +++ b/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. -- 2.45.2