9fc3ad34c5
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@4769 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
289 lines
10 KiB
TeX
289 lines
10 KiB
TeX
\section{\class{wxThread}}\label{wxthread}
|
|
|
|
A thread is basically a path of execution through a program. Threads are also
|
|
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 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 wxWindows: {\it detached} and {\it joinable}
|
|
ones, just as in POSIX thread API (but unlike Win32 threads where all threads
|
|
are joinable). The difference between the two is that only joinbale threads
|
|
can return a return code - it is returned by Wait() function. The detached
|
|
threads (default) can not 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 of the
|
|
system resources used by it will never be freed and you also must delete the
|
|
corresponding wxThread object yourself, while 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. The
|
|
joinable threads may be created on stack (don't create global thread objects
|
|
because they allocate memory in their constructor which is a badthing to do),
|
|
although usually they will be created on the heap as well.
|
|
|
|
\wxheading{Derived from}
|
|
|
|
None.
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/thread.h>
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{wxMutex}{wxmutex}, \helpref{wxCondition}{wxcondition}, \helpref{wxCriticalSection}{wxcriticalsection}
|
|
|
|
\latexignore{\rtfignore{\wxheading{Members}}}
|
|
|
|
\membersection{wxThread::wxThread}\label{wxthreadctor}
|
|
|
|
\func{}{wxThread}{\void}
|
|
|
|
Constructor creates a new detached (default) or joinable C++ thread object. It
|
|
does not create (or starts execution of) the real thread - for this you should
|
|
use \helpref{Create}{wxthreadcreate} and \helpref{Run}{wxthreadrun} methods.
|
|
|
|
\membersection{wxThread::\destruct{wxThread}}
|
|
|
|
\func{}{\destruct{wxThread}}{\void}
|
|
|
|
Destructor frees the ressources 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.
|
|
|
|
The joinable threads, however, may and should be deleted explicitly and
|
|
\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}
|
|
|
|
Creates a new thread. The thread object is created in the suspended state, you
|
|
should call \helpref{Run}{wxthreadrun} to start running it.
|
|
|
|
\wxheading{Return value}
|
|
|
|
One of:
|
|
|
|
\twocolwidtha{7cm}
|
|
\begin{twocollist}\itemsep=0pt
|
|
\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::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 quiet soon.
|
|
|
|
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, the message processing
|
|
is not stopped during this function execution, so the message handlers may be
|
|
called from inside it!
|
|
|
|
Delete() may be called for thread in any state: running, paused or even not yet
|
|
created. Moreover, it must be called if \helpref{Create}{wxthreadcreate} or
|
|
\helpref{Run}{wxthreadrun} failed for a detached thread to free the memory
|
|
occupied by the thread object (it will be done in the destructor for joinable
|
|
threads).
|
|
|
|
Delete() may be called for 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 to free
|
|
the memory occupied by the thread object.
|
|
|
|
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.
|
|
|
|
\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 the
|
|
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::GetId}\label{wxthreadgetid}
|
|
|
|
\constfunc{unsigned long}{GetId}{\void}
|
|
|
|
Gets the thread identifier: this is a platform dependent number which 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}
|
|
|
|
Gets the priority of the thread, between zero and 100.
|
|
|
|
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}
|
|
\end{twocollist}
|
|
|
|
\membersection{wxThread::IsAlive}\label{wxthreadisalive}
|
|
|
|
\constfunc{bool}{IsAlive}{\void}
|
|
|
|
Returns TRUE if the thread is alive (i.e. started and not terminating).
|
|
|
|
\membersection{wxThread::IsDetached}\label{wxthreadisdetached}
|
|
|
|
\constfunc{bool}{IsDetached}{\void}
|
|
|
|
Returns TRUE if the thread is of 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.
|
|
|
|
\membersection{wxThread::IsPaused}\label{wxthreadispaused}
|
|
|
|
\constfunc{bool}{IsPaused}{\void}
|
|
|
|
Returns TRUE if the thread is paused.
|
|
|
|
\membersection{wxThread::IsRunning}\label{wxthreadisrunning}
|
|
|
|
\constfunc{bool}{IsRunning}{\void}
|
|
|
|
Returns TRUE if the thread is running.
|
|
|
|
\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.
|
|
|
|
This function can only be called from another thread context.
|
|
|
|
\membersection{wxThread::OnExit}\label{wxthreadonexit}
|
|
|
|
\func{void}{OnExit}{\void}
|
|
|
|
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 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.
|
|
|
|
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}
|
|
\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
|
|
(i.e. all except the main one) threads.
|
|
|
|
\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::TestDestroy}\label{wxthreadtestdestroy}
|
|
|
|
\func{bool}{TestDestroy}{\void}
|
|
|
|
This function should be periodically called 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}
|
|
|
|
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 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.
|