]> git.saurik.com Git - wxWidgets.git/blobdiff - interface/thread.h
use wx-style header and commets; fix indentation to be 4 spaces; move Doxygen comment...
[wxWidgets.git] / interface / thread.h
index bfd661a200b659c5c9f5b826b5a8e8e6a53a71db..4d086f25700340d06f40f424c821c0f15b578b21 100644 (file)
@@ -1,6 +1,6 @@
 /////////////////////////////////////////////////////////////////////////////
 // Name:        thread.h
-// Purpose:     documentation for wxCondition class
+// Purpose:     interface of wxCondition
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Licence:     wxWindows license
@@ -33,8 +33,7 @@
     @library{wxbase}
     @category{thread}
 
-    @seealso
-    wxThread, wxMutex
+    @see wxThread, wxMutex
 */
 class wxCondition
 {
@@ -57,7 +56,7 @@ 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.
-        
+
         @see Signal()
     */
     void Broadcast();
@@ -66,7 +65,7 @@ public:
         Returns @true if the object had been initialized successfully, @false
         if an error occurred.
     */
-    bool IsOk();
+    bool IsOk() const;
 
     /**
         Signals the object waking up at most one thread. If several threads are waiting
@@ -75,7 +74,7 @@ public:
         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.
-        
+
         @see Broadcast()
     */
     void Signal();
@@ -91,10 +90,10 @@ public:
         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
                  occurred.
-        
+
         @see WaitTimeout()
     */
     wxCondError Wait();
@@ -104,7 +103,7 @@ public:
         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
             Timeout in milliseconds
     */
@@ -112,6 +111,7 @@ public:
 };
 
 
+
 /**
     @class wxCriticalSectionLocker
     @wxheader{thread.h}
@@ -152,8 +152,7 @@ public:
     @library{wxbase}
     @category{thread}
 
-    @seealso
-    wxCriticalSection, wxMutexLocker
+    @see wxCriticalSection, wxMutexLocker
 */
 class wxCriticalSectionLocker
 {
@@ -171,6 +170,7 @@ public:
 };
 
 
+
 /**
     @class wxThreadHelper
     @wxheader{thread.h}
@@ -204,8 +204,7 @@ public:
     @library{wxbase}
     @category{thread}
 
-    @seealso
-    wxThread
+    @see wxThread
 */
 class wxThreadHelper
 {
@@ -226,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).
-        
+
         @returns One of:
     */
     wxThreadError Create(unsigned int stackSize = 0);
@@ -255,12 +254,13 @@ public:
 };
 
 
+
 /**
     @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
@@ -276,8 +276,7 @@ public:
     @library{wxbase}
     @category{thread}
 
-    @seealso
-    wxThread, wxCondition, wxCriticalSectionLocker
+    @see wxThread, wxCondition, wxCriticalSectionLocker
 */
 class wxCriticalSection
 {
@@ -307,6 +306,7 @@ public:
 };
 
 
