fix signature of wxClipboard::UserPrimarySelection; in particular change the default...

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

diff --git a/interface/wx/thread.h b/interface/wx/thread.h
index 2c47ea1fdbb85e2fb498c7cc14d944810d4cbc09..0e83c26d40ddeb2b14bd5e6b98f599348bffa6e9 100644 (file)
--- a/interface/wx/thread.h
+++ b/interface/wx/thread.h
@@ -8,7 +8,6 @@
 
 /**
     @class wxCondition
 
 /**
     @class wxCondition

-    @wxheader{thread.h}

 
     wxCondition variables correspond to pthread conditions or to Win32 event
     objects. They may be used in a multithreaded application to wait until the
 
     wxCondition variables correspond to pthread conditions or to Win32 event
     objects. They may be used in a multithreaded application to wait until the


@@ -114,7 +113,6 @@ public:
 
 /**
     @class wxCriticalSectionLocker
 
 /**
     @class wxCriticalSectionLocker

-    @wxheader{thread.h}

 
     This is a small helper class to be used with wxCriticalSection
     objects. A wxCriticalSectionLocker enters the critical section in the
 
     This is a small helper class to be used with wxCriticalSection
     objects. A wxCriticalSectionLocker enters the critical section in the


@@ -173,7 +171,6 @@ public:
 
 /**
     @class wxThreadHelper
 
 /**
     @class wxThreadHelper

-    @wxheader{thread.h}

 
     The wxThreadHelper class is a mix-in class that manages a single background
     thread.  By deriving from wxThreadHelper, a class can implement the thread
 
     The wxThreadHelper class is a mix-in class that manages a single background
     thread.  By deriving from wxThreadHelper, a class can implement the thread


@@ -253,25 +250,33 @@ public:
     */
 };
 
     */
 };
 

+/**
+   Possible critical section types
+*/

 
 

+enum wxCriticalSectionType
+{
+    wxCRITSEC_DEFAULT,
+      /** Recursive critical section under both Windows and Unix */
+
+    wxCRITSEC_NON_RECURSIVE  
+      /** Non-recursive critical section under Unix, recursive under Windows */
+};

 
 /**
     @class wxCriticalSection
 
 /**
     @class wxCriticalSection

-    @wxheader{thread.h}

 
     A critical section object is used for exactly the same purpose as
 
     A critical section object is used for exactly the same purpose as

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

     critical sections are only visible inside one process, while mutexes may be
     shared among processes, so using critical sections is slightly more
     critical sections are only visible inside one process, while mutexes may be
     shared among processes, so using critical sections is slightly more

-    efficient. The terminology is also slightly different: mutex may be locked (or
-    acquired) and unlocked (or released) while critical section is entered and left
-    by the program.
+    efficient. The terminology is also slightly different: mutex may be locked
+    (or acquired) and unlocked (or released) while critical section is entered
+    and left by the program.

 
 

-    Finally, you should try to use
-    wxCriticalSectionLocker class whenever
+    Finally, you should try to use wxCriticalSectionLocker class whenever

     possible instead of directly using wxCriticalSection for the same reasons
     possible instead of directly using wxCriticalSection for the same reasons

-    wxMutexLocker is preferrable to
-    wxMutex - please see wxMutex for an example.
+    wxMutexLocker is preferrable to wxMutex - please see wxMutex for an example.

 
     @library{wxbase}
     @category{threading}
 
     @library{wxbase}
     @category{threading}


@@ -282,9 +287,10 @@ class wxCriticalSection
 {
 public:
     /**
 {
 public:
     /**

-        Default constructor initializes critical section object.
+        Default constructor initializes critical section object. By default
+        critical sections are recursive under Unix and Windows.

     */
     */

