X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/7323ff1aee02cc8c8979b6b25f84049ab0c081ae..d3fa4bc22e84e3ca4d88cc1772f2d414140a1017:/interface/wx/thread.h
diff --git a/interface/wx/thread.h b/interface/wx/thread.h
index f530c12157..0854cb5576 100644
--- a/interface/wx/thread.h
+++ b/interface/wx/thread.h
@@ -3,7 +3,7 @@
// Purpose: interface of all thread-related wxWidgets classes
// Author: wxWidgets team
// RCS-ID: $Id$
-// Licence: wxWindows license
+// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
@@ -51,8 +51,6 @@ enum wxCondError
{
m_mutex = mutex;
m_condition = condition;
-
- Create();
}
virtual ExitCode Entry()
@@ -151,7 +149,7 @@ public:
@see Broadcast()
*/
- void Signal();
+ wxCondError Signal();
/**
Waits until the condition is signalled.
@@ -188,23 +186,6 @@ public:
wxCondError WaitTimeout(unsigned long milliseconds);
};
-// There are 2 types of mutexes: normal mutexes and recursive ones. The attempt
-// to lock a normal mutex by a thread which already owns it results in
-// undefined behaviour (it always works under Windows, it will almost always
-// result in a deadlock under Unix). Locking a recursive mutex in such
-// situation always succeeds and it must be unlocked as many times as it has
-// been locked.
-//
-// However recursive mutexes have several important drawbacks: first, in the
-// POSIX implementation, they're less efficient. Second, and more importantly,
-// they CAN NOT BE USED WITH CONDITION VARIABLES under Unix! Using them with
-// wxCondition will work under Windows and some Unices (notably Linux) but will
-// deadlock under other Unix versions (e.g. Solaris). As it might be difficult
-// to ensure that a recursive mutex is not used with wxCondition, it is a good
-// idea to avoid using recursive mutexes at all. Also, the last problem with
-// them is that some (older) Unix versions don't support this at all -- which
-// results in a configure warning when building and a deadlock when using them.
-
/**
@class wxCriticalSectionLocker
@@ -269,7 +250,8 @@ public:
@class wxThreadHelper
The wxThreadHelper class is a mix-in class that manages a single background
- thread. By deriving from wxThreadHelper, a class can implement the thread
+ thread, either detached or joinable (see wxThread for the differences).
+ By deriving from wxThreadHelper, a class can implement the thread
code in its own wxThreadHelper::Entry() method and easily share data and
synchronization objects between the main thread and the worker thread.
@@ -282,31 +264,158 @@ public:
Ordinarily, a wxThread derived object would be created with the calculation
code implemented in wxThread::Entry. To access the inputs to the calculation,
- the frame object would often to pass a pointer to itself to the thread object.
+ the frame object would often need to pass a pointer to itself to the thread object.
Similarly, the frame object would hold a pointer to the thread object.
+
Shared data and synchronization objects could be stored in either object
though the object without the data would have to access the data through
a pointer.
- However, with wxThreadHelper, the frame object and the thread object are
+ However with wxThreadHelper the frame object and the thread object are
treated as the same object. Shared data and synchronization variables are
stored in the single object, eliminating a layer of indirection and the
associated pointers.
+ Example:
+ @code
+ wxDECLARE_EVENT(myEVT_THREAD_UPDATE, wxThreadEvent);
+
+ class MyFrame : public wxFrame, public wxThreadHelper
+ {
+ public:
+ MyFrame(...) { ... }
+ ~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 DoStartALongTask();
+ void OnThreadUpdate(wxThreadEvent& evt);
+ void OnClose(wxCloseEvent& evt);
+ ...
+
+ protected:
+ virtual wxThread::ExitCode Entry();
+
+ // the output data of the Entry() routine:
+ char m_data[1024];
+ wxCriticalSection m_dataCS; // protects field above
+
+ wxDECLARE_EVENT_TABLE();
+ };
+
+ wxDEFINE_EVENT(myEVT_THREAD_UPDATE, wxThreadEvent)
+ wxBEGIN_EVENT_TABLE(MyFrame, wxFrame)
+ EVT_THREAD(wxID_ANY, myEVT_THREAD_UPDATE, MyFrame::OnThreadUpdate)
+ EVT_CLOSE(MyFrame::OnClose)
+ wxEND_EVENT_TABLE()
+
+ void MyFrame::DoStartALongTask()
+ {
+ // we want to start a long task, but we don't want our GUI to block
+ // while it's executed, so we use a thread to do it.
+ if (CreateThread(wxTHREAD_JOINABLE) != wxTHREAD_NO_ERROR)
+ {
+ wxLogError("Could not create the worker thread!");
+ return;
+ }
+
+ // go!
+ if (GetThread()->Run() != wxTHREAD_NO_ERROR)
+ {
+ wxLogError("Could not run the worker thread!");
+ return;
+ }
+ }
+
+ wxThread::ExitCode MyFrame::Entry()
+ {
+ // IMPORTANT:
+ // this function gets executed in the secondary thread context!
+
+ int offset = 0;
+
+ // here we do our long task, periodically calling TestDestroy():
+ while (!GetThread()->TestDestroy())
+ {
+ // since this Entry() is implemented in MyFrame context we don't
+ // need any pointer to access the m_data, m_processedData, m_dataCS
+ // variables... very nice!
+
+ // this is an example of the generic structure of a download thread:
+ char buffer[1024];
+ download_chunk(buffer, 1024); // this takes time...
+
+ {
+ // ensure no one reads m_data while we write it
+ wxCriticalSectionLocker lock(m_dataCS);
+ memcpy(m_data+offset, buffer, 1024);
+ offset += 1024;
+ }
+
+
+ // VERY IMPORTANT: do not call any GUI function inside this
+ // function; rather use wxQueueEvent():
+ wxQueueEvent(this, new wxThreadEvent(wxEVT_COMMAND_MYTHREAD_UPDATE));
+ // we used pointer 'this' assuming it's safe; see OnClose()
+ }
+
+ // TestDestroy() returned true (which means the main thread asked us
+ // to terminate as soon as possible) or we ended the long task...
+ return (wxThread::ExitCode)0;
+ }
+
+ void MyFrame::OnClose(wxCloseEvent&)
+ {
+ // important: before terminating, we _must_ wait for our joinable
+ // thread to end, if it's running; in fact it uses variables of this
+ // instance and posts events to *this event handler
+
+ if (GetThread() && // DoStartALongTask() may have not been called
+ GetThread()->IsRunning())
+ GetThread()->Wait();
+
+ Destroy();
+ }
+
+ void MyFrame::OnThreadUpdate(wxThreadEvent& evt)
+ {
+ // ...do something... e.g. m_pGauge->Pulse();
+
+ // read some parts of m_data just for fun:
+ wxCriticalSectionLocker lock(m_dataCS);
+ wxPrintf("%c", m_data[100]);
+ }
+ @endcode
+
@library{wxbase}
@category{threading}
- @see wxThread
+ @see wxThread, wxThreadEvent
*/
class wxThreadHelper
{
public:
/**
- This constructor simply initializes a member variable.
+ This constructor simply initializes internal member variables and tells
+ wxThreadHelper which type the thread internally managed should be.
*/
- wxThreadHelper();
+ wxThreadHelper(wxThreadKind kind = wxTHREAD_JOINABLE);
/**
- The destructor frees the resources associated with the thread.
+ The destructor frees the resources associated with the thread, forcing
+ it to terminate (it uses wxThread::Kill function).
+
+ Because of the wxThread::Kill unsafety, you should always wait
+ (with wxThread::Wait) for joinable threads to end or call wxThread::Delete
+ on detached threads, instead of relying on this destructor for stopping
+ the thread.
*/
virtual ~wxThreadHelper();
@@ -316,32 +425,95 @@ public:
This function is pure virtual and must be implemented by any derived class.
The thread execution will start here.
+ You'll typically want your Entry() to look like:
+ @code
+ wxThread::ExitCode Entry()
+ {
+ while (!GetThread()->TestDestroy())
+ {
+ // ... do some work ...
+
+ if (IsWorkCompleted)
+ break;
+
+ if (HappenedStoppingError)
+ return (wxThread::ExitCode)1; // failure
+ }
+
+ return (wxThread::ExitCode)0; // success
+ }
+ @endcode
+
The returned value is the thread exit code which is only useful for
joinable threads and is the value returned by @c "GetThread()->Wait()".
This function is called by wxWidgets itself and should never be called
directly.
*/
- virtual ExitCode Entry();
+ virtual ExitCode Entry() = 0;
/**
- Creates a new thread.
+ Callback called by Delete() before actually deleting the thread.
+
+ This function can be overridden by the derived class to perform some
+ specific task when the thread is gracefully destroyed. Notice that it
+ will be executed in the context of the thread that called Delete() and
+ not in this thread's context.
+
+ TestDestroy() will be true for the thread before OnDelete() gets
+ executed.
+
+ @since 2.9.2
+
+ @see OnKill()
+ */
+ virtual void OnDelete();
+
+ /**
+ Callback called by Kill() before actually killing the thread.
+
+ This function can be overridden by the derived class to perform some
+ specific task when the thread is terminated. Notice that it will be
+ executed in the context of the thread that called Kill() and not
+ in this thread's context.
+
+ @since 2.9.2
+
+ @see OnDelete()
+ */
+ virtual void OnKill();
+
+ /**
+ @deprecated
+ Use CreateThread() instead.
+ */
+ wxThreadError Create(unsigned int stackSize = 0);
+
+ /**
+ Creates a new thread of the given @a kind.
The thread object is created in the suspended state, and you
- should call @ref wxThread::Run GetThread()-Run to start running it.
+ should call @ref wxThread::Run "GetThread()->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).
+ on platforms that don't support setting it explicitly, e.g. Unix).
@return One of the ::wxThreadError enum values.
*/
- wxThreadError Create(unsigned int stackSize = 0);
+ wxThreadError CreateThread(wxThreadKind kind = wxTHREAD_JOINABLE,
+ unsigned int stackSize = 0);
/**
- This is a public function that returns the wxThread object
- associated with the thread.
+ This is a public function that returns the wxThread object associated with
+ the thread.
*/
wxThread* GetThread() const;
+
+ /**
+ Returns the last type of thread given to the CreateThread() function
+ or to the constructor.
+ */
+ wxThreadKind GetThreadKind() const;
};
/**
@@ -370,11 +542,15 @@ enum wxCriticalSectionType
Finally, you should try to use wxCriticalSectionLocker class whenever
possible instead of directly using wxCriticalSection for the same reasons
- wxMutexLocker is preferrable to wxMutex - please see wxMutex for an example.
+ wxMutexLocker is preferable to wxMutex - please see wxMutex for an example.
@library{wxbase}
@category{threading}
+ @note Critical sections can be used before the wxWidgets library is fully
+ initialized. In particular, it's safe to create global
+ wxCriticalSection instances.
+
@see wxThread, wxCondition, wxCriticalSectionLocker
*/
class wxCriticalSection
@@ -392,14 +568,28 @@ public:
~wxCriticalSection();
/**
- Enter the critical section (same as locking a mutex).
-
+ Enter the critical section (same as locking a mutex): if another thread
+ has already entered it, this call will block until the other thread
+ calls Leave().
There is no error return for this function.
- After entering the critical section protecting some global
- data the thread running in critical section may safely use/modify it.
+
+ After entering the critical section protecting a data variable,
+ the thread running inside the critical section may safely use/modify it.
+
+ Note that entering the same critical section twice or more from the same
+ thread doesn't result in a deadlock; in this case in fact this function will
+ immediately return.
*/
void Enter();
+ /**
+ Try to enter the critical section (same as trying to lock a mutex).
+ If it can't, immediately returns false.
+
+ @since 2.9.3
+ */
+ bool TryEnter();
+
/**
Leave the critical section allowing other threads use the global data
protected by it. There is no error return for this function.
@@ -407,6 +597,46 @@ public:
void Leave();
};
+/**
+ The possible thread wait types.
+
+ @since 2.9.2
+*/
+enum wxThreadWait
+{
+ /**
+ No events are processed while waiting.
+
+ This is the default under all platforms except for wxMSW.
+ */
+ wxTHREAD_WAIT_BLOCK,
+
+ /**
+ Yield for event dispatching while waiting.
+
+ This flag is dangerous as it exposes the program using it to unexpected
+ reentrancies in the same way as calling wxYield() function does so you
+ are strongly advised to avoid its use and not wait for the thread
+ termination from the main (GUI) thread at all to avoid making your
+ application unresponsive.
+
+ Also notice that this flag is not portable as it is only implemented in
+ wxMSW and simply ignored under the other platforms.
+ */
+ wxTHREAD_WAIT_YIELD,
+
+ /**
+ Default wait mode for wxThread::Wait() and wxThread::Delete().
+
+ For compatibility reasons, the default wait mode is currently
+ wxTHREAD_WAIT_YIELD if WXWIN_COMPATIBILITY_2_8 is defined (and it is
+ by default). However, as mentioned above, you're strongly encouraged to
+ not use wxTHREAD_WAIT_YIELD and pass wxTHREAD_WAIT_BLOCK to wxThread
+ method explicitly.
+ */
+ wxTHREAD_WAIT_DEFAULT = wxTHREAD_WAIT_YIELD
+};
+
/**
The possible thread kinds.
*/
@@ -443,17 +673,6 @@ enum wxThreadError
wxTHREAD_MISC_ERROR
};
-/**
- Defines the interval of priority
-*/
-enum
-{
- WXTHREAD_MIN_PRIORITY = 0u,
- WXTHREAD_DEFAULT_PRIORITY = 50u,
- WXTHREAD_MAX_PRIORITY = 100u
-};
-
-
/**
@class wxThread
@@ -464,56 +683,233 @@ enum
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() 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.
+ 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.
+
@section thread_types Types of wxThreads
There are two types of threads in wxWidgets: @e detached and @e joinable,
- modeled after the the POSIX thread API. This is different from the Win32 API
+ 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 behavior. 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).
- Conversely, joinable threads do not delete themselves when they are done
+ By default wxThreads in wxWidgets use the @b 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
+ @b 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:
+
+ @code
+ // 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();
+ }
+ @endcode
+
+ For a more detailed and comprehensive example, see @sample{thread}.
+ For a simpler way to share data and synchronization objects between
+ the main and the secondary thread see wxThreadHelper.
+
+ Conversely, @b 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 @b 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.
+ 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.
@section thread_deletion 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 @ref thread_types.
+ @b joinable thread to release its memory, as outlined in @ref thread_types.
If you created a joinable thread on the heap, remember to delete it manually
with the @c 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,
+ Since @b 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() attempts to gracefully terminate a
- joinable and detached thread, respectively. It does this by waiting until
- the thread in question calls TestDestroy() or ends processing (returns
+ that call to Delete()). It should be implied that you should @b never attempt
+ to delete a detached thread with the @c 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 calling
- thread will come to halt. This is why it is important to call TestDestroy() in
- the Entry() routine of your threads as often as possible.
+ 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
@@ -523,10 +919,9 @@ enum
@section thread_secondary wxWidgets Calls in Secondary Threads
- All threads other than the "main application thread" (the one
- wxApp::OnInit() or your main function runs in, for example) are considered
- "secondary threads". These include all threads created by Create() or the
- corresponding constructors.
+ 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.
@@ -535,9 +930,9 @@ enum
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 either wxQueueEvent().
+ 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.
@@ -547,15 +942,15 @@ enum
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 behavior and has already deleted
- itself. Naturally, they instead attempt to use joinable threads in place
- of the previous behavior. 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.
+ because the thread is using the default behaviour (i.e. it's @b 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 wxPostEvent() or wxEvtHandler::AddPendingEvent().
+ 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
@@ -564,15 +959,21 @@ enum
@library{wxbase}
@category{threading}
- @see wxMutex, wxCondition, wxCriticalSection
+ @see wxThreadHelper, wxMutex, wxCondition, wxCriticalSection,
+ @ref overview_thread
*/
class wxThread
{
public:
+ /**
+ The return type for the thread functions.
+ */
+ typedef void* ExitCode;
+
/**
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 Create() and Run() methods.
+ for this you should use the Run() method.
The possible values for @a kind parameters are:
- @b wxTHREAD_DETACHED - Creates a detached thread.
@@ -599,7 +1000,13 @@ public:
to it (Ignored on platforms that don't support setting it explicitly,
eg. Unix system without @c pthread_attr_setstacksize).
- If you do not specify the stack size,the system's default value is used.
+ 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'
@@ -611,7 +1018,7 @@ public:
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 adress space can get tight unless you explicitly specify a
+ virtual address space can get tight unless you explicitly specify a
smaller amount of thread stack space for each thread.
@return One of:
@@ -622,50 +1029,81 @@ public:
wxThreadError Create(unsigned int stackSize = 0);
/**
- Calling Delete() gracefully terminates a detached thread, either when
- the thread calls TestDestroy() or finished processing.
+ Calling Delete() gracefully terminates a @b detached thread, either when
+ the thread calls TestDestroy() or when it finishes processing.
+
+ @param rc
+ The thread exit code, if rc is not NULL.
+
+ @param 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
- While this could work on a joinable thread you simply should not
- call this routine on one as afterwards you may not be able to call
- Wait() to free the memory of that thread).
+ 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 @ref thread_deletion for a broader explanation of this routine.
*/
- wxThreadError Delete();
+ wxThreadError Delete(ExitCode *rc = NULL,
+ wxThreadWait waitMode = wxTHREAD_WAIT_BLOCK);
/**
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 @e cores, since the OS usually abstract a single N-core CPU
+ as N different cores.
+
@see SetConcurrency()
*/
static int GetCPUCount();
/**
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 GetMainId()
*/
- static unsigned long GetCurrentId();
+ static wxThreadIdType GetCurrentId();
/**
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).
+ (i.e.\ the thread identifiers may be reused).
+ */
+ wxThreadIdType GetId() const;
+
+ /**
+ Returns the thread kind as it was given in the ctor.
+
+ @since 2.9.0
*/
- unsigned long GetId() const;
+ wxThreadKind GetKind() const;
/**
- Gets the priority of the thread, between zero and 100.
+ Returns the thread ID of the main thread.
+
+ @see IsMain()
+
+ @since 2.9.1
+ */
+ static wxThreadIdType GetMainId();
- The following priorities are defined:
- - @b WXTHREAD_MIN_PRIORITY: 0
- - @b WXTHREAD_DEFAULT_PRIORITY: 50
- - @b WXTHREAD_MAX_PRIORITY: 100
+ /**
+ Gets the priority of the thread, between 0 (lowest) and 100 (highest).
+
+ @see SetPriority()
*/
- int GetPriority() const;
+ unsigned int GetPriority() const;
/**
- 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 safely be used with joinable threads, not
detached ones as the latter delete themselves and so when the real thread is
@@ -682,6 +1120,11 @@ public:
/**
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 GetMainId(), GetCurrentId()
*/
static bool IsMain();
@@ -722,17 +1165,6 @@ public:
*/
wxThreadError Kill();
- /**
- 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 @ref Kill() killed.
-
- This function should never be called directly.
- */
- virtual void OnExit();
-
/**
Suspends the thread.
@@ -753,10 +1185,19 @@ public:
wxThreadError Resume();
/**
- Starts the thread execution. Should be called after
- Create().
+ Starts the thread execution.
+
+ Note that once you Run() a @b detached thread, @e any function call you do
+ on the thread pointer (you must allocate it on the heap) is @e "unsafe";
+ i.e. the thread may have terminated at any moment after Run() and your pointer
+ may be dangling. See @ref thread_types 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 @c wxTHREAD_RUNNING will be returned in release builds).
*/
wxThreadError Run();
@@ -773,15 +1214,15 @@ public:
static bool SetConcurrency(size_t level);
/**
- Sets the priority of the thread, between 0 and 100.
- It can only be set after calling Create() but before calling Run().
+ Sets the priority of the thread, between 0 (lowest) and 100 (highest).
- The following priorities are defined:
- - @b WXTHREAD_MIN_PRIORITY: 0
- - @b WXTHREAD_DEFAULT_PRIORITY: 50
- - @b WXTHREAD_MAX_PRIORITY: 100
+ 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
*/
- void SetPriority(int priority);
+ void SetPriority(unsigned int priority);
/**
Pauses the thread execution for the given amount of time.
@@ -812,20 +1253,27 @@ public:
static wxThread* This();
/**
- Waits for a joinable thread to terminate and returns the value the thread
- returned from Entry() or @c (ExitCode)-1 on error. Notice that, unlike
- Delete() doesn't cancel the thread in any way so the caller waits for as
- long as it takes to the thread to exit.
+ Waits for a @b joinable thread to terminate and returns the value the thread
+ returned from Entry() or @c "(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 @b joinable (not detached) threads.
- You can only Wait() for joinable (not detached) threads.
This function can only be called from another thread context.
+ @param 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.
+
See @ref thread_deletion for a broader explanation of this routine.
*/
- ExitCode Wait() const;
+ ExitCode Wait(wxThreadWait flags = wxTHREAD_WAIT_BLOCK);
/**
- Give the rest of the thread time slice to the system allowing the other
+ Give the rest of the thread's time-slice to the system allowing the other
threads to run.
Note that using this function is @b strongly discouraged, since in
@@ -851,8 +1299,8 @@ public:
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 drastically, and this effect gets worse
- with increasing system load due to less free CPU resources available.
+ 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 @c sched_yield discussions for more
information.
@@ -873,7 +1321,7 @@ protected:
This function is called by wxWidgets itself and should never be called
directly.
*/
- virtual ExitCode Entry();
+ virtual ExitCode Entry() = 0;
/**
This is a protected function of the wxThread class and thus can only be called
@@ -885,6 +1333,19 @@ protected:
OnExit() will be called just before exiting.
*/
void Exit(ExitCode exitcode = 0);
+
+private:
+
+ /**
+ 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 @ref Kill() killed.
+
+ This function should never be called directly.
+ */
+ virtual void OnExit();
};
@@ -983,7 +1444,7 @@ public:
- wxSEMA_TIMEOUT: Timeout occurred without receiving semaphore.
- wxSEMA_MISC_ERROR: Miscellaneous error.
*/
- wxSemaError WaitTimeout(unsigned longtimeout_millis);
+ wxSemaError WaitTimeout(unsigned long timeout_millis);
};
@@ -1084,7 +1545,7 @@ enum wxMutexError
For example, when several threads use the data stored in the linked list,
modifications to the list should only be allowed to one thread at a time
because during a new node addition the list integrity is temporarily broken
- (this is also called @e program invariant).
+ (this is also called @e program @e invariant).
@code
// this variable has an "s_" prefix because it is static: seeing an "s_" in
@@ -1125,9 +1586,9 @@ enum wxMutexError
Notice how wxMutexLocker was used in the second function to ensure that the
mutex is unlocked in any case: whether the function returns true or false
- (because the destructor of the local object lock is always called). Using
- this class instead of directly using wxMutex is, in general safer and is
- even more so if your program uses C++ exceptions.
+ (because the destructor of the local object @e lock is always called).
+ Using this class instead of directly using wxMutex is, in general, safer
+ and is even more so if your program uses C++ exceptions.
@library{wxbase}
@category{threading}
@@ -1151,6 +1612,9 @@ public:
Locks the mutex object.
This is equivalent to LockTimeout() with infinite timeout.
+ Note that if this mutex is already locked by the caller thread,
+ this function doesn't block but rather immediately returns.
+
@return One of: @c wxMUTEX_NO_ERROR, @c wxMUTEX_DEAD_LOCK.
*/
wxMutexError Lock();
@@ -1183,7 +1647,7 @@ public:
// Global functions/macros
// ============================================================================
-/** @ingroup group_funcmacro_thread */
+/** @addtogroup group_funcmacro_thread */
//@{
/**
@@ -1266,6 +1730,8 @@ public:
*/
bool wxIsMainThread();
+
+
/**
This function must be called when any thread other than the main GUI thread
wants to get access to the GUI library. This function will block the
@@ -1284,14 +1750,14 @@ bool wxIsMainThread();
wxMutexGuiEnter();
// Call GUI here:
- my_window-DrawSomething();
+ my_window->DrawSomething();
wxMutexGuiLeave();
}
@endcode
This function is only defined on platforms which support preemptive
- threads.
+ threads and only works under some ports (wxMSW currently).
@note Under GTK, no creation of top-level windows is allowed in any thread
but the main one.