give an error message when ran from a wrong location instead of just saying that...

[wxWidgets.git] / interface / thread.h

diff --git a/interface/thread.h b/interface/thread.h
index 98d51ae9e3dd3cf50468fa28d7654333b7945321..c7eca68d19c64fee0d5dc91fa0245d4d83cb1694 100644 (file)
--- a/interface/thread.h
+++ b/interface/thread.h
@@ -1,6 +1,6 @@
 /////////////////////////////////////////////////////////////////////////////
 // Name:        thread.h
 /////////////////////////////////////////////////////////////////////////////
 // Name:        thread.h

-// Purpose:     documentation for wxCondition class
+// Purpose:     interface of wxCondition

 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Licence:     wxWindows license
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Licence:     wxWindows license


@@ -33,16 +33,14 @@
     @library{wxbase}
     @category{thread}
 
     @library{wxbase}
     @category{thread}
 

-    @seealso
-    wxThread, wxMutex
+    @see wxThread, wxMutex

 */
 class wxCondition
 {
 public:
     /**
 */
 class wxCondition
 {
 public:
     /**

-        Default and only constructor. The @e mutex must be locked by the caller
+        Default and only constructor. The @a mutex must be locked by the caller

         before calling Wait() function.
         before calling Wait() function.

-        

         Use IsOk() to check if the object was successfully
         initialized.
     */
         Use IsOk() to check if the object was successfully
         initialized.
     */


@@ -58,8 +56,8 @@ public:
         Broadcasts to all waiting threads, waking all of them up. Note that this method
         may be called whether the mutex associated with this condition is locked or
         not.
         Broadcasts to all waiting threads, waking all of them up. Note that this method
         may be called whether the mutex associated with this condition is locked or
         not.

-        
-        @sa Signal()
+
+        @see Signal()

     */
     void Broadcast();
 
     */
     void Broadcast();
 


@@ -67,56 +65,53 @@ public:
         Returns @true if the object had been initialized successfully, @false
         if an error occurred.
     */
         Returns @true if the object had been initialized successfully, @false
         if an error occurred.
     */

-#define bool IsOk()     /* implementation is private */
+    bool IsOk() const;

 
     /**
         Signals the object waking up at most one thread. If several threads are waiting
         on the same condition, the exact thread which is woken up is undefined. If no
         threads are waiting, the signal is lost and the condition would have to be
         signalled again to wake up any thread which may start waiting on it later.
 
     /**
         Signals the object waking up at most one thread. If several threads are waiting
         on the same condition, the exact thread which is woken up is undefined. If no
         threads are waiting, the signal is lost and the condition would have to be
         signalled again to wake up any thread which may start waiting on it later.

-        

         Note that this method may be called whether the mutex associated with this
         condition is locked or not.
         Note that this method may be called whether the mutex associated with this
         condition is locked or not.

-        
-        @sa Broadcast()
+
+        @see Broadcast()

     */
     void Signal();
 
     /**
         Waits until the condition is signalled.
     */
     void Signal();
 
     /**
         Waits until the condition is signalled.

-        

         This method atomically releases the lock on the mutex associated with this
         condition (this is why it must be locked prior to calling Wait) and puts the
         thread to sleep until Signal() or
         Broadcast() is called. It then locks the mutex
         again and returns.
         This method atomically releases the lock on the mutex associated with this
         condition (this is why it must be locked prior to calling Wait) and puts the
         thread to sleep until Signal() or
         Broadcast() is called. It then locks the mutex
         again and returns.

-        

         Note that even if Signal() had been called before
         Wait without waking up any thread, the thread would still wait for another one
         and so it is important to ensure that the condition will be signalled after
         Wait or the thread may sleep forever.
         Note that even if Signal() had been called before
         Wait without waking up any thread, the thread would still wait for another one
         and so it is important to ensure that the condition will be signalled after
         Wait or the thread may sleep forever.

-        
+

         @returns Returns wxCOND_NO_ERROR on success, another value if an error
         @returns Returns wxCOND_NO_ERROR on success, another value if an error

-                   occurred.
-        
-        @sa WaitTimeout()
+                 occurred.
+
+        @see WaitTimeout()

     */
     wxCondError Wait();
 
     /**
         Waits until the condition is signalled or the timeout has elapsed.
     */
     wxCondError Wait();
 
     /**
         Waits until the condition is signalled or the timeout has elapsed.

-        

         This method is identical to Wait() except that it
         returns, with the return code of @c wxCOND_TIMEOUT as soon as the given
         timeout expires.
         This method is identical to Wait() except that it
         returns, with the return code of @c wxCOND_TIMEOUT as soon as the given
         timeout expires.

-        
+

         @param milliseconds
         @param milliseconds

-        Timeout in milliseconds
+            Timeout in milliseconds

     */
     wxCondError WaitTimeout(unsigned long milliseconds);
 };
 
 
     */
     wxCondError WaitTimeout(unsigned long milliseconds);
 };
 
 

+

 /**
     @class wxCriticalSectionLocker
     @wxheader{thread.h}
 /**
     @class wxCriticalSectionLocker
     @wxheader{thread.h}


@@ -157,15 +152,14 @@ public:
     @library{wxbase}
     @category{thread}
 
     @library{wxbase}
     @category{thread}
 

-    @seealso
-    wxCriticalSection, wxMutexLocker
+    @see wxCriticalSection, wxMutexLocker

 */
 class wxCriticalSectionLocker
 {
 public:
     /**
         Constructs a wxCriticalSectionLocker object associated with given
 */
 class wxCriticalSectionLocker
 {
 public:
     /**
         Constructs a wxCriticalSectionLocker object associated with given

-        @e criticalsection and enters it.
+        @a criticalsection and enters it.

     */
     wxCriticalSectionLocker(wxCriticalSection& criticalsection);
 
     */
     wxCriticalSectionLocker(wxCriticalSection& criticalsection);
 


@@ -176,6 +170,7 @@ public:
 };
 
 
 };
 
 

+

 /**
     @class wxThreadHelper
     @wxheader{thread.h}
 /**
     @class wxThreadHelper
     @wxheader{thread.h}


@@ -209,8 +204,7 @@ public:
     @library{wxbase}
     @category{thread}
 
     @library{wxbase}
     @category{thread}
 

-    @seealso
-    wxThread
+    @see wxThread

 */
 class wxThreadHelper
 {
 */
 class wxThreadHelper
 {


@@ -231,7 +225,7 @@ public:
         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).
         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).

-        
+

         @returns One of:
     */
     wxThreadError Create(unsigned int stackSize = 0);
         @returns One of:
     */
     wxThreadError Create(unsigned int stackSize = 0);


@@ -239,11 +233,9 @@ public:
     /**
         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.
     /**
         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
         @ref wxThread::wait GetThread()-Wait.
         The returned value is the thread exit code which is only useful for
         joinable threads and is the value returned by
         @ref wxThread::wait GetThread()-Wait.

-        

         This function is called by wxWidgets itself and should never be called
         directly.
     */
         This function is called by wxWidgets itself and should never be called
         directly.
     */


@@ -253,22 +245,22 @@ public:
         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();
+    wxThread* GetThread();

 
     /**
         wxThread * m_thread
 
     /**
         wxThread * m_thread

-        

         the actual wxThread object.
     */
 };
 
 
         the actual wxThread object.
     */
 };
 
 

+

 /**
     @class wxCriticalSection
     @wxheader{thread.h}
 
     A critical section object is used for exactly the same purpose as
 /**
     @class wxCriticalSection
     @wxheader{thread.h}
 
     A critical section object is used for exactly the same purpose as

-    mutexes. The only difference is that under Windows platform
+    mutexes(). The only difference is that under Windows platform

     critical sections are only visible inside one process, while mutexes may be
     shared between processes, so using critical sections is slightly more
     efficient. The terminology is also slightly different: mutex may be locked (or
     critical sections are only visible inside one process, while mutexes may be
     shared between processes, so using critical sections is slightly more
     efficient. The terminology is also slightly different: mutex may be locked (or


@@ -284,8 +276,7 @@ public:
     @library{wxbase}
     @category{thread}
 
     @library{wxbase}
     @category{thread}
 

-    @seealso
-    wxThread, wxCondition, wxCriticalSectionLocker
+    @see wxThread, wxCondition, wxCriticalSectionLocker

 */
 class wxCriticalSection
 {
 */
 class wxCriticalSection
 {


@@ -315,6 +306,7 @@ public:
 };
 
 
 };
 
 

+

 /**
     @class wxThread
     @wxheader{thread.h}
 /**
     @class wxThread
     @wxheader{thread.h}


@@ -328,16 +320,15 @@ public:
     also
     makes it much easier to shoot oneself in the foot, so careful use of
     synchronization
     also
     makes it much easier to shoot oneself in the foot, so careful use of
     synchronization

-    objects such as mutexes or @ref overview_wxcriticalsection "critical sections"
-    is recommended. In addition, don't create global thread
+    objects such as mutexes() or @ref overview_wxcriticalsection "critical
+    sections" 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.
 
     @library{wxbase}
     @category{thread}
 
     objects because they allocate memory in their constructor, which will cause
     problems for the memory checking system.
 
     @library{wxbase}
     @category{thread}
 

-    @seealso
-    wxMutex, wxCondition, wxCriticalSection
+    @see wxMutex, wxCondition, wxCriticalSection

 */
 class wxThread
 {
 */
 class wxThread
 {


@@ -347,18 +338,14 @@ public:
         object. It
         does not create or start execution of the real thread -- for this you should
         use the Create() and Run() methods.
         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 @e kind parameters are:
-        
-        
+        The possible values for @a kind parameters are:
+

         @b wxTHREAD_DETACHED
         @b wxTHREAD_DETACHED

-        
-        
+

         Creates a detached thread.
         Creates a detached thread.

-        
+

         @b wxTHREAD_JOINABLE
         @b wxTHREAD_JOINABLE

-        
-        
+

         Creates a joinable thread.
     */
     wxThread(wxThreadKind kind = wxTHREAD_DETACHED);
         Creates a joinable thread.
     */
     wxThread(wxThreadKind kind = wxTHREAD_DETACHED);


@@ -369,7 +356,6 @@ public:
         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.
         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.
         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.


@@ -384,7 +370,6 @@ public:
         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.
         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.

-        

         @b 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
         @b 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


@@ -396,7 +381,7 @@ public:
         use a lot of threads (say several hundred), virtual adress space can get tight
         unless you explicitly specify a smaller amount of thread stack space for each
         thread.
         use a lot of threads (say several hundred), virtual adress space can get tight
         unless you explicitly specify a smaller amount of thread stack space for each
         thread.

-        
+

         @returns One of:
     */
     wxThreadError Create(unsigned int stackSize = 0);
         @returns One of:
     */
     wxThreadError Create(unsigned int stackSize = 0);


@@ -405,11 +390,9 @@ public:
         Calling Delete() gracefully terminates a
         detached thread, either when the thread calls TestDestroy() or finished
         processing.
         Calling Delete() gracefully terminates a
         detached thread, either when the thread calls TestDestroy() or finished
         processing.

-        

         (Note that 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).
         (Note that 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).

-        

         See @ref overview_deletionwxthread "wxThread deletion" for a broader
         explanation of this routine.
     */
         See @ref overview_deletionwxthread "wxThread deletion" for a broader
         explanation of this routine.
     */


@@ -422,16 +405,15 @@ public:
         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.
         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.
         Usually you only need to notify the main thread, in which case you can post
         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
+        an event to it via wxPostEvent() or

         wxEvtHandler::AddPendingEvent. 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
         wxEvtHandler::AddPendingEvent. 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 and/or other
+        of a variable, possibly using mutexes() and/or other

         synchronization means if necessary.
     */
 
         synchronization means if necessary.
     */
 


@@ -439,10 +421,8 @@ public:
     /**
         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.
     /**
         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().
         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.
     */
         This function is called by wxWidgets itself and should never be called
         directly.
     */


@@ -452,7 +432,6 @@ public:
         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 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.
         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.


@@ -461,8 +440,8 @@ 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.

-        
-        @sa SetConcurrency()
+
+        @see SetConcurrency()

     */
     static int GetCPUCount();
 
     */
     static int GetCPUCount();
 


@@ -479,47 +458,41 @@ public:
         thread throughout the system during its existence (i.e. the thread identifiers
         may be reused).
     */
         thread throughout the system during its existence (i.e. the thread identifiers
         may be reused).
     */

-    unsigned long GetId();
+    unsigned long GetId() const;

 
     /**
         Gets the priority of the thread, between zero and 100.
 
     /**
         Gets the priority of the thread, between zero and 100.

-        

         The following priorities are defined:
         The following priorities are defined:

-        
-        
+

         @b WXTHREAD_MIN_PRIORITY
         @b WXTHREAD_MIN_PRIORITY

-        
-        
+

         0
         0

-        
+

         @b WXTHREAD_DEFAULT_PRIORITY
         @b WXTHREAD_DEFAULT_PRIORITY

-        
-        
+

         50
         50

-        
+

         @b WXTHREAD_MAX_PRIORITY
         @b WXTHREAD_MAX_PRIORITY

-        
-        
+

         100
     */
         100
     */

-    int GetPriority();
+    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
         no longer alive, it is not possible to call this function because
         the wxThread object no longer exists.
     */
         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 IsAlive();
+    bool IsAlive() const;

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

-    bool IsDetached();
+    bool IsDetached() const;

 
     /**
         Returns @true if the calling thread is the main application thread.
 
     /**
         Returns @true if the calling thread is the main application thread.


@@ -529,15 +502,14 @@ public:
     /**
         Returns @true if the thread is paused.
     */
     /**
         Returns @true if the thread is paused.
     */

-    bool IsPaused();
+    bool IsPaused() const;

 
     /**
         Returns @true if the thread is running.
 
     /**
         Returns @true if the thread is running.

-        

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

-    bool IsRunning();
+    bool IsRunning() const;

 
     /**
         Immediately terminates the target thread. @b This function is dangerous and
 
     /**
         Immediately terminates the target thread. @b This function is dangerous and


@@ -546,16 +518,13 @@ public:
         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.
         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.
         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.
         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 @c wxTHREAD_NOT_RUNNING error will be returned.
         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 @c wxTHREAD_NOT_RUNNING error will be returned.


@@ -567,7 +536,6 @@ public:
         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.
         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.
     */
     void OnExit();
         This function should never be called directly.
     */
     void OnExit();


@@ -577,14 +545,12 @@ public:
         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).
         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 Pause();
 
     /**
         Resumes a thread suspended by the call to Pause().
         This function can only be called from another thread context.
     */
     wxThreadError Pause();
 
     /**
         Resumes a thread suspended by the call to Pause().

-        

         This function can only be called from another thread context.
     */
     wxThreadError Resume();
         This function can only be called from another thread context.
     */
     wxThreadError Resume();


@@ -592,16 +558,14 @@ public:
     /**
         Starts the thread execution. Should be called after
         Create().
     /**
         Starts the thread execution. Should be called after
         Create().

-        

         This function can only be called from another thread context.
     */
         This function can only be called from another thread context.
     */

-#define wxThreadError Run()     /* implementation is private */
+    wxThreadError Run();

 
     /**
         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.
 
     /**
         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 @e level may be used to set the default one.
-        
+        The value of 0 for @a 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).
     */
         Returns @true on success or @false otherwise (for example, if this function is
         not implemented for this platform -- currently everything except Solaris).
     */


@@ -611,31 +575,25 @@ public:
         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 and 100. It can only be set
         after calling Create() but before calling
         Run().

-        

         The following priorities are already defined:
         The following priorities are already defined:

-        
-        
+

         @b WXTHREAD_MIN_PRIORITY
         @b WXTHREAD_MIN_PRIORITY

-        
-        
+

         0
         0

-        
+

         @b WXTHREAD_DEFAULT_PRIORITY
         @b WXTHREAD_DEFAULT_PRIORITY

-        
-        
+

         50
         50

-        
+

         @b WXTHREAD_MAX_PRIORITY
         @b WXTHREAD_MAX_PRIORITY

-        
-        
+

         100
     */
     void SetPriority(int priority);
 
     /**
         Pauses the thread execution for the given amount of time.
         100
     */
     void SetPriority(int priority);
 
     /**
         Pauses the thread execution for the given amount of time.

-        
-        This function should be used instead of wxSleep by all worker
+        This function should be used instead of wxSleep() by all worker

         threads (i.e. all except the main one).
     */
     static void Sleep(unsigned long milliseconds);
         threads (i.e. all except the main one).
     */
     static void Sleep(unsigned long milliseconds);


@@ -644,7 +602,6 @@ public:
         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.
         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.
         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.


@@ -661,13 +618,12 @@ public:
         a thread
         is undefined.
     */
         a thread
         is undefined.
     */

-    static wxThread * This();
+    static wxThread* This();

 
     /**
         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
         where all threads are joinable.
 
     /**
         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
         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
         By default wxThreads in wxWidgets use the detached behavior. Detached threads
         delete themselves once they have completed, either by themselves when they
         complete


@@ -679,7 +635,6 @@ public:
         are safe to create on the stack. Joinable threads also provide the ability
         for one to get value it returned from Entry()
         through Wait().
         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
         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


@@ -697,15 +652,12 @@ public:
         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.
         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.

-        

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

-        

         This function can only be called from another thread context.
         This function can only be called from another thread context.

-        

         See @ref overview_deletionwxthread "wxThread deletion" for a broader
         explanation of this routine.
     */
         See @ref overview_deletionwxthread "wxThread deletion" for a broader
         explanation of this routine.
     */

-    ExitCode Wait();
+    ExitCode Wait() const;

 
     /**
         Give the rest of the thread time slice to the system allowing the other threads
 
     /**
         Give the rest of the thread time slice to the system allowing the other threads


@@ -744,7 +696,6 @@ public:
         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.
         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
         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


@@ -752,17 +703,14 @@ public:
         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.
         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 from wxThread::Entry).
         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 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 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.

-        

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


@@ -776,17 +724,15 @@ public:
         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.
         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.

-        

         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.
         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 that works on some wxWidgets ports is calling wxMutexGUIEnter
-        before any GUI calls and then calling wxMutexGUILeave afterwords. However,
+        A workaround that works on 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
         the recommended way is to simply process the GUI calls in the main thread

-        through an event that is posted by either wxPostEvent or
+        through an event that is posted by either wxPostEvent() or

         wxEvtHandler::AddPendingEvent. This does
         not imply that calls to these classes are thread-safe, however, as most
         wxWidgets classes are not thread-safe, including wxString.
         wxEvtHandler::AddPendingEvent. This does
         not imply that calls to these classes are thread-safe, however, as most
         wxWidgets classes are not thread-safe, including wxString.


@@ -794,6 +740,7 @@ public:
 };
 
 
 };
 
 

+

 /**
     @class wxSemaphore
     @wxheader{thread.h}
 /**
     @class wxSemaphore
     @wxheader{thread.h}


@@ -822,13 +769,12 @@ class wxSemaphore
 {
 public:
     /**
 {
 public:
     /**

-        Specifying a @e maxcount of 0 actually makes wxSemaphore behave as if
+        Specifying a @a maxcount of 0 actually makes wxSemaphore behave as if

         there is no upper limit. If maxcount is 1, the semaphore behaves almost as a
         mutex (but unlike a mutex it can be released by a thread different from the one
         which acquired it).
         there is no upper limit. If maxcount is 1, the semaphore behaves almost as a
         mutex (but unlike a mutex it can be released by a thread different from the one
         which acquired it).

-        
-        @e initialcount is the initial value of the semaphore which must be between
-        0 and @e maxcount (if it is not set to 0).
+        @a initialcount is the initial value of the semaphore which must be between
+        0 and @a maxcount (if it is not set to 0).

     */
     wxSemaphore(int initialcount = 0, int maxcount = 0);
 
     */
     wxSemaphore(int initialcount = 0, int maxcount = 0);
 


@@ -841,14 +787,14 @@ public:
         Increments the semaphore count and signals one of the waiting
         threads in an atomic way. Returns wxSEMA_OVERFLOW if the count
         would increase the counter past the maximum.
         Increments the semaphore count and signals one of the waiting
         threads in an atomic way. Returns wxSEMA_OVERFLOW if the count
         would increase the counter past the maximum.

-        
+

         @returns One of:
     */
     wxSemaError Post();
 
     /**
         Same as Wait(), but returns immediately.
         @returns One of:
     */
     wxSemaError Post();
 
     /**
         Same as Wait(), but returns immediately.

-        
+

         @returns One of:
     */
     wxSemaError TryWait();
         @returns One of:
     */
     wxSemaError TryWait();


@@ -856,13 +802,14 @@ public:
     /**
         Wait indefinitely until the semaphore count becomes strictly positive
         and then decrement it and return.
     /**
         Wait indefinitely until the semaphore count becomes strictly positive
         and then decrement it and return.

-        
+

         @returns One of:
     */
     wxSemaError Wait();
 };
 
 
         @returns One of:
     */
     wxSemaError Wait();
 };
 
 

