+\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.
projects / wxWidgets.git / blobdiff