-    wxCriticalSection();
+    wxCriticalSection( wxCriticalSectionType critSecType = wxCRITSEC_DEFAULT );

 
     /**
         Destructor frees the resources.
 
     /**
         Destructor frees the resources.


@@ -305,11 +311,55 @@ public:
     void Leave();
 };
 
     void Leave();
 };
 

+/**
+  The possible thread kinds.
+*/
+enum wxThreadKind
+{
+    /** Detached thread */
+    wxTHREAD_DETACHED,  
+    
+    /** Joinable thread */
+    wxTHREAD_JOINABLE   
+};
+
+/**
+  The possible thread errors.
+*/
+enum wxThreadError
+{
+    /** No error */
+    wxTHREAD_NO_ERROR = 0,      
+    
+    /** No resource left to create a new thread. */
+    wxTHREAD_NO_RESOURCE,       
+    
+    /** The thread is already running. */
+    wxTHREAD_RUNNING,          
+    
+    /** The thread isn't running. */ 
+    wxTHREAD_NOT_RUNNING,       
+    
+    /** Thread we waited for had to be killed. */
+    wxTHREAD_KILLED,            
+    
+    /** Some other error */
+    wxTHREAD_MISC_ERROR         
+};
+
+/**
+   Defines the interval of priority
+*/
+enum
+{
+    WXTHREAD_MIN_PRIORITY      = 0u,
+    WXTHREAD_DEFAULT_PRIORITY  = 50u,
+    WXTHREAD_MAX_PRIORITY      = 100u
+};

 
 
 /**
     @class wxThread
 
 
 /**
     @class wxThread

-    @wxheader{thread.h}

 
     A thread is basically a path of execution through a program. Threads are
     sometimes called @e light-weight processes, but the fundamental difference
 
     A thread is basically a path of execution through a program. Threads are
     sometimes called @e light-weight processes, but the fundamental difference


@@ -703,7 +753,6 @@ public:
 
 /**
     @class wxSemaphore
 
 /**
     @class wxSemaphore

-    @wxheader{thread.h}

 
     wxSemaphore is a counter limiting the number of threads concurrently accessing
     a shared resource. This counter is always between 0 and the maximum value
 
     wxSemaphore is a counter limiting the number of threads concurrently accessing
     a shared resource. This counter is always between 0 and the maximum value


@@ -772,7 +821,6 @@ public:
 
 /**
     @class wxMutexLocker
 
 /**
     @class wxMutexLocker

-    @wxheader{thread.h}

 
     This is a small helper class to be used with wxMutex
     objects. A wxMutexLocker acquires a mutex lock in the constructor and releases
 
     This is a small helper class to be used with wxMutex
     objects. A wxMutexLocker acquires a mutex lock in the constructor and releases


@@ -791,8 +839,7 @@ class wxMutexLocker
 public:
     /**
         Constructs a wxMutexLocker object associated with mutex and locks it.
 public:
     /**
         Constructs a wxMutexLocker object associated with mutex and locks it.

-        Call @ref IsOk() IsLocked to check if the mutex was
-        successfully locked.
+        Call IsOk() to check if the mutex was successfully locked.

     */
     wxMutexLocker(wxMutex& mutex);
 
     */
     wxMutexLocker(wxMutex& mutex);
 


@@ -808,10 +855,50 @@ public:
 };
 
 
 };
 
 

