#include <wx/thread.h>

Detailed Description

A thread is basically a path of execution through a program.

Threads are 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 it much easier to shoot oneself in the foot, so careful use of synchronization objects such as mutexes (see wxMutex) or critical sections (see wxCriticalSection) is recommended. In addition, don't create global thread objects because they allocate memory in their constructor, which will cause problems for the memory checking system.

Types of wxThreads

There are two types of threads in wxWidgets: detached and joinable, modeled after the POSIX thread API. This is different from the Win32 API where all threads are joinable.

By default wxThreads in wxWidgets use the detached behaviour. Detached threads delete themselves once they have completed, either by themselves when they complete processing or through a call to Delete(), and thus must be created on the heap (through the new operator, for example).

Typically you'll want to store the instances of the detached wxThreads you allocate, so that you can call functions on them. Because of their nature however you'll need to always use a critical section when accessing them:

// declare a new type of event, to be used by our MyThread class:
wxDECLARE_EVENT(wxEVT_COMMAND_MYTHREAD_COMPLETED, wxThreadEvent);
wxDECLARE_EVENT(wxEVT_COMMAND_MYTHREAD_UPDATE, wxThreadEvent);
class MyFrame;
class MyThread : public wxThread
{
public:
    MyThread(MyFrame *handler)
        : wxThread(wxTHREAD_DETACHED)
        { m_pHandler = handler }
    ~MyThread();
protected:
    virtual ExitCode Entry();
    MyFrame *m_pHandler;
};
class MyFrame : public wxFrame
{
public:
    ...
    ~MyFrame()
    {
        // it's better to do any thread cleanup in the OnClose()
        // event handler, rather than in the destructor.
        // This is because the event loop for a top-level window is not
        // active anymore when its destructor is called and if the thread
        // sends events when ending, they won't be processed unless
        // you ended the thread from OnClose.
        // See @ref overview_windowdeletion for more info.
    }
    ...
    void DoStartThread();
    void DoPauseThread();
    // a resume routine would be nearly identic to DoPauseThread()
    void DoResumeThread() { ... }
    void OnThreadUpdate(wxThreadEvent&);
    void OnThreadCompletion(wxThreadEvent&);
    void OnClose(wxCloseEvent&);
protected:
    MyThread *m_pThread;
    wxCriticalSection m_pThreadCS;    // protects the m_pThread pointer
    wxDECLARE_EVENT_TABLE();
};
wxBEGIN_EVENT_TABLE(MyFrame, wxFrame)
    EVT_CLOSE(MyFrame::OnClose)
    EVT_MENU(Minimal_Start,  MyFrame::DoStartThread)
    EVT_COMMAND(wxID_ANY, wxEVT_COMMAND_MYTHREAD_UPDATE, MyFrame::OnThreadUpdate)
    EVT_COMMAND(wxID_ANY, wxEVT_COMMAND_MYTHREAD_COMPLETED, MyFrame::OnThreadCompletion)
