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. Joinable
-threads may be created on the stack although more usually they will be created on the heap.
-Don't create global thread objects because they allocate memory in their constructor,
-which will cause problems for the memory checking system.
+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.
\wxheading{Derived from}
\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.
\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.
+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).
\wxheading{Return value}
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
+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.
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}
\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}
\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).
\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.
\membersection{wxThread::Kill}\label{wxthreadkill}
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}
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.
\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).
\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.
\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:
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}
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}
projects / wxWidgets.git / blobdiff