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 wxWindows: {\it detached} and {\it joinable}
+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
\latexignore{\rtfignore{\wxheading{Members}}}
+
\membersection{wxThread::wxThread}\label{wxthreadctor}
\func{}{wxThread}{\param{wxThreadKind }{kind = wxTHREAD\_DETACHED}}
\twocolitem{{\bf wxTHREAD\_JOINABLE}}{Create a joinable thread}
\end{twocollist}
+
\membersection{wxThread::\destruct{wxThread}}
\func{}{\destruct{wxThread}}{\void}
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}}
\twocolitem{{\bf wxTHREAD\_RUNNING}}{The thread is already running.}
\end{twocollist}
+
\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
+written, the thread will terminate after the next call to
\helpref{TestDestroy}{wxthreadtestdestroy} which should happen quite soon.
However, if the thread doesn't call \helpref{TestDestroy}{wxthreadtestdestroy}
This function can only be called from another thread context.
+
\membersection{wxThread::Entry}\label{wxthreadentry}
\func{virtual ExitCode}{Entry}{\void}
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 wxWindows itself and should never be called
+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}}
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}
\helpref{SetConcurrency}{wxthreadsetconcurrency}
+
\membersection{wxThread::GetCurrentId}\label{wxthreadgetcurrentid}
\func{static unsigned long}{GetCurrentId}{\void}
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).
+
\membersection{wxThread::GetPriority}\label{wxthreadgetpriority}
\constfunc{int}{GetPriority}{\void}
\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}
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}
This function should never be called directly.
+
\membersection{wxThread::Pause}\label{wxthreadpause}
\func{wxThreadError}{Pause}{\void}
This function can only be called from another thread context.
+
\membersection{wxThread::Run}\label{wxthreadrun}
\func{wxThreadError}{Run}{\void}
This function can only be called from another thread context.
+
\membersection{wxThread::SetPriority}\label{wxthreadsetpriority}
\func{void}{SetPriority}{\param{int}{ priority}}
\twocolitem{{\bf WXTHREAD\_MAX\_PRIORITY}}{100}
\end{twocollist}
+
\membersection{wxThread::Sleep}\label{wxthreadsleep}
\func{static void}{Sleep}{\param{unsigned long }{milliseconds}}
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}
This function can only be called from another thread context.
+
\membersection{wxThread::SetConcurrency}\label{wxthreadsetconcurrency}
\func{static bool}{SetConcurrency}{\param{size\_t }{level}}
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
+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}
+\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.
+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}
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}
projects / wxWidgets.git / blobdiff