X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/6fe7378863be6febaaab0e8aa855b51781351ac5..3ac7b44cc0765b8444324d71b58cf648009d41c2:/docs/latex/wx/thread.tex

diff --git a/docs/latex/wx/thread.tex b/docs/latex/wx/thread.tex
index ada3f901b9..558d3cc709 100644
--- a/docs/latex/wx/thread.tex
+++ b/docs/latex/wx/thread.tex
@@ -11,7 +11,7 @@ such as \helpref{mutexes}{wxmutex} and/or \helpref{critical sections}{wxcritical
 There are two types of threads in wxWindows: {\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
+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
@@ -42,12 +42,13 @@ None.
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 
+
 \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
+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:
@@ -58,12 +59,13 @@ 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}
 
 The destructor frees the resources associated with the thread. Notice that you
-should never delete a detached thread - you may only call 
+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.
@@ -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,38 +95,35 @@ One of:
 \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} 
+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!
 
-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. This cleanup will be done in the destructor for joinable
-threads.
-
-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 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}
@@ -137,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}}
@@ -146,9 +147,10 @@ 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. 
+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}
@@ -159,6 +161,16 @@ 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}
+
+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}
@@ -166,6 +178,7 @@ Returns the number of system CPUs or -1 if the value is unknown.
 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}
@@ -181,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}
 
@@ -230,46 +258,50 @@ 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, 
+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}
 
 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 
+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 $0$ and $100$. It can only be set
-after calling \helpref{Create()}{wxthreadcreate} but before calling 
+after calling \helpref{Create()}{wxthreadcreate} but before calling
 \helpref{Run()}{wxthreadrun}.
 
 The following priorities are already defined:
@@ -281,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}}
@@ -290,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}
@@ -298,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}}
@@ -306,8 +341,9 @@ 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).
+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}
 
@@ -315,7 +351,8 @@ not implemented for this platform - currently everything except Solaris).
 
 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.
+
 
 \membersection{wxThread::This}\label{wxthreadthis}
 
@@ -327,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}
@@ -334,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}