wxEND_EVENT_TABLE()
wxDEFINE_EVENT(wxEVT_COMMAND_MYTHREAD_COMPLETED, wxThreadEvent)
wxDEFINE_EVENT(wxEVT_COMMAND_MYTHREAD_UPDATE, wxThreadEvent)
void MyFrame::DoStartThread()
{
    m_pThread = new MyThread(this);
    if ( m_pThread->Run() != wxTHREAD_NO_ERROR )
    {
        wxLogError("Can't create the thread!");
        delete m_pThread;
        m_pThread = NULL;
    }
    // after the call to wxThread::Run(), the m_pThread pointer is "unsafe":
    // at any moment the thread may cease to exist (because it completes its work).
    // To avoid dangling pointers OnThreadExit() will set m_pThread
    // to NULL when the thread dies.
}
wxThread::ExitCode MyThread::Entry()
{
    while (!TestDestroy())
    {
        // ... do a bit of work...
        wxQueueEvent(m_pHandler, new wxThreadEvent(wxEVT_COMMAND_MYTHREAD_UPDATE));
    }
    // signal the event handler that this thread is going to be destroyed
    // NOTE: here we assume that using the m_pHandler pointer is safe,
    //       (in this case this is assured by the MyFrame destructor)
    wxQueueEvent(m_pHandler, new wxThreadEvent(wxEVT_COMMAND_MYTHREAD_COMPLETED));
    return (wxThread::ExitCode)0;     // success
}
MyThread::~MyThread()
{
    wxCriticalSectionLocker enter(m_pHandler->m_pThreadCS);
    // the thread is being destroyed; make sure not to leave dangling pointers around
    m_pHandler->m_pThread = NULL;
}
void MyFrame::OnThreadCompletion(wxThreadEvent&)
{
    wxMessageOutputDebug().Printf("MYFRAME: MyThread exited!\n");
}
void MyFrame::OnThreadUpdate(wxThreadEvent&)
{
    wxMessageOutputDebug().Printf("MYFRAME: MyThread update...\n");
}
void MyFrame::DoPauseThread()
{
    // anytime we access the m_pThread pointer we must ensure that it won't
    // be modified in the meanwhile; since only a single thread may be
    // inside a given critical section at a given time, the following code
    // is safe:
    wxCriticalSectionLocker enter(m_pThreadCS);
    if (m_pThread)         // does the thread still exist?
    {
        // without a critical section, once reached this point it may happen
        // that the OS scheduler gives control to the MyThread::Entry() function,
        // which in turn may return (because it completes its work) making
        // invalid the m_pThread pointer
        if (m_pThread->Pause() != wxTHREAD_NO_ERROR )
            wxLogError("Can't pause the thread!");
    }
}
void MyFrame::OnClose(wxCloseEvent&)
{
    {
        wxCriticalSectionLocker enter(m_pThreadCS);
        if (m_pThread)         // does the thread still exist?
        {
            wxMessageOutputDebug().Printf("MYFRAME: deleting thread");
            if (m_pThread->Delete() != wxTHREAD_NO_ERROR )
                wxLogError("Can't delete the thread!");
        }
    }       // exit from the critical section to give the thread
            // the possibility to enter its destructor
            // (which is guarded with m_pThreadCS critical section!)
    while (1)
    {
        { // was the ~MyThread() function executed?
            wxCriticalSectionLocker enter(m_pThreadCS);
            if (!m_pThread) break;
        }
        // wait for thread completion
        wxThread::This()->Sleep(1);
    }
    Destroy();
}

For a more detailed and comprehensive example, see Thread Sample. For a simpler way to share data and synchronization objects between the main and the secondary thread see wxThreadHelper.

Conversely, joinable threads do not delete themselves when they are done processing and as such are safe to create on the stack. Joinable threads also provide the ability for one to get value it returned from Entry() through Wait(). You shouldn't hurry to create all the threads joinable, however, because this has a disadvantage as well: you 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 if you did not create it on the stack. 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.

wxThread Deletion

Regardless of whether it has terminated or not, you should call Wait() on a joinable thread to release its memory, as outlined in Types of wxThreads. If you created a joinable thread on the heap, remember to delete it manually with the delete operator or similar means as only detached threads handle this type of memory management.

Since detached threads delete themselves when they are finished processing, you should take care when calling a routine on one. If you are certain the thread is still running and would like to end it, you may call Delete() to gracefully end it (which implies that the thread will be deleted after that call to Delete()). It should be implied that you should never attempt to delete a detached thread with the delete operator or similar means.

As mentioned, Wait() or Delete() functions attempt to gracefully terminate a joinable and a detached thread, respectively. They do this by waiting until the thread in question calls TestDestroy() or ends processing (i.e. returns from wxThread::Entry).

Obviously, if the thread does call TestDestroy() and does not end, the thread which called Wait() or Delete() will come to halt. This is why it's important to call TestDestroy() in the Entry() routine of your threads as often as possible and immediately exit when it returns true.

As a last resort you can end the thread immediately through Kill(). It is strongly recommended that you do not do this, however, as it does not free the resources associated with the object (although the wxThread object of detached threads will still be deleted) and could leave the C runtime library in an undefined state.

wxWidgets Calls in Secondary Threads

All threads other than the "main application thread" (the one running wxApp::OnInit() or the one your main function runs in, for example) are considered "secondary threads".

