X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/382f12e41917abf78fb7f00d786c7ead112e4df4..0847e36eff0512bf3c50c01e8d9dcff5e693ada5:/interface/wx/thread.h diff --git a/interface/wx/thread.h b/interface/wx/thread.h index 0985caf1b6..89eccc0b13 100644 --- a/interface/wx/thread.h +++ b/interface/wx/thread.h @@ -279,7 +279,7 @@ public: Example: @code - extern const wxEventType wxEVT_COMMAND_MYTHREAD_UPDATE; + wxDECLARE_EVENT(wxEVT_COMMAND_MYTHREAD_UPDATE, wxThreadEvent); class MyFrame : public wxFrame, public wxThreadHelper { @@ -298,7 +298,7 @@ public: ... void DoStartALongTask(); - void OnThreadUpdate(wxCommandEvent& evt); + void OnThreadUpdate(wxThreadEvent& evt); void OnClose(wxCloseEvent& evt); ... @@ -312,7 +312,7 @@ public: DECLARE_EVENT_TABLE() }; - DEFINE_EVENT_TYPE(wxEVT_COMMAND_MYTHREAD_UPDATE) + wxDEFINE_EVENT(wxEVT_COMMAND_MYTHREAD_UPDATE, wxThreadEvent) BEGIN_EVENT_TABLE(MyFrame, wxFrame) EVT_COMMAND(wxID_ANY, wxEVT_COMMAND_MYTHREAD_UPDATE, MyFrame::OnThreadUpdate) EVT_CLOSE(MyFrame::OnClose) @@ -364,7 +364,7 @@ public: // VERY IMPORTANT: do not call any GUI function inside this // function; rather use wxQueueEvent(): - wxQueueEvent(this, new wxCommandEvent(wxEVT_COMMAND_MYTHREAD_UPDATE)); + wxQueueEvent(this, new wxThreadEvent(wxEVT_COMMAND_MYTHREAD_UPDATE)); // we used pointer 'this' assuming it's safe; see OnClose() } @@ -386,7 +386,7 @@ public: Destroy(); } - void MyFrame::OnThreadUpdate(wxCommandEvent&evt) + void MyFrame::OnThreadUpdate(wxThreadEvent& evt) { // ...do something... e.g. m_pGauge->Pulse(); @@ -399,7 +399,7 @@ public: @library{wxbase} @category{threading} - @see wxThread + @see wxThread, wxThreadEvent */ class wxThreadHelper { @@ -535,11 +535,17 @@ 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(); @@ -631,8 +637,8 @@ enum @code // declare a new type of event, to be used by our MyThread class: - extern const wxEventType wxEVT_COMMAND_MYTHREAD_COMPLETED; - extern const wxEventType wxEVT_COMMAND_MYTHREAD_UPDATE; + wxDECLARE_EVENT(wxEVT_COMMAND_MYTHREAD_COMPLETED, wxThreadEvent); + wxDECLARE_EVENT(wxEVT_COMMAND_MYTHREAD_UPDATE, wxThreadEvent); class MyFrame; class MyThread : public wxThread @@ -669,7 +675,8 @@ enum // a resume routine would be nearly identic to DoPauseThread() void DoResumeThread() { ... } - void OnThreadCompletion(wxCommandEvent&); + void OnThreadUpdate(wxThreadEvent&); + void OnThreadCompletion(wxThreadEvent&); void OnClose(wxCloseEvent&); protected: @@ -686,8 +693,8 @@ enum EVT_COMMAND(wxID_ANY, wxEVT_COMMAND_MYTHREAD_COMPLETED, MyFrame::OnThreadCompletion) END_EVENT_TABLE() - DEFINE_EVENT_TYPE(wxEVT_COMMAND_MYTHREAD_COMPLETED) - DEFINE_EVENT_TYPE(wxEVT_COMMAND_MYTHREAD_UPDATE) + wxDEFINE_EVENT(wxEVT_COMMAND_MYTHREAD_COMPLETED, wxThreadEvent) + wxDEFINE_EVENT(wxEVT_COMMAND_MYTHREAD_UPDATE, wxThreadEvent) void MyFrame::DoStartThread() { @@ -721,13 +728,13 @@ enum { // ... do a bit of work... - wxQueueEvent(m_pHandler, new wxCommandEvent(wxEVT_COMMAND_MYTHREAD_UPDATE)); + 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 wxCommandEvent(wxEVT_COMMAND_MYTHREAD_COMPLETED)); + wxQueueEvent(m_pHandler, new wxThreadEvent(wxEVT_COMMAND_MYTHREAD_COMPLETED)); return (wxThread::ExitCode)0; // success } @@ -740,12 +747,12 @@ enum m_pHandler->m_pThread = NULL; } - void MyFrame::OnThreadCompletion(wxCommandEvent&) + void MyFrame::OnThreadCompletion(wxThreadEvent&) { wxMessageOutputDebug().Printf("MYFRAME: MyThread exited!\n"); } - void MyFrame::OnThreadUpdate(wxCommandEvent&) + void MyFrame::OnThreadUpdate(wxThreadEvent&) { wxMessageOutputDebug().Printf("MYFRAME: MyThread update...\n"); } @@ -863,9 +870,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 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. @@ -982,7 +989,10 @@ public: /** 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 wxThreadIdType GetCurrentId(); @@ -1000,6 +1010,15 @@ public: */ wxThreadKind GetKind() const; + /** + Returns the thread ID of the main thread. + + @see IsMain() + + @since 2.9.1 + */ + static wxThreadIdType GetMainId(); + /** Gets the priority of the thread, between zero and 100. @@ -1028,6 +1047,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(); @@ -1505,6 +1529,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(); @@ -1620,6 +1647,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 @@ -1645,7 +1674,7 @@ bool wxIsMainThread(); @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.