download_chunk(buffer, 1024); // this takes time...
{
- // ensure noone reads m_data while we write it
+ // ensure no one reads m_data while we write it
wxCriticalSectionLocker lock(m_dataCS);
memcpy(m_data+offset, buffer, 1024);
offset += 1024;
*/
virtual ExitCode Entry() = 0;
+ /**
+ Callback called by Delete() before actually deleting the thread.
+
+ This function can be overridden by the derived class to perform some
+ specific task when the thread is gracefully destroyed. Notice that it
+ will be executed in the context of the thread that called Delete() and
+ <b>not</b> in this thread's context.
+
+ TestDestroy() will be true for the thread before OnDelete() gets
+ executed.
+
+ @since 2.9.2
+
+ @see OnKill()
+ */
+ virtual void OnDelete();
+
+ /**
+ Callback called by Kill() before actually killing the thread.
+
+ This function can be overridden by the derived class to perform some
+ specific task when the thread is terminated. Notice that it will be
+ executed in the context of the thread that called Kill() and <b>not</b>
+ in this thread's context.
+
+ @since 2.9.2
+
+ @see OnDelete()
+ */
+ virtual void OnKill();
+
/**
@deprecated
Use CreateThread() instead.
Finally, you should try to use wxCriticalSectionLocker class whenever
possible instead of directly using wxCriticalSection for the same reasons
- wxMutexLocker is preferrable to wxMutex - please see wxMutex for an example.
+ wxMutexLocker is preferable to wxMutex - please see wxMutex for an example.
@library{wxbase}
@category{threading}
*/
void Enter();
+ /**
+ Try to enter the critical section (same as trying to lock a mutex).
+ If it can't, immediately returns false.
+
+ @since 2.9.3
+ */
+ bool TryEnter();
+
/**
Leave the critical section allowing other threads use the global data
protected by it. There is no error return for this function.
void Leave();
};
+/**
+ The possible thread wait types.
+
+ @since 2.9.2
+*/
+enum wxThreadWait
+{
+ /**
+ No events are processed while waiting.
+
+ This is the default under all platforms except for wxMSW.
+ */
+ wxTHREAD_WAIT_BLOCK,
+
+ /**
+ Yield for event dispatching while waiting.
+
+ This flag is dangerous as it exposes the program using it to unexpected
+ reentrancies in the same way as calling wxYield() function does so you
+ are strongly advised to avoid its use and not wait for the thread
+ termination from the main (GUI) thread at all to avoid making your
+ application unresponsive.
+
+ Also notice that this flag is not portable as it is only implemented in
+ wxMSW and simply ignored under the other platforms.
+ */
+ wxTHREAD_WAIT_YIELD,
+
+ /**
+ Default wait mode for wxThread::Wait() and wxThread::Delete().
+
+ For compatibility reasons, the default wait mode is currently
+ wxTHREAD_WAIT_YIELD if WXWIN_COMPATIBILITY_2_8 is defined (and it is
+ by default). However, as mentioned above, you're strongly encouraged to
+ not use wxTHREAD_WAIT_YIELD and pass wxTHREAD_WAIT_BLOCK to wxThread
+ method explicitly.
+ */
+ wxTHREAD_WAIT_DEFAULT = wxTHREAD_WAIT_YIELD
+};
+
/**
The possible thread kinds.
*/
wxTHREAD_MISC_ERROR
};
-/**
- Defines the interval of priority
-*/
-enum
-{
- WXTHREAD_MIN_PRIORITY = 0u,
- WXTHREAD_DEFAULT_PRIORITY = 50u,
- WXTHREAD_MAX_PRIORITY = 100u
-};
-
-
/**
@class wxThread
@section thread_types Types of wxThreads
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
+ modeled after the POSIX thread API. This is different from the Win32 API
where all threads are joinable.
- By default wxThreads in wxWidgets use the @b detached behavior.
+ By default wxThreads in wxWidgets use the @b detached behaviour.
Detached threads delete themselves once they have completed, either by themselves
when they complete processing or through a call to Delete(), and thus
@b must be created on the heap (through the new operator, for example).
A common problem users experience with wxThread is that in their main thread
they will check the thread every now and then to see if it has ended through
IsRunning(), only to find that their application has run into problems
- because the thread is using the default behavior (i.e. it's @b detached) and
+ because the thread is using the default behaviour (i.e. it's @b detached) 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
+ behaviour. 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.
performance issues on those systems with small default stack since those
typically use fully committed memory for the stack.
On the contrary, if you use a lot of threads (say several hundred),
- virtual adress space can get tight unless you explicitly specify a
+ virtual address space can get tight unless you explicitly specify a
smaller amount of thread stack space for each thread.
@return One of:
Calling Delete() gracefully terminates a @b detached thread, either when
the thread calls TestDestroy() or when it finishes processing.
+ @param rc
+ The thread exit code, if rc is not NULL.
+
+ @param waitMode
+ As described in wxThreadWait documentation, wxTHREAD_WAIT_BLOCK
+ should be used as the wait mode even although currently
+ wxTHREAD_WAIT_YIELD is for compatibility reasons. This parameter is
+ new in wxWidgets 2.9.2.
+
@note
This function works on a joinable thread but in that case makes
the TestDestroy() function of the thread return @true and then
See @ref thread_deletion for a broader explanation of this routine.
*/
- wxThreadError Delete(void** rc = NULL);
+ wxThreadError Delete(ExitCode *rc = NULL,
+ wxThreadWait waitMode = wxTHREAD_WAIT_BLOCK);
/**
Returns the number of system CPUs or -1 if the value is unknown.
/**
Gets the thread identifier: this is a platform dependent number that uniquely
identifies the thread throughout the system during its existence
- (i.e. the thread identifiers may be reused).
+ (i.e.\ the thread identifiers may be reused).
*/
wxThreadIdType GetId() const;
static wxThreadIdType GetMainId();
/**
- Gets the priority of the thread, between zero and 100.
+ Gets the priority of the thread, between 0 (lowest) and 100 (highest).
- The following priorities are defined:
- - @b WXTHREAD_MIN_PRIORITY: 0
- - @b WXTHREAD_DEFAULT_PRIORITY: 50
- - @b WXTHREAD_MAX_PRIORITY: 100
+ @see SetPriority()
*/
unsigned 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
static bool SetConcurrency(size_t level);
/**
- Sets the priority of the thread, between 0 and 100.
+ Sets the priority of the thread, between 0 (lowest) and 100 (highest).
+
It can only be set after calling Create() but before calling Run().
- The following priorities are defined:
- - @b WXTHREAD_MIN_PRIORITY: 0
- - @b WXTHREAD_DEFAULT_PRIORITY: 50
- - @b WXTHREAD_MAX_PRIORITY: 100
+ The following symbolic constants can be used in addition to raw
+ values in 0..100 range:
+ - ::wxPRIORITY_MIN: 0
+ - ::wxPRIORITY_DEFAULT: 50
+ - ::wxPRIORITY_MAX: 100
*/
void SetPriority(unsigned int priority);
This function can only be called from another thread context.
+ @param waitMode
+ As described in wxThreadWait documentation, wxTHREAD_WAIT_BLOCK
+ should be used as the wait mode even although currently
+ wxTHREAD_WAIT_YIELD is for compatibility reasons. This parameter is
+ new in wxWidgets 2.9.2.
+
See @ref thread_deletion for a broader explanation of this routine.
*/
- ExitCode Wait();
+ ExitCode Wait(wxThreadWait flags = wxTHREAD_WAIT_BLOCK);
/**
Give the rest of the thread's time-slice to the system allowing the other
projects / wxWidgets.git / blobdiff