GUI calls, such as those to a wxWindow or wxBitmap are explicitly not safe at all in secondary threads and could end your application prematurely. This is due to several reasons, including the underlying native API and the fact that wxThread does not run a GUI event loop similar to other APIs as MFC.

A workaround for some wxWidgets ports is calling wxMutexGUIEnter() before any GUI calls and then calling wxMutexGUILeave() afterwords. However, the recommended way is to simply process the GUI calls in the main thread through an event that is posted by wxQueueEvent(). This does not imply that calls to these classes are thread-safe, however, as most wxWidgets classes are not thread-safe, including wxString.

Don't Poll a wxThread

A common problem users experience with wxThread is that in their main thread they will check the thread every now and then to see if it has ended through IsRunning(), only to find that their application has run into problems because the thread is using the default behaviour (i.e. it's detached) and has already deleted itself. Naturally, they instead attempt to use joinable threads in place of the previous behaviour. However, polling a wxThread for when it has ended is in general a bad idea - in fact calling a routine on any running wxThread should be avoided if possible. Instead, find a way to notify yourself when the thread has ended.

Usually you only need to notify the main thread, in which case you can post an event to it via wxQueueEvent(). In the case of secondary threads you can call a routine of another class when the thread is about to complete processing and/or set the value of a variable, possibly using mutexes (see wxMutex) and/or other synchronization means if necessary.

Library: wxBase

Category: Threading

See also: wxThreadHelper, wxMutex, wxCondition, wxCriticalSection, Multithreading Overview

Public Types
typedef void *	ExitCode
	The return type for the thread functions. More...

Public Member Functions
	wxThread (wxThreadKind kind=wxTHREAD_DETACHED)
	This constructor creates a new detached (default) or joinable C++ thread object. More...

virtual	~wxThread ()
	The destructor frees the resources associated with the thread. More...

wxThreadError	Create (unsigned int stackSize=0)
	Creates a new thread. More...

wxThreadError	Delete (ExitCode *rc=NULL, wxThreadWait waitMode=wxTHREAD_WAIT_DEFAULT)
	Calling Delete() gracefully terminates a detached thread, either when the thread calls TestDestroy() or when it finishes processing. More...

wxThreadIdType	GetId () const
	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). More...

wxThreadKind	GetKind () const
	Returns the thread kind as it was given in the ctor. More...

unsigned int	GetPriority () const
	Gets the priority of the thread, between 0 (lowest) and 100 (highest). More...

bool	IsAlive () const
	Returns true if the thread is alive (i.e. started and not terminating). More...

bool	IsDetached () const
	Returns true if the thread is of the detached kind, false if it is a joinable one. More...

bool	IsPaused () const
	Returns true if the thread is paused. More...

bool	IsRunning () const
	Returns true if the thread is running. More...

wxThreadError	Kill ()
	Immediately terminates the target thread. More...

wxThreadError	Pause ()
	Suspends the thread. More...

wxThreadError	Resume ()
	Resumes a thread suspended by the call to Pause(). More...

wxThreadError	Run ()
	Starts the thread execution. More...

void	SetPriority (unsigned int priority)
	Sets the priority of the thread, between 0 (lowest) and 100 (highest). More...

virtual bool	TestDestroy ()
	This function should be called periodically by the thread to ensure that calls to Pause() and Delete() will work. More...

ExitCode	Wait (wxThreadWait flags=wxTHREAD_WAIT_BLOCK)
	Waits for a joinable thread to terminate and returns the value the thread returned from Entry() or `"(ExitCode)-1"` on error. More...

Static Public Member Functions
static int	GetCPUCount ()
	Returns the number of system CPUs or -1 if the value is unknown. More...

static wxThreadIdType	GetCurrentId ()
	Returns the platform specific thread ID of the current thread as a long. More...

static wxThreadIdType	GetMainId ()
	Returns the thread ID of the main thread. More...

static bool	IsMain ()
	Returns true if the calling thread is the main application thread. More...

static bool	SetConcurrency (size_t level)
	Sets the thread concurrency level for this process. More...

static void	Sleep (unsigned long milliseconds)
	Pauses the thread execution for the given amount of time. More...

static wxThread *	This ()
	Return the thread object for the calling thread. More...

