\section{\class{wxThread}}\label{wxthread}
-A thread is basically a path of execution through a program. Threads are also
+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 much
+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 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.
+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 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
+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. 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.
+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}
\latexignore{\rtfignore{\wxheading{Members}}}
+
\membersection{wxThread::wxThread}\label{wxthreadctor}
-\func{}{wxThread}{\void}
+\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}
-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}}
+\membersection{wxThread::\destruct{wxThread}}\label{wxthreaddtor}
\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
+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.
-The joinable threads, however, may and should be deleted explicitly and
-\helpref{Delete}{wxthreaddelete} and \helpref{Kill}{wxthreadkill} functions
+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 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 system without
+\texttt{pthread\_attr\_setstacksize}). If you do not specify the stack size,
+the system's default value is used.
+
+{\bf Warning:} It is a good idea to explicitly specify a value as systems'
+default values vary from just a couple of KB on some systems (BSD and
+OS/2 systems) to one or several MB (Windows, Solaris, Linux). So, if you
+have a thread that requires more than just a few KB of memory, you will
+have mysterious problems on some platforms but not on the common ones. On the
+other hand, just indicating a large stack size by default will give you
+performance issues on those systems with small default stack since those
+typically use fully committed memory for the stack. On the contrary, if
+use a lot of threads (say several hundred), virtual adress space can get tight
+unless you explicitly specify a smaller amount of thread stack space for each
+thread.
-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}
\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.
+\helpref{TestDestroy}{wxthreadtestdestroy} which should happen quite soon.
-However, if the thread doesn't call \helpref{TestDestroy}{wxthreadtestdestroy}
+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
+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!
-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. 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.
+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.
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
+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}}
+
+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.
+
+
\membersection{wxThread::GetCPUCount}\label{wxthreadgetcpucount}
\func{static int}{GetCPUCount}{\void}
\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 which uniquely identifies the
+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 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 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}
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.
-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.
+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
+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
+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:
\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.
+threads (i.e. all except the main one).
+
\membersection{wxThread::Resume}\label{wxthreadresume}
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
-not implemented for this platform (currently everything except Solaris)).
+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 periodically called by the thread to ensure that calls
+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}
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
+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.
+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.
+
projects / wxWidgets.git / blobdiff