+/**
+    The possible wxMutex kinds.
+*/
+enum wxMutexType
+{
+    /** Normal non-recursive mutex: try to always use this one. */
+    wxMUTEX_DEFAULT,   
+
+    /** Recursive mutex: don't use these ones with wxCondition. */
+    wxMUTEX_RECURSIVE  
+};
+
+
+/**
+    The possible wxMutex errors.
+*/
+enum wxMutexError
+{
+    /** The operation completed successfully. */
+    wxMUTEX_NO_ERROR = 0,   
+    
+    /** The mutex hasn't been initialized. */
+    wxMUTEX_INVALID,       
+    
+     /** The mutex is already locked by the calling thread. */ 
+    wxMUTEX_DEAD_LOCK,     
+    
+    /** The mutex is already locked by another thread. */
+    wxMUTEX_BUSY,           
+    
+    /** An attempt to unlock a mutex which is not locked. */
+    wxMUTEX_UNLOCKED,       
+    
+    /** wxMutex::LockTimeout() has timed out. */
+    wxMUTEX_TIMEOUT,        
+    
+    /** Any other error */
+    wxMUTEX_MISC_ERROR      
+};
+
+

 
 /**
     @class wxMutex
 
 /**
     @class wxMutex

-    @wxheader{thread.h}

 
     A mutex object is a synchronization object whose state is set to signaled when
     it is not owned by any thread, and nonsignaled when it is owned. Its name comes
 
     A mutex object is a synchronization object whose state is set to signaled when
     it is not owned by any thread, and nonsignaled when it is owned. Its name comes


@@ -822,16 +909,58 @@ public:
     had already locked before (instead of dead locking the entire process in this
     situation by starting to wait on a mutex which will never be released while the
     thread is waiting) but using them is not recommended under Unix and they are
     had already locked before (instead of dead locking the entire process in this
     situation by starting to wait on a mutex which will never be released while the
     thread is waiting) but using them is not recommended under Unix and they are

-    @b not recursive there by default. The reason for this is that recursive
+    @b not recursive by default. The reason for this is that recursive

     mutexes are not supported by all Unix flavours and, worse, they cannot be used
     mutexes are not supported by all Unix flavours and, worse, they cannot be used

-    with wxCondition. On the other hand, Win32 mutexes are
-    always recursive.
+    with wxCondition.

 
     For example, when several threads use the data stored in the linked list,
     modifications to the list should only be allowed to one thread at a time
     because during a new node addition the list integrity is temporarily broken
     (this is also called @e program invariant).
 
 
     For example, when several threads use the data stored in the linked list,
     modifications to the list should only be allowed to one thread at a time
     because during a new node addition the list integrity is temporarily broken
     (this is also called @e program invariant).
 

+    @code
+    // this variable has an "s_" prefix because it is static: seeing an "s_" in
+    // a multithreaded program is in general a good sign that you should use a
+    // mutex (or a critical section)
+    static wxMutex *s_mutexProtectingTheGlobalData;
+
+    // we store some numbers in this global array which is presumably used by
+    // several threads simultaneously
+    wxArrayInt s_data;
+
+    void MyThread::AddNewNode(int num)
+    {
+        // ensure that no other thread accesses the list
+        s_mutexProtectingTheGlobalList->Lock();
+
+        s_data.Add(num);
+
+        s_mutexProtectingTheGlobalList->Unlock();
+    }
+
+    // return true if the given number is greater than all array elements
+    bool MyThread::IsGreater(int num)
+    {
+        // before using the list we must acquire the mutex
+        wxMutexLocker lock(s_mutexProtectingTheGlobalData);
+
+        size_t count = s_data.Count();
+        for ( size_t n = 0; n < count; n++ )
+        {
+            if ( s_data[n] > num )
+                return false;
+        }
+
+        return true;
+    }
+    @endcode
+
+    Notice how wxMutexLocker was used in the second function to ensure that the
+    mutex is unlocked in any case: whether the function returns true or false
+    (because the destructor of the local object lock is always called). Using
+    this class instead of directly using wxMutex is, in general safer and is
+    even more so if your program uses C++ exceptions.
+

     @library{wxbase}
     @category{threading}
 
     @library{wxbase}
     @category{threading}
 


@@ -854,28 +983,28 @@ 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.
 

-        @return One of:
+        @return One of: @c wxMUTEX_NO_ERROR, @c wxMUTEX_DEAD_LOCK.

     */
     wxMutexError Lock();
 
     /**
         Try to lock the mutex object during the specified time interval.
 
     */
     wxMutexError Lock();
 
     /**
         Try to lock the mutex object during the specified time interval.
 

-        @return One of:
+        @return One of: @c wxMUTEX_NO_ERROR, @c wxMUTEX_DEAD_LOCK, @c wxMUTEX_TIMEOUT.

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

-        @return One of:
+        @return One of: @c wxMUTEX_NO_ERROR, @c wxMUTEX_BUSY.

     */
     wxMutexError TryLock();
 
     /**
         Unlocks the mutex object.
 
     */
     wxMutexError TryLock();
 
     /**
         Unlocks the mutex object.
 

-        @return One of:
+        @return One of: @c wxMUTEX_NO_ERROR, @c wxMUTEX_UNLOCKED.

     */
     wxMutexError Unlock();
 };
     */
     wxMutexError Unlock();
 };