static void	Yield ()
	Give the rest of the thread's time-slice to the system allowing the other threads to run. More...

Protected Member Functions
virtual ExitCode	Entry ()=0
	This is the entry point of the thread. More...

void	Exit (ExitCode exitcode=0)
	This is a protected function of the wxThread class and thus can only be called from a derived class. More...

Member Typedef Documentation

typedef void* wxThread::ExitCode

The return type for the thread functions.

Constructor & Destructor Documentation

wxThread::wxThread ( 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 Run() method.

The possible values for kind parameters are:

wxTHREAD_DETACHED - Creates a detached thread.
wxTHREAD_JOINABLE - Creates a joinable thread.

virtual wxThread::~wxThread ( )

virtual

The destructor frees the resources associated with the thread.

Notice that you should never delete a detached thread – you may only call Delete() 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. Joinable threads should be deleted explicitly. The Delete() and Kill() functions will not delete the C++ thread object. It is also safe to allocate them on stack.

Member Function Documentation

wxThreadError wxThread::Create ( unsigned int stackSize = 0 )

Creates a new thread.

The thread object is created in the suspended state, and you should call Run() 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 pthread_attr_setstacksize).

If you do not specify the stack size, the system's default value is used.

Note: It is not necessary to call this method since 2.9.5, Run() will create the thread internally. You only need to call Create() if you need to do something with the thread (e.g. pass its ID to an external library) before it starts.

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 you use a lot of threads (say several hundred), virtual address space can get tight unless you explicitly specify a smaller amount of thread stack space for each thread.

Returns

One of:

wxTHREAD_NO_ERROR - No error.
wxTHREAD_NO_RESOURCE - There were insufficient resources to create the thread.
wxTHREAD_NO_RUNNING - The thread is already running

wxThreadError wxThread::Delete	(	ExitCode *	rc = `NULL`,
		wxThreadWait	waitMode = `wxTHREAD_WAIT_DEFAULT`
	)

Calling Delete() gracefully terminates a detached thread, either when the thread calls TestDestroy() or when it finishes processing.

Parameters

rc	The thread exit code, if rc is not NULL.
waitMode	As described in wxThreadWait documentation, wxTHREAD_WAIT_BLOCK should be used as the wait mode even although currently wxTHREAD_WAIT_YIELD is for compatibility reasons. This parameter is new in wxWidgets 2.9.2.

Note: This function works on a joinable thread but in that case makes the TestDestroy() function of the thread return true and then waits for its completion (i.e. it differs from Wait() because it asks the thread to terminate before waiting).

See wxThread Deletion for a broader explanation of this routine.

virtual ExitCode wxThread::Entry ( )

protectedpure virtual

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 joinable threads and is the value returned by Wait(). This function is called by wxWidgets itself and should never be called directly.

void wxThread::Exit ( ExitCode exitcode = 0 )

protected

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. OnExit() will be called just before exiting.

static int wxThread::GetCPUCount ( )

static

Returns the number of system CPUs or -1 if the value is unknown.

For multi-core systems the returned value is typically the total number of cores, since the OS usually abstract a single N-core CPU as N different cores.

See also: SetConcurrency()

static wxThreadIdType wxThread::GetCurrentId ( )

static

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.

See also: GetMainId()

wxThreadIdType wxThread::GetId ( ) const

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

wxThreadKind wxThread::GetKind ( ) const

Returns the thread kind as it was given in the ctor.

Since: 2.9.0

static wxThreadIdType wxThread::GetMainId ( )

static

Returns the thread ID of the main thread.

See also: IsMain()

Since: 2.9.1

unsigned int wxThread::GetPriority ( ) const

Gets the priority of the thread, between 0 (lowest) and 100 (highest).

See also: SetPriority()

bool wxThread::IsAlive ( ) const

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.

bool wxThread::IsDetached ( ) const

Returns true if the thread is of the detached kind, false if it is a joinable one.

static bool wxThread::IsMain ( )

static

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

Main thread in the context of wxWidgets is the one which initialized the library.

See also: GetMainId(), GetCurrentId()

bool wxThread::IsPaused ( ) const

Returns true if the thread is paused.

