Contents Up Previous Next

wxThread

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::wxThread

wxThread()

Default constructor: it doesn't create nor starts the thread.


wxThread::~wxThread

~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.


wxThread::Create

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.


wxThread::Delete

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.


wxThread::GetID

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).


wxThread::GetPriority

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


wxThread::IsAlive

bool IsAlive() const

Returns TRUE if the thread is alive (i.e. started and not terminating).


wxThread::IsMain

bool IsMain() const

Returns TRUE if the calling thread is the main application thread.


wxThread::IsPaused

bool IsPaused() const

Returns TRUE if the thread is paused.


wxThread::IsRunning

bool IsRunning() const

Returns TRUE if the thread is running.


wxThread::Kill

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.


wxThread::OnExit

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.


wxThread::Run

wxThreadError Run()

Runs the thread.


wxThread::SetPriority

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


wxThread::Sleep

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

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.


wxThread::Yield

Yield()

Give the rest of the thread time slice to the system allowing the other threads to run. See also Sleep().