+

 /**
     @class wxMutexLocker
     @wxheader{thread.h}
 /**
     @class wxMutexLocker
     @wxheader{thread.h}


@@ -877,8 +824,7 @@ public:
     @library{wxbase}
     @category{thread}
 
     @library{wxbase}
     @category{thread}
 

-    @seealso
-    wxMutex, wxCriticalSectionLocker
+    @see wxMutex, wxCriticalSectionLocker

 */
 class wxMutexLocker
 {
 */
 class wxMutexLocker
 {


@@ -898,10 +844,11 @@ public:
     /**
         Returns @true if mutex was acquired in the constructor, @false otherwise.
     */
     /**
         Returns @true if mutex was acquired in the constructor, @false otherwise.
     */

-#define bool IsOk()     /* implementation is private */
+    bool IsOk() const;

 };
 
 
 };
 
 

+

 /**
     @class wxMutex
     @wxheader{thread.h}
 /**
     @class wxMutex
     @wxheader{thread.h}


@@ -928,8 +875,7 @@ public:
     @library{wxbase}
     @category{thread}
 
     @library{wxbase}
     @category{thread}
 

-    @seealso
-    wxThread, wxCondition, wxMutexLocker, wxCriticalSection
+    @see wxThread, wxCondition, wxMutexLocker, wxCriticalSection

 */
 class wxMutex
 {
 */
 class wxMutex
 {


@@ -947,49 +893,75 @@ 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.

-        
+

         @returns One of:
     */
     wxMutexError Lock();
 
     /**
         Try to lock the mutex object during the specified time interval.
         @returns One of:
     */
     wxMutexError Lock();
 
     /**
         Try to lock the mutex object during the specified time interval.

-        
+

         @returns One of:
     */
     wxMutexError LockTimeout(unsigned long msec);
 
     /**
         Tries to lock the mutex object. If it can't, returns immediately with an error.
         @returns One of:
     */
     wxMutexError LockTimeout(unsigned long msec);
 
     /**
         Tries to lock the mutex object. If it can't, returns immediately with an error.

-        
+

         @returns One of:
     */
     wxMutexError TryLock();
 
     /**
         Unlocks the mutex object.
         @returns One of:
     */
     wxMutexError TryLock();
 
     /**
         Unlocks the mutex object.

-        
+

         @returns One of:
     */
     wxMutexError Unlock();
 };
 
 
         @returns One of:
     */
     wxMutexError Unlock();
 };
 
 

+

 // ============================================================================
 // Global functions/macros
 // ============================================================================
 
 // ============================================================================
 // Global functions/macros
 // ============================================================================
 

+/** @ingroup group_funcmacro_thread */
+//@{
+

 /**
 /**

-    Returns @true if this thread is the main one. Always returns @true if
-    @c wxUSE_THREADS is 0.
+    This macro declares a (static) critical section object named @a cs if
+    @c wxUSE_THREADS is 1 and does nothing if it is 0.
+
+    @header{wx/thread.h}

 */
 */

-bool wxIsMainThread();
+#define wxCRIT_SECT_DECLARE(cs)
+
+/**
+    This macro declares a critical section object named @a cs if
+    @c wxUSE_THREADS is 1 and does nothing if it is 0. As it doesn't include
+    the @c static keyword (unlike wxCRIT_SECT_DECLARE()), it can be used to
+    declare a class or struct member which explains its name.
+
+    @header{wx/thread.h}
+*/
+#define wxCRIT_SECT_DECLARE_MEMBER(cs)

 
 /**
 
 /**

-    This macro combines wxCRIT_SECT_DECLARE and
-    wxCRIT_SECT_LOCKER: it creates a static critical
-    section object and also the lock object associated with it. Because of this, it
-    can be only used inside a function, not at global scope. For example:
+    This macro creates a wxCriticalSectionLocker named @a name and associated
+    with the critical section @a cs if @c wxUSE_THREADS is 1 and does nothing
+    if it is 0.
+
+    @header{wx/thread.h}
+*/
+#define wxCRIT_SECT_LOCKER(name, cs)
+
+/**
+    This macro combines wxCRIT_SECT_DECLARE() and wxCRIT_SECT_LOCKER(): it
+    creates a static critical section object and also the lock object
+    associated with it. Because of this, it can be only used inside a function,
+    not at global scope. For example:
+

     @code
     int IncCount()
     {
     @code
     int IncCount()
     {


@@ -1001,35 +973,56 @@ bool wxIsMainThread();
     }
     @endcode
 
     }
     @endcode
 

-    (note that we suppose that the function is called the first time from the main
-    thread so that the critical section object is initialized correctly by the time
-    other threads start calling it, if this is not the case this approach can
-    @b not be used and the critical section must be made a global instead).
+    Note that this example assumes that the function is called the first time
+    from the main thread so that the critical section object is initialized
+    correctly by the time other threads start calling it, if this is not the
+    case this approach can @b not be used and the critical section must be made
+    a global instead.
+
+    @header{wx/thread.h}
+*/
+#define wxCRITICAL_SECTION(name)
+
+/**
+    This macro is equivalent to
+    @ref wxCriticalSection::Leave "critical_section.Leave()" if
+    @c wxUSE_THREADS is 1 and does nothing if it is 0.
+
+    @header{wx/thread.h}
+*/
+#define wxLEAVE_CRIT_SECT(critical_section)
+
+/**
+    This macro is equivalent to
+    @ref wxCriticalSection::Enter "critical_section.Enter()" if
+    @c wxUSE_THREADS is 1 and does nothing if it is 0.
+
+    @header{wx/thread.h}

 */
 */

-#define wxCRITICAL_SECTION(name)     /* implementation is private */
+#define wxENTER_CRIT_SECT(critical_section)

 
 /**
 
 /**

-    This macro declares a critical section object named @e cs if
-    @c wxUSE_THREADS is 1 and does nothing if it is 0. As it doesn't
-    include the @c static keyword (unlike
-    wxCRIT_SECT_DECLARE), it can be used to declare
-    a class or struct member which explains its name.
+    Returns @true if this thread is the main one. Always returns @true if
+    @c wxUSE_THREADS is 0.
+
+    @header{wx/thread.h}

 */
 */

-#define wxCRIT_SECT_DECLARE(cs)     /* implementation is private */
+bool wxIsMainThread();

 
 /**
     This function must be called when any thread other than the main GUI thread
 
 /**
     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 execution
-    of the calling thread until the main thread (or any other thread holding the
-    main GUI lock) leaves the GUI library and no other thread will enter the GUI
-    library until the calling thread calls ::wxMutexGuiLeave.
+    wants to get access to the GUI library. This function will block the
+    execution of the calling thread until the main thread (or any other thread
+    holding the main GUI lock) leaves the GUI library and no other thread will
+    enter the GUI library until the calling thread calls wxMutexGuiLeave().

 
     Typically, these functions are used like this:
 
     Typically, these functions are used like this:

+

     @code
     void MyThread::Foo(void)
     {
     @code
     void MyThread::Foo(void)
     {

-        // before doing any GUI calls we must ensure that this thread is the only
-        // one doing it!
+        // before doing any GUI calls we must ensure that
+        // this thread is the only one doing it!

 
         wxMutexGuiEnter();
 
 
         wxMutexGuiEnter();
 


@@ -1040,37 +1033,25 @@ bool wxIsMainThread();
     }
     @endcode
 
     }
     @endcode
 

-    Note that under GTK, no creation of top-level windows is allowed in any
-    thread but the main one.
-

     This function is only defined on platforms which support preemptive
     threads.
     This function is only defined on platforms which support preemptive
     threads.

+
+    @note Under GTK, no creation of top-level windows is allowed in any thread
+          but the main one.
+
+    @header{wx/thread.h}

 */
 void wxMutexGuiEnter();
 
 /**
 */
 void wxMutexGuiEnter();
 
 /**

-    This macro declares a (static) critical section object named @e cs if
-    @c wxUSE_THREADS is 1 and does nothing if it is 0.
-*/
-#define wxCRIT_SECT_DECLARE(cs)     /* implementation is private */
+    This function is only defined on platforms which support preemptive
+    threads.

 
 

-/**
-    This macro is equivalent to @ref wxCriticalSection::leave cs.Leave if
-    @c wxUSE_THREADS is 1 and does nothing if it is 0.
-*/
-#define wxLEAVE_CRIT_SECT(wxCriticalSection& cs)     /* implementation is private */
+    @see wxMutexGuiEnter()

 
 

-/**
-    This macro creates a @ref overview_wxcriticalsectionlocker "critical section
-    lock"
-    object named @e name and associated with the critical section @e cs if
-    @c wxUSE_THREADS is 1 and does nothing if it is 0.
+    @header{wx/thread.h}

 */
 */

-#define wxCRIT_SECT_LOCKER(name,  cs)     /* implementation is private */
+void wxMutexGuiLeave();

 
 

-/**
-    This macro is equivalent to @ref wxCriticalSection::enter cs.Enter if
-    @c wxUSE_THREADS is 1 and does nothing if it is 0.
-*/
-#define wxENTER_CRIT_SECT(wxCriticalSection& cs)     /* implementation is private */
+//@}