bool wxThread::IsRunning ( ) const

Returns true if the thread is running.

This method may only be safely used for joinable threads, see the remark in IsAlive().

wxThreadError wxThread::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() for detached threads or Wait() for joinable threads 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 OnExit() 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 wxTHREAD_NOT_RUNNING error will be returned.

wxThreadError wxThread::Pause ( )

Suspends the thread.

Under some implementations (Win32), the thread is suspended immediately, under others it will only be suspended when it calls TestDestroy() 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.

wxThreadError wxThread::Resume ( )

Resumes a thread suspended by the call to Pause().

This function can only be called from another thread context.

wxThreadError wxThread::Run ( )

Starts the thread execution.

Note that once you Run() a detached thread, any function call you do on the thread pointer (you must allocate it on the heap) is "unsafe"; i.e. the thread may have terminated at any moment after Run() and your pointer may be dangling. See Types of wxThreads for an example of safe manipulation of detached threads.

This function can only be called from another thread context.

Finally, note that once a thread has completed and its Entry() function returns, you cannot call Run() on it again (an assert will fail in debug builds or wxTHREAD_RUNNING will be returned in release builds).

static bool wxThread::SetConcurrency ( size_t level )

static

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

void wxThread::SetPriority ( unsigned int priority )

Sets the priority of the thread, between 0 (lowest) and 100 (highest).

The following symbolic constants can be used in addition to raw values in 0..100 range:

wxPRIORITY_MIN: 0
wxPRIORITY_DEFAULT: 50
wxPRIORITY_MAX: 100

static void wxThread::Sleep ( unsigned long milliseconds )

static

Pauses the thread execution for the given amount of time.

This is the same as wxMilliSleep().

virtual bool wxThread::TestDestroy ( )

virtual

This function should be called periodically by the thread to ensure that calls to Pause() and Delete() will work.

If it returns true, the thread should exit as soon as possible. Notice that under some platforms (POSIX), implementation of Pause() also relies on this function being called, so not calling it would prevent both stopping and suspending thread from working.

static wxThread* wxThread::This ( )

static

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 a thread is undefined.

ExitCode wxThread::Wait ( wxThreadWait flags = wxTHREAD_WAIT_BLOCK )

Waits for a joinable thread to terminate and returns the value the thread returned from Entry() or "(ExitCode)-1" on error.

Notice that, unlike Delete(), this function doesn't cancel the thread in any way so the caller waits for as long as it takes to the thread to exit.

You can only Wait() for joinable (not detached) threads.

This function can only be called from another thread context.

Parameters

flags As described in wxThreadWait documentation, wxTHREAD_WAIT_BLOCK should be used as the wait mode even although currently wxTHREAD_WAIT_YIELD is for compatibility reasons. This parameter is new in wxWidgets 2.9.2.

See wxThread Deletion for a broader explanation of this routine.

static void wxThread::Yield ( )

static

Give the rest of the thread's time-slice to the system allowing the other threads to run.

Note that using this function is strongly discouraged, since in many cases it indicates a design weakness of your threading model (as does using Sleep() functions).

Threads should use the CPU in an efficient manner, i.e. they should do their current work efficiently, then as soon as the work is done block on a wakeup event (wxCondition, wxMutex, select(), poll(), ...) which will get signalled e.g. by other threads or a user device once further thread work is available. Using Yield() or Sleep() indicates polling-type behaviour, since we're fuzzily giving up our timeslice and wait until sometime later we'll get reactivated, at which time we realize that there isn't really much to do and Yield() again...

The most critical characteristic of Yield() is that it's operating system specific: there may be scheduler changes which cause your thread to not wake up relatively soon again, but instead many seconds later, causing huge performance issues for your application.

With a well-behaving, CPU-efficient thread the operating system is likely to properly care for its reactivation the moment it needs it, whereas with non-deterministic, Yield-using threads all bets are off and the system scheduler is free to penalize them drastically, and this effect gets worse with increasing system load due to less free CPU resources available. You may refer to various Linux kernel sched_yield discussions for more information.

Detailed Description

Types of wxThreads

wxThread Deletion

wxWidgets Calls in Secondary Threads

Don't Poll a wxThread

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation