 |
Version: 2.9.4 |
#include </home/zeitlin/src/wx/github/interface/wx/thread.h>
スレッドはプログラム内の基本的な実行パスです。
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.
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->Create() != wxTHREAD_NO_ERROR ) { wxLogError("Can't create the thread!"); delete m_pThread; m_pThread = NULL; } else { 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.
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.
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". These include all threads created by Create() or the corresponding constructors.
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.
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.
Public Types | |
| typedef void * | ExitCode |
| The return type for the thread functions. | |
Public Member Functions | |
| wxThread (wxThreadKind kind=wxTHREAD_DETACHED) | |
| This constructor creates a new detached (default) or joinable C++ thread object. | |
| virtual | ~wxThread () |
| The destructor frees the resources associated with the thread. | |
| wxThreadError | Create (unsigned int stackSize=0) |
| Creates a new thread. | |
| wxThreadError | Delete (ExitCode *rc=NULL, wxThreadWait waitMode=wxTHREAD_WAIT_BLOCK) |
| Calling Delete() gracefully terminates a detached thread, either when the thread calls TestDestroy() or when it finishes processing. | |
| 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. | |
| wxThreadKind | GetKind () const |
| Returns the thread kind as it was given in the ctor. | |
| unsigned int | GetPriority () const |
| Gets the priority of the thread, between zero and 100. | |
| bool | IsAlive () const |
| Returns true if the thread is alive (i.e. | |
| bool | IsDetached () const |
| Returns true if the thread is of the detached kind, false if it is a joinable one. | |
| 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. | |
| wxThreadError | Pause () |
| Suspends the thread. | |
| wxThreadError | Resume () |
| Resumes a thread suspended by the call to Pause(). | |
| wxThreadError | Run () |
| Starts the thread execution. | |
| void | SetPriority (unsigned int priority) |
| Sets the priority of the thread, between 0 and 100. | |
| virtual bool | TestDestroy () |
| This function should be called periodically by the thread to ensure that calls to Pause() and Delete() will work. | |
| 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. | |
Static Public Member Functions | |
| static int | GetCPUCount () |
| CPU の数か、数が不明な場合は -1 を返却します。 | |
| static wxThreadIdType | GetCurrentId () |
| Returns the platform specific thread ID of the current thread as a long. | |
| static wxThreadIdType | GetMainId () |
| Returns the thread ID of the main thread. | |
| static bool | IsMain () |
| Returns true if the calling thread is the main application thread. | |
| static bool | SetConcurrency (size_t level) |
| Sets the thread concurrency level for this process. | |
| static void | Sleep (unsigned long milliseconds) |
| Pauses the thread execution for the given amount of time. | |
| static wxThread * | This () |
| Return the thread object for the calling thread. | |
| static void | Yield () |
| Give the rest of the thread's time-slice to the system allowing the other threads to run. | |
Protected Member Functions | |
| virtual ExitCode | Entry ()=0 |
| This is the entry point of the thread. | |
| void | Exit (ExitCode exitcode=0) |
| This is a protected function of the wxThread class and thus can only be called from a derived class. | |
| typedef void* wxThread::ExitCode |
The return type for the thread functions.
| 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 Create() and Run() methods.
The possible values for kind parameters are:
| 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.
| 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.
| wxThreadError wxThread::Delete | ( | ExitCode * | rc = NULL, |
| wxThreadWait | waitMode = wxTHREAD_WAIT_BLOCK |
||
| ) |
Calling Delete() gracefully terminates a detached thread, either when the thread calls TestDestroy() or when it finishes processing.
| 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. |
See wxThread Deletion for a broader explanation of this routine.
| virtual ExitCode wxThread::Entry | ( | ) | [protected, pure 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] |
CPU の数か、数が不明な場合は -1 を返却します。
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.
| 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.
| 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.
| static wxThreadIdType wxThread::GetMainId | ( | ) | [static] |
| unsigned int wxThread::GetPriority | ( | ) | const |
Gets the priority of the thread, between zero and 100.
The following priorities are defined:
| 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.
| 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.
Should be called after Create().
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.
| void wxThread::SetPriority | ( | unsigned int | priority | ) |
| 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.
| 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 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.
See also Sleep().
