X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/6d06e061dc11140151be2914c30c759ee15e3fe7..4d76ea948a703e19008366bf79411dc9bd58b0c1:/docs/latex/wx/thread.tex diff --git a/docs/latex/wx/thread.tex b/docs/latex/wx/thread.tex index 8bac6f84bd..ad1cb401fd 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} @@ -84,7 +160,22 @@ stack. Creates a new thread. The thread object is created in the suspended state, and you should call \helpref{Run}{wxthreadrun} to start running it. You may optionally specify the stack size to be allocated to it (Ignored on platforms that don't -support setting it explicitly, eg. Unix). +support setting it explicitly, eg. Unix system without +\texttt{pthread\_attr\_setstacksize}). If you do not specify the stack size, +the system's default value is used. + +{\bf Warning:} It is a good idea to explicitly specify a value as systems' +default values vary from just a couple of KB on some systems (BSD and +OS/2 systems) to one or several MB (Windows, Solaris, Linux). So, if you +have a thread that requires more than just a few KB of memory, you will +have mysterious problems on some platforms but not on the common ones. On the +other hand, just indicating a large stack size by default will give you +performance issues on those systems with small default stack since those +typically use fully committed memory for the stack. On the contrary, if +use a lot of threads (say several hundred), virtual adress space can get tight +unless you explicitly specify a smaller amount of thread stack space for each +thread. + \wxheading{Return value} @@ -100,31 +191,18 @@ One of: \membersection{wxThread::Delete}\label{wxthreaddelete} -\func{void}{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. +\func{wxThreadError}{Delete}{\void} -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! +Calling \helpref{Delete}{wxthreaddelete} gracefully terminates a +detached thread, either when the thread calls \helpref{TestDestroy}{wxthreadtestdestroy} or finished processing. -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. +(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). -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} @@ -203,11 +281,10 @@ The following priorities are defined: Returns \true if the thread is alive (i.e. started and not terminating). -Note that this function can only be saely used with joinable threads, not +Note that this function can only safely be used with joinable threads, not detached ones as the latter delete themselves and so when the real thread is -not alive any longer it is not possible to call this function neither because -the wxThread object doesn't exist any more as well. - +no longer alive, it is not possible to call this function because +the wxThread object no longer exists. \membersection{wxThread::IsDetached}\label{wxthreadisdetached} @@ -248,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 @@ -383,9 +461,15 @@ 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. +Waits for a joinable thread to terminate and returns the value the thread +returned from \helpref{wxThread::Entry}{wxthreadentry} or {\tt (ExitCode)-1} on +error. Notice that, unlike \helpref{Delete}{wxthreaddelete} doesn't cancel the +thread in any way so the caller waits for as long as it takes to the thread to +exit. 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. +