X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/4d1f281b6df51eb8610688e68439c489b878deca..bcf576ccfe754a634034203aa133c02fb5d2f964:/docs/latex/wx/thread.tex diff --git a/docs/latex/wx/thread.tex b/docs/latex/wx/thread.tex index f3b2d4b2b3..1559443b69 100644 --- a/docs/latex/wx/thread.tex +++ b/docs/latex/wx/thread.tex @@ -1,34 +1,90 @@ \section{\class{wxThread}}\label{wxthread} -A wxThread manages a system thread, code which executes as a mini-process within the application. +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. + +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. \wxheading{Derived from} None. +\wxheading{Include files} + + + \wxheading{See also} -\helpref{wxMutex}{wxmutex}, \helpref{wxCondition}{wxcondition} +\helpref{wxMutex}{wxmutex}, \helpref{wxCondition}{wxcondition}, \helpref{wxCriticalSection}{wxcriticalsection} \latexignore{\rtfignore{\wxheading{Members}}} -\membersection{wxThread::wxThread}\label{wxthreadconstr} -\func{}{wxThread}{\void} +\membersection{wxThread::wxThread}\label{wxthreadctor} + +\func{}{wxThread}{\param{wxThreadKind }{kind = wxTHREAD\_DETACHED}} + +This constructor creates a new detached (default) or joinable C++ thread object. It +does not create or start execution of the real thread -- for this you should +use the \helpref{Create}{wxthreadcreate} and \helpref{Run}{wxthreadrun} methods. + +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} +\end{twocollist} -Default constructor. -\membersection{wxThread::\destruct{wxThread}} +\membersection{wxThread::\destruct{wxThread}}\label{wxthreaddtor} \func{}{\destruct{wxThread}}{\void} -Destroys the wxThread object. +The destructor frees the resources associated with the thread. Notice that you +should never delete a detached thread -- you may only call +\helpref{Delete}{wxthreaddelete} on it or wait until it terminates (and auto +destructs) itself. Because the detached threads delete themselves, they can +only be allocated on the heap. + +Joinable threads should be deleted explicitly. The \helpref{Delete}{wxthreaddelete} and \helpref{Kill}{wxthreadkill} functions +will not delete the C++ thread object. It is also safe to allocate them on +stack. + \membersection{wxThread::Create}\label{wxthreadcreate} -\func{wxThreadError}{Create}{\void} +\func{wxThreadError}{Create}{\param{unsigned int }{stackSize = 0}} -Creates a thread control. +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). \wxheading{Return value} @@ -36,39 +92,94 @@ One of: \twocolwidtha{7cm} \begin{twocollist}\itemsep=0pt -\twocolitem{{\bf THREAD\_NO\_ERROR}}{There was no error.} -\twocolitem{{\bf THREAD\_NO\_RESOURCE}}{There were insufficient resources to create a new thread.} -\twocolitem{{\bf THREAD\_RUNNING}}{The thread is already running.} +\twocolitem{{\bf wxTHREAD\_NO\_ERROR}}{There was no error.} +\twocolitem{{\bf wxTHREAD\_NO\_RESOURCE}}{There were insufficient resources to create a new thread.} +\twocolitem{{\bf wxTHREAD\_RUNNING}}{The thread is already running.} \end{twocollist} -\membersection{wxThread::DeferDestroy}\label{wxthreaddeferdestroy} -\func{void}{DeferDestroy}{\param{bool}{ defer}} +\membersection{wxThread::Delete}\label{wxthreaddelete} -If {\it defer} is TRUE, defers thread destruction. This function affects the -calling thread. +\func{void}{Delete}{\void} -\membersection{wxThread::Destroy}\label{wxthreaddestroy} +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}{Destroy}{\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! -Destroys the thread immediately unless the application has specified deferral via \helpref{wxThread::DeferDestroy}{deferdestroy}. +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. -\wxheading{Return value} +For detached threads Delete() will also delete the C++ thread object, but it +will not do this for joinable ones. -One of: +This function can only be called from another thread context. + + +\membersection{wxThread::Entry}\label{wxthreadentry} + +\func{virtual ExitCode}{Entry}{\void} + +This is the entry point of the thread. This function is pure virtual and must +be implemented by any derived class. The thread execution will start here. + +The returned value is the thread exit code which is only useful for +joinable threads and is the value returned by \helpref{Wait}{wxthreadwait}. + +This function is called by wxWidgets itself and should never be called +directly. + + +\membersection{wxThread::Exit}\label{wxthreadexit} + +\func{void}{Exit}{\param{ExitCode }{exitcode = 0}} + +This is a protected function of the wxThread class and thus can only be called +from a derived class. It also can only be called in the context of this +thread, i.e. a thread can only exit from itself, not from another thread. + +This function will terminate the OS thread (i.e. stop the associated path of +execution) and also delete the associated C++ object for detached threads. +\helpref{wxThread::OnExit}{wxthreadonexit} will be called just before exiting. -\twocolwidtha{7cm} -\begin{twocollist}\itemsep=0pt -\twocolitem{{\bf THREAD\_NO\_ERROR}}{There was no error.} -\twocolitem{{\bf THREAD\_NOT\_RUNNING}}{The thread is not running.} -\end{twocollist} -\membersection{wxThread::GetID}\label{wxthreadgetid} +\membersection{wxThread::GetCPUCount}\label{wxthreadgetcpucount} -\constfunc{unsigned long}{GetID}{\void} +\func{static int}{GetCPUCount}{\void} + +Returns the number of system CPUs or -1 if the value is unknown. + +\wxheading{See also} + +\helpref{SetConcurrency}{wxthreadsetconcurrency} + + +\membersection{wxThread::GetCurrentId}\label{wxthreadgetcurrentid} + +\func{static unsigned long}{GetCurrentId}{\void} + +Returns the platform specific thread ID of the current thread as a +long. This can be used to uniquely identify threads, even if they are +not wxThreads. + + +\membersection{wxThread::GetId}\label{wxthreadgetid} + +\constfunc{unsigned long}{GetId}{\void} + +Gets the thread identifier: this is a platform dependent number that uniquely identifies the +thread throughout the system during its existence (i.e. the thread identifiers may be reused). -Gets the thread identifier. \membersection{wxThread::GetPriority}\label{wxthreadgetpriority} @@ -76,51 +187,204 @@ Gets the thread identifier. Gets the priority of the thread, between zero and 100. -The following priorities are already defined: +The following priorities are defined: \twocolwidtha{7cm} \begin{twocollist}\itemsep=0pt -\twocolitem{{\bf WXTHREAD_MIN_PRIORITY}}{0} -\twocolitem{{\bf WXTHREAD_DEFAULT_PRIORITY}}{50} -\twocolitem{{\bf WXTHREAD_MAX_PRIORITY}}{100} +\twocolitem{{\bf WXTHREAD\_MIN\_PRIORITY}}{0} +\twocolitem{{\bf WXTHREAD\_DEFAULT\_PRIORITY}}{50} +\twocolitem{{\bf WXTHREAD\_MAX\_PRIORITY}}{100} \end{twocollist} + \membersection{wxThread::IsAlive}\label{wxthreadisalive} \constfunc{bool}{IsAlive}{\void} -Returns TRUE if the thread is alive. +Returns \true if the thread is alive (i.e. started and not terminating). + +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 +no longer alive, it is not possible to call this function because +the wxThread object no longer exists. + +\membersection{wxThread::IsDetached}\label{wxthreadisdetached} + +\constfunc{bool}{IsDetached}{\void} + +Returns \true if the thread is of the detached kind, \false if it is a joinable +one. + \membersection{wxThread::IsMain}\label{wxthreadismain} -\constfunc{bool}{IsMain}{\void} +\func{static bool}{IsMain}{\void} + +Returns \true if the calling thread is the main application thread. + + +\membersection{wxThread::IsPaused}\label{wxthreadispaused} + +\constfunc{bool}{IsPaused}{\void} + +Returns \true if the thread is paused. + + +\membersection{wxThread::IsRunning}\label{wxthreadisrunning} -Returns TRUE if the thread is the main application thread. +\constfunc{bool}{IsRunning}{\void} -\membersection{wxThread::Join}\label{wxthreadjoin} +Returns \true if the thread is running. -\func{void*}{Join}{\void} +This method may only be safely used for joinable threads, see the remark in +\helpref{IsAlive}{wxthreadisalive}. + + +\membersection{wxThread::Kill}\label{wxthreadkill} + +\func{wxThreadError}{Kill}{\void} + +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. + +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 +still have to delete the wxThread object yourself to avoid memory leaks. +In neither case \helpref{OnExit}{wxthreadonexit} of the dying thread will be +called, so no thread-specific cleanup will be performed. + +This function can only be called from another thread context, i.e. a thread +cannot kill itself. + +It is also an error to call this function for a thread which is not running or +paused (in the latter case, the thread will be resumed first) -- if you do it, +a {\tt wxTHREAD\_NOT\_RUNNING} error will be returned. -Waits for the termination of the thread. Returns a platform-specific exit code. TODO \membersection{wxThread::OnExit}\label{wxthreadonexit} \func{void}{OnExit}{\void} -Called when the thread exits. The default implementation calls \helpref{wxThread::Join}{wxthreadjoin}. +Called when the thread exits. This function is called in the context of the +thread associated with the wxThread object, not in the context of the main +thread. This function will not be called if the thread was +\helpref{killed}{wxthreadkill}. + +This function should never be called directly. + + +\membersection{wxThread::Pause}\label{wxthreadpause} + +\func{wxThreadError}{Pause}{\void} + +Suspends the thread. Under some implementations (Win32), the thread is +suspended immediately, under others it will only be suspended when it calls +\helpref{TestDestroy}{wxthreadtestdestroy} for the next time (hence, if the +thread doesn't call it at all, it won't be suspended). + +This function can only be called from another thread context. + + +\membersection{wxThread::Run}\label{wxthreadrun} + +\func{wxThreadError}{Run}{\void} + +Starts the thread execution. Should be called after +\helpref{Create}{wxthreadcreate}. + +This function can only be called from another thread context. + \membersection{wxThread::SetPriority}\label{wxthreadsetpriority} \func{void}{SetPriority}{\param{int}{ priority}} -Sets the priority of the thread, between zero and 100. This must be set before the thread is created. +Sets the priority of the thread, between $0$ and $100$. It can only be set +after calling \helpref{Create()}{wxthreadcreate} but before calling +\helpref{Run()}{wxthreadrun}. The following priorities are already defined: \twocolwidtha{7cm} \begin{twocollist}\itemsep=0pt -\twocolitem{{\bf WXTHREAD_MIN_PRIORITY}}{0} -\twocolitem{{\bf WXTHREAD_DEFAULT_PRIORITY}}{50} -\twocolitem{{\bf WXTHREAD_MAX_PRIORITY}}{100} +\twocolitem{{\bf WXTHREAD\_MIN\_PRIORITY}}{0} +\twocolitem{{\bf WXTHREAD\_DEFAULT\_PRIORITY}}{50} +\twocolitem{{\bf WXTHREAD\_MAX\_PRIORITY}}{100} \end{twocollist} + +\membersection{wxThread::Sleep}\label{wxthreadsleep} + +\func{static void}{Sleep}{\param{unsigned long }{milliseconds}} + +Pauses the thread execution for the given amount of time. + +This function should be used instead of \helpref{wxSleep}{wxsleep} by all worker +threads (i.e. all except the main one). + + +\membersection{wxThread::Resume}\label{wxthreadresume} + +\func{wxThreadError}{Resume}{\void} + +Resumes a thread suspended by the call to \helpref{Pause}{wxthreadpause}. + +This function can only be called from another thread context. + + +\membersection{wxThread::SetConcurrency}\label{wxthreadsetconcurrency} + +\func{static bool}{SetConcurrency}{\param{size\_t }{level}} + +Sets the thread concurrency level for this process. This is, roughly, the +number of threads that the system tries to schedule to run in parallel. +The value of $0$ for {\it level} may be used to set the default one. + +Returns \true on success or false otherwise (for example, if this function is +not implemented for this platform -- currently everything except Solaris). + + +\membersection{wxThread::TestDestroy}\label{wxthreadtestdestroy} + +\func{virtual bool}{TestDestroy}{\void} + +This function should be called periodically by the thread to ensure that calls +to \helpref{Pause}{wxthreadpause} and \helpref{Delete}{wxthreaddelete} will +work. If it returns \true, the thread should exit as soon as possible. + +Notice that under some platforms (POSIX), implementation of +\helpref{Pause}{wxthreadpause} also relies on this function being called, so +not calling it would prevent both stopping and suspending thread from working. + + +\membersection{wxThread::This}\label{wxthreadthis} + +\func{static wxThread *}{This}{\void} + +Return the thread object for the calling thread. NULL is returned if the calling thread +is the main (GUI) thread, but \helpref{IsMain}{wxthreadismain} should be used to test +whether the thread is really the main one because NULL may also be returned for the thread +not created with wxThread class. Generally speaking, the return value for such a thread +is undefined. + + +\membersection{wxThread::Yield}\label{wxthreadyield} + +\func{void}{Yield}{\void} + +Give the rest of the thread time slice to the system allowing the other threads to run. +See also \helpref{Sleep()}{wxthreadsleep}. + + +\membersection{wxThread::Wait}\label{wxthreadwait} + +\constfunc{ExitCode}{Wait}{\void} + +Waits until the thread terminates and returns its exit code 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. +