From f06afb9ceb2c233083dda4d7dcbe49b2dadf0a7b Mon Sep 17 00:00:00 2001 From: Vadim Zeitlin Date: Sat, 15 Nov 2003 15:05:28 +0000 Subject: [PATCH] IsAlive/Running() may only be used with joinable threads git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@24566 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- docs/latex/wx/thread.tex | 46 +++++++++++++++++++++++++++++++++++----- 1 file changed, 41 insertions(+), 5 deletions(-) diff --git a/docs/latex/wx/thread.tex b/docs/latex/wx/thread.tex index 400824fd6e..558d3cc709 100644 --- a/docs/latex/wx/thread.tex +++ b/docs/latex/wx/thread.tex @@ -42,6 +42,7 @@ None. \latexignore{\rtfignore{\wxheading{Members}}} + \membersection{wxThread::wxThread}\label{wxthreadctor} \func{}{wxThread}{\param{wxThreadKind }{kind = wxTHREAD\_DETACHED}} @@ -58,6 +59,7 @@ The possible values for {\it kind} parameters are: \twocolitem{{\bf wxTHREAD\_JOINABLE}}{Create a joinable thread} \end{twocollist} + \membersection{wxThread::\destruct{wxThread}} \func{}{\destruct{wxThread}}{\void} @@ -72,6 +74,7 @@ Joinable threads should be deleted explicitly. The \helpref{Delete}{wxthreaddele will not delete the C++ thread object. It is also safe to allocate them on stack. + \membersection{wxThread::Create}\label{wxthreadcreate} \func{wxThreadError}{Create}{\param{unsigned int }{stackSize = 0}} @@ -92,6 +95,7 @@ One of: \twocolitem{{\bf wxTHREAD\_RUNNING}}{The thread is already running.} \end{twocollist} + \membersection{wxThread::Delete}\label{wxthreaddelete} \func{void}{Delete}{\void} @@ -119,6 +123,7 @@ will not do this for joinable ones. This function can only be called from another thread context. + \membersection{wxThread::Entry}\label{wxthreadentry} \func{virtual ExitCode}{Entry}{\void} @@ -132,6 +137,7 @@ joinable threads and is the value returned by \helpref{Wait}{wxthreadwait}. This function is called by wxWindows itself and should never be called directly. + \membersection{wxThread::Exit}\label{wxthreadexit} \func{void}{Exit}{\param{ExitCode }{exitcode = 0}} @@ -144,6 +150,7 @@ 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. + \membersection{wxThread::GetCPUCount}\label{wxthreadgetcpucount} \func{static int}{GetCPUCount}{\void} @@ -154,6 +161,7 @@ Returns the number of system CPUs or -1 if the value is unknown. \helpref{SetConcurrency}{wxthreadsetconcurrency} + \membersection{wxThread::GetCurrentId}\label{wxthreadgetcurrentid} \func{static unsigned long}{GetCurrentId}{\void} @@ -162,6 +170,7 @@ 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} @@ -169,6 +178,7 @@ not wxThreads. 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). + \membersection{wxThread::GetPriority}\label{wxthreadgetpriority} \constfunc{int}{GetPriority}{\void} @@ -184,35 +194,50 @@ The following priorities are defined: \twocolitem{{\bf WXTHREAD\_MAX\_PRIORITY}}{100} \end{twocollist} + \membersection{wxThread::IsAlive}\label{wxthreadisalive} \constfunc{bool}{IsAlive}{\void} -Returns true if the thread is alive (i.e. started and not terminating). +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 +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. + \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. +Returns \true if the thread is of the detached kind, \false if it is a joinable +one. + \membersection{wxThread::IsMain}\label{wxthreadismain} \func{static bool}{IsMain}{\void} -Returns true if the calling thread is the main application thread. +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. +Returns \true if the thread is paused. + \membersection{wxThread::IsRunning}\label{wxthreadisrunning} \constfunc{bool}{IsRunning}{\void} -Returns true if the thread is running. +Returns \true if the thread is running. + +This method may only be safely used for joinable threads, see the remark in +\helpref{IsAlive}{wxthreadisalive}. + \membersection{wxThread::Kill}\label{wxthreadkill} @@ -236,6 +261,7 @@ 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. + \membersection{wxThread::OnExit}\label{wxthreadonexit} \func{void}{OnExit}{\void} @@ -247,6 +273,7 @@ thread. This function will not be called if the thread was This function should never be called directly. + \membersection{wxThread::Pause}\label{wxthreadpause} \func{wxThreadError}{Pause}{\void} @@ -258,6 +285,7 @@ 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} @@ -267,6 +295,7 @@ Starts the thread execution. Should be called after This function can only be called from another thread context. + \membersection{wxThread::SetPriority}\label{wxthreadsetpriority} \func{void}{SetPriority}{\param{int}{ priority}} @@ -284,6 +313,7 @@ The following priorities are already defined: \twocolitem{{\bf WXTHREAD\_MAX\_PRIORITY}}{100} \end{twocollist} + \membersection{wxThread::Sleep}\label{wxthreadsleep} \func{static void}{Sleep}{\param{unsigned long }{milliseconds}} @@ -293,6 +323,7 @@ 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} @@ -301,6 +332,7 @@ 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}} @@ -312,6 +344,7 @@ 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{bool}{TestDestroy}{\void} @@ -320,6 +353,7 @@ 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. + \membersection{wxThread::This}\label{wxthreadthis} \func{static wxThread *}{This}{\void} @@ -330,6 +364,7 @@ whether the thread is really the main one because NULL may also be returned for 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} @@ -337,6 +372,7 @@ is undefined. 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}