A thread is basically a path of execution through a program. Threads are also sometimes called 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 mutexes and/or critical sections is recommended.
Derived from
None.
Include files
<wx/thread.h>
See also
wxMutex, wxCondition, wxCriticalSection
Members
wxThread::wxThread
wxThread::~wxThread
wxThread::Create
wxThread::Delete
wxThread::GetID
wxThread::GetPriority
wxThread::IsAlive
wxThread::IsMain
wxThread::IsPaused
wxThread::IsRunning
wxThread::Kill
wxThread::OnExit
wxThread::Run
wxThread::SetPriority
wxThread::Sleep
wxThread::This
wxThread::Yield
wxThread()
Default constructor: it doesn't create nor starts the thread.
~wxThread()
wxThread destructor is private, so you can not call it directly - i.e., deleting wxThread objects is forbidden. Instead, you should use Delete or Kill methods. This also means that thread objects should eb always allocated on the heap (i.e. with new) because the functions mentioned above will try to reclaim the storage from the heap.
wxThreadError Create()
Creates a new thread. The thread object is created in the suspended state, you should call Run to start running it.
Return value
One of:
wxTHREAD_NO_ERROR | There was no error. |
wxTHREAD_NO_RESOURCE | There were insufficient resources to create a new thread. |
wxTHREAD_RUNNING | The thread is already running. |
Delete()
This function should be called to terminate this thread. Unlike Kill, it gives the target thread the time to terminate gracefully. Because of this, however, this function may not return immediately and if the thread is "hung" won't return at all. Also, 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 Create or Run fail to free the memory occupied by the thread object.
unsigned long GetID() const
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).
int GetPriority() const
Gets the priority of the thread, between zero and 100.
The following priorities are already defined:
WXTHREAD_MIN_PRIORITY | 0 |
WXTHREAD_DEFAULT_PRIORITY | 50 |
WXTHREAD_MAX_PRIORITY | 100 |
bool IsAlive() const
Returns TRUE if the thread is alive (i.e. started and not terminating).
bool IsMain() const
Returns TRUE if the calling thread is the main application thread.
bool IsPaused() const
Returns TRUE if the thread is paused.
bool IsRunning() const
Returns TRUE if the thread is running.
wxThreadError Kill()
Immediately terminates the target thread. 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 Delete() instead.
void OnExit()
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.
wxThreadError Run()
Runs the thread.
void SetPriority(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:
WXTHREAD_MIN_PRIORITY | 0 |
WXTHREAD_DEFAULT_PRIORITY | 50 |
WXTHREAD_MAX_PRIORITY | 100 |
Sleep(unsigned long milliseconds)
Pauses the thread execution for the given amount of time.
This function should be used instead of wxSleep by all worker (i.e. all except the main one) threads.
wxThread * This()
Return the thread object for the calling thread. NULL is returned if the calling thread is the main (GUI) thread, but IsMain 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.
Yield()
Give the rest of the thread time slice to the system allowing the other threads to run. See also Sleep().