Document that throwing exceptions from wxTimer::Notify() is unsupported.

[wxWidgets.git] / interface / wx / thread.h

diff --git a/interface/wx/thread.h b/interface/wx/thread.h
index 050e253525baa9156183633b982c2b58be76c80e..89eccc0b1329e5e3c8127ea456d0557a14bf9b76 100644 (file)
--- a/interface/wx/thread.h
+++ b/interface/wx/thread.h
@@ -279,7 +279,7 @@ public:
 
     Example:
     @code
 
     Example:
     @code

-        extern const wxEventType wxEVT_COMMAND_MYTHREAD_UPDATE;
+        wxDECLARE_EVENT(wxEVT_COMMAND_MYTHREAD_UPDATE, wxThreadEvent);

 
         class MyFrame : public wxFrame, public wxThreadHelper
         {
 
         class MyFrame : public wxFrame, public wxThreadHelper
         {


@@ -298,7 +298,7 @@ public:
 
             ...
             void DoStartALongTask();
 
             ...
             void DoStartALongTask();

-            void OnThreadUpdate(wxCommandEvent& evt);
+            void OnThreadUpdate(wxThreadEvent& evt);

             void OnClose(wxCloseEvent& evt);
             ...
 
             void OnClose(wxCloseEvent& evt);
             ...
 


@@ -312,7 +312,7 @@ public:
             DECLARE_EVENT_TABLE()
         };
 
             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)
         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():
 
                 // 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()
             }
 
                     // we used pointer 'this' assuming it's safe; see OnClose()
             }
 


@@ -386,7 +386,7 @@ public:
             Destroy();
         }
 
             Destroy();
         }
 

-        void MyFrame::OnThreadUpdate(wxCommandEvent&evt)
+        void MyFrame::OnThreadUpdate(wxThreadEvent& evt)

         {
             // ...do something... e.g. m_pGauge->Pulse();
 
         {
             // ...do something... e.g. m_pGauge->Pulse();
 


@@ -399,7 +399,7 @@ public:
     @library{wxbase}
     @category{threading}
 
     @library{wxbase}
     @category{threading}
 

-    @see wxThread
+    @see wxThread, wxThreadEvent

 */
 class wxThreadHelper
 {
 */
 class wxThreadHelper
 {


@@ -454,6 +454,12 @@ public:
     */
     virtual ExitCode Entry() = 0;
 
     */
     virtual ExitCode Entry() = 0;
 

+    /**
+        @deprecated
+        Use CreateThread() instead.
+    */
+    wxThreadError Create(unsigned int stackSize = 0);
+

     /**
         Creates a new thread of the given @a kind.
 
     /**
         Creates a new thread of the given @a kind.
 


@@ -529,11 +535,17 @@ public:
     ~wxCriticalSection();
 
     /**
     ~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.
         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();
 
     */
     void Enter();
 


@@ -625,8 +637,8 @@ enum
 
     @code
     // declare a new type of event, to be used by our MyThread class:
 
     @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
     class MyFrame;
 
     class MyThread : public wxThread


@@ -663,7 +675,8 @@ enum
         // a resume routine would be nearly identic to DoPauseThread()
         void DoResumeThread() { ... }
 
         // a resume routine would be nearly identic to DoPauseThread()
         void DoResumeThread() { ... }
 

-        void OnThreadCompletion(wxCommandEvent&);
+        void OnThreadUpdate(wxThreadEvent&);
+        void OnThreadCompletion(wxThreadEvent&);

         void OnClose(wxCloseEvent&);
 
     protected:
         void OnClose(wxCloseEvent&);
 
     protected:


@@ -680,8 +693,8 @@ enum
         EVT_COMMAND(wxID_ANY, wxEVT_COMMAND_MYTHREAD_COMPLETED, MyFrame::OnThreadCompletion)
     END_EVENT_TABLE()
 
         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()
     {
 
     void MyFrame::DoStartThread()
     {


@@ -715,13 +728,13 @@ enum
         {
             // ... do a bit of work...
 
         {
             // ... 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)
         }
 
         // 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
     }
 
         return (wxThread::ExitCode)0;     // success
     }


@@ -734,12 +747,12 @@ enum
         m_pHandler->m_pThread = NULL;
     }
 
         m_pHandler->m_pThread = NULL;
     }
 

-    void MyFrame::OnThreadCompletion(wxCommandEvent&)
+    void MyFrame::OnThreadCompletion(wxThreadEvent&)

     {
         wxMessageOutputDebug().Printf("MYFRAME: MyThread exited!\n");
     }
 
     {
         wxMessageOutputDebug().Printf("MYFRAME: MyThread exited!\n");
     }
 

-    void MyFrame::OnThreadUpdate(wxCommandEvent&)
+    void MyFrame::OnThreadUpdate(wxThreadEvent&)

     {
         wxMessageOutputDebug().Printf("MYFRAME: MyThread update...\n");
     }
     {
         wxMessageOutputDebug().Printf("MYFRAME: MyThread update...\n");
     }


@@ -857,9 +870,9 @@ enum
     as MFC.
 
     A workaround for some wxWidgets ports is calling wxMutexGUIEnter()
     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.
 
     This does not imply that calls to these classes are thread-safe, however,
     as most wxWidgets classes are not thread-safe, including wxString.
 


@@ -966,15 +979,22 @@ public:
     /**
         Returns the number of system CPUs or -1 if the value is unknown.
 
     /**
         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.
         @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.
         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
 
     /**
         Gets the thread identifier: this is a platform dependent number that uniquely


@@ -983,6 +1003,22 @@ public:
     */
     wxThreadIdType GetId() const;
 
     */
     wxThreadIdType GetId() const;
 

+    /**
+        Returns the thread kind as it was given in the ctor.
+
+        @since 2.9.0
+    */
+    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.
 
     /**
         Gets the priority of the thread, between zero and 100.
 


@@ -1011,6 +1047,11 @@ public:
 
     /**
         Returns @true if the calling thread is the main application thread.
 
     /**
         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();
 
     */
     static bool IsMain();
 


@@ -1051,17 +1092,6 @@ public:
     */
     wxThreadError Kill();
 
     */
     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.
 
     /**
         Suspends the thread.
 


@@ -1220,6 +1250,19 @@ protected:
         OnExit() will be called just before exiting.
     */
     void Exit(ExitCode exitcode = 0);
         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();

 };
 
 
 };
 
 


@@ -1486,6 +1529,9 @@ public:
         Locks the mutex object.
         This is equivalent to LockTimeout() with infinite timeout.
 
         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();
         @return One of: @c wxMUTEX_NO_ERROR, @c wxMUTEX_DEAD_LOCK.
     */
     wxMutexError Lock();


@@ -1518,7 +1564,7 @@ public:
 // Global functions/macros
 // ============================================================================
 
 // Global functions/macros
 // ============================================================================
 

-/** @ingroup group_funcmacro_thread */
+/** @addtogroup group_funcmacro_thread */

 //@{
 
 /**
 //@{
 
 /**


@@ -1601,6 +1647,8 @@ public:
 */
 bool wxIsMainThread();
 
 */
 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
 /**
     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


@@ -1619,14 +1667,14 @@ bool wxIsMainThread();
         wxMutexGuiEnter();
 
         // Call GUI here:
         wxMutexGuiEnter();
 
         // Call GUI here:

-        my_window-DrawSomething();
+        my_window->DrawSomething();

 
         wxMutexGuiLeave();
     }
     @endcode
 
     This function is only defined on platforms which support preemptive
 
         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.
 
     @note Under GTK, no creation of top-level windows is allowed in any thread
           but the main one.