+
 /**
     @class wxThread
     @wxheader{thread.h}
@@ -320,16 +320,15 @@ public:
     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}
 
-    @seealso
-    wxMutex, wxCondition, wxCriticalSection
+    @see wxMutex, wxCondition, wxCriticalSection
 */
 class wxThread
 {
@@ -340,13 +339,13 @@ public:
         does not create or start execution of the real thread -- for this you should
         use the Create() and Run() methods.
         The possible values for @a kind parameters are:
-        
+
         @b wxTHREAD_DETACHED
-        
+
         Creates a detached thread.
-        
+
         @b wxTHREAD_JOINABLE
-        
+
         Creates a joinable thread.
     */
     wxThread(wxThreadKind kind = wxTHREAD_DETACHED);
@@ -382,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.
-        
+
         @returns One of:
     */
     wxThreadError Create(unsigned int stackSize = 0);
@@ -410,11 +409,11 @@ public:
         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
-        of a variable, possibly using mutexes and/or other
+        of a variable, possibly using mutexes() and/or other
         synchronization means if necessary.
     */
 
@@ -441,7 +440,7 @@ public:
 
     /**
         Returns the number of system CPUs or -1 if the value is unknown.
-        
+
         @see SetConcurrency()
     */
     static int GetCPUCount();
@@ -459,25 +458,25 @@ public:
         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.
         The following priorities are defined:
-        
+
         @b WXTHREAD_MIN_PRIORITY
-        
+
         0
-        
+
         @b WXTHREAD_DEFAULT_PRIORITY
-        
+
         50
-        
+
         @b WXTHREAD_MAX_PRIORITY
-        
+
         100
     */
-    int GetPriority();
+    int GetPriority() const;
 
     /**
         Returns @true if the thread is alive (i.e. started and not terminating).
@@ -486,14 +485,14 @@ public:
         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.
     */
-    bool IsDetached();
+    bool IsDetached() const;
 
     /**
         Returns @true if the calling thread is the main application thread.
@@ -503,14 +502,14 @@ public:
     /**
         Returns @true if the thread is paused.
     */
-    bool IsPaused();
+    bool IsPaused() const;
 
     /**
         Returns @true if the thread is running.
         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
@@ -577,24 +576,24 @@ public:
         after calling Create() but before calling
         Run().
         The following priorities are already defined:
-        
+
         @b WXTHREAD_MIN_PRIORITY
-        
+
         0
-        
+
         @b WXTHREAD_DEFAULT_PRIORITY
-        
+
         50
-        
+
         @b WXTHREAD_MAX_PRIORITY
-        
+
         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);
@@ -658,7 +657,7 @@ public:
         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
@@ -730,10 +729,10 @@ public:
         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
-        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.
@@ -741,6 +740,7 @@ public:
 };
 
 
+
 /**
     @class wxSemaphore
     @wxheader{thread.h}
@@ -787,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.
-        
+
         @returns One of:
     */
     wxSemaError Post();
 
     /**
         Same as Wait(), but returns immediately.
-        
+
         @returns One of:
     */
     wxSemaError TryWait();
@@ -802,13 +802,14 @@ public:
     /**
         Wait indefinitely until the semaphore count becomes strictly positive
         and then decrement it and return.
-        
+
         @returns One of:
     */
     wxSemaError Wait();
 };
 
 
+
 /**
     @class wxMutexLocker
     @wxheader{thread.h}
@@ -823,8 +824,7 @@ public:
     @library{wxbase}
     @category{thread}
 
-    @seealso
-    wxMutex, wxCriticalSectionLocker
+    @see wxMutex, wxCriticalSectionLocker
 */
 class wxMutexLocker
 {
@@ -844,10 +844,11 @@ public:
     /**
         Returns @true if mutex was acquired in the constructor, @false otherwise.
     */
-    bool IsOk();
+    bool IsOk() const;
 };
 
 
+
 /**
     @class wxMutex
     @wxheader{thread.h}
@@ -874,8 +875,7 @@ public:
     @library{wxbase}
     @category{thread}
 
-    @seealso
-    wxThread, wxCondition, wxMutexLocker, wxCriticalSection
+    @see wxThread, wxCondition, wxMutexLocker, wxCriticalSection
 */
 class wxMutex
 {
@@ -893,34 +893,35 @@ public:
     /**
         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 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 Unlock();
 };
 
 
+
 // ============================================================================
 // Global functions/macros
 // ============================================================================
@@ -932,8 +933,8 @@ public:
 bool wxIsMainThread();
 
 /**
-    This macro combines wxCRIT_SECT_DECLARE and
-    wxCRIT_SECT_LOCKER: it creates a static critical
+    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:
 
@@ -959,7 +960,7 @@ bool wxIsMainThread();
     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
+    wxCRIT_SECT_DECLARE()), it can be used to declare
     a class or struct member which explains its name.
 */
 #define wxCRIT_SECT_DECLARE(cs)     /* implementation is private */