1815 lines
62 KiB
Objective-C
1815 lines
62 KiB
Objective-C
/////////////////////////////////////////////////////////////////////////////
|
|
// Name: thread.h
|
|
// Purpose: interface of all thread-related wxWidgets classes
|
|
// Author: wxWidgets team
|
|
// Licence: wxWindows licence
|
|
/////////////////////////////////////////////////////////////////////////////
|
|
|
|
|
|
/** See wxCondition. */
|
|
enum wxCondError
|
|
{
|
|
wxCOND_NO_ERROR = 0,
|
|
wxCOND_INVALID,
|
|
wxCOND_TIMEOUT, //!< WaitTimeout() has timed out
|
|
wxCOND_MISC_ERROR
|
|
};
|
|
|
|
|
|
/**
|
|
@class wxCondition
|
|
|
|
wxCondition variables correspond to pthread conditions or to Win32 event objects.
|
|
They may be used in a multithreaded application to wait until the given condition
|
|
becomes @true which happens when the condition becomes signaled.
|
|
|
|
For example, if a worker thread is doing some long task and another thread has
|
|
to wait until it is finished, the latter thread will wait on the condition
|
|
object and the worker thread will signal it on exit (this example is not
|
|
perfect because in this particular case it would be much better to just
|
|
wxThread::Wait for the worker thread, but if there are several worker threads
|
|
it already makes much more sense).
|
|
|
|
Note that a call to wxCondition::Signal may happen before the other thread calls
|
|
wxCondition::Wait and, just as with the pthread conditions, the signal is then
|
|
lost and so if you want to be sure that you don't miss it you must keep the
|
|
mutex associated with the condition initially locked and lock it again before calling
|
|
wxCondition::Signal. Of course, this means that this call is going to block
|
|
until wxCondition::Wait is called by another thread.
|
|
|
|
@section condition_example Example
|
|
|
|
This example shows how a main thread may launch a worker thread which starts
|
|
running and then waits until the main thread signals it to continue:
|
|
|
|
@code
|
|
class MySignallingThread : public wxThread
|
|
{
|
|
public:
|
|
MySignallingThread(wxMutex *mutex, wxCondition *condition)
|
|
{
|
|
m_mutex = mutex;
|
|
m_condition = condition;
|
|
}
|
|
|
|
virtual ExitCode Entry()
|
|
{
|
|
... do our job ...
|
|
|
|
// tell the other(s) thread(s) that we're about to terminate: we must
|
|
// lock the mutex first or we might signal the condition before the
|
|
// waiting threads start waiting on it!
|
|
wxMutexLocker lock(*m_mutex);
|
|
m_condition->Broadcast(); // same as Signal() here -- one waiter only
|
|
|
|
return 0;
|
|
}
|
|
|
|
private:
|
|
wxCondition *m_condition;
|
|
wxMutex *m_mutex;
|
|
};
|
|
|
|
int main()
|
|
{
|
|
wxMutex mutex;
|
|
wxCondition condition(mutex);
|
|
|
|
// the mutex should be initially locked
|
|
mutex.Lock();
|
|
|
|
// create and run the thread but notice that it won't be able to
|
|
// exit (and signal its exit) before we unlock the mutex below
|
|
MySignallingThread *thread = new MySignallingThread(&mutex, &condition);
|
|
|
|
thread->Run();
|
|
|
|
// wait for the thread termination: Wait() atomically unlocks the mutex
|
|
// which allows the thread to continue and starts waiting
|
|
condition.Wait();
|
|
|
|
// now we can exit
|
|
return 0;
|
|
}
|
|
@endcode
|
|
|
|
Of course, here it would be much better to simply use a joinable thread and
|
|
call wxThread::Wait on it, but this example does illustrate the importance of
|
|
properly locking the mutex when using wxCondition.
|
|
|
|
@library{wxbase}
|
|
@category{threading}
|
|
|
|
@see wxThread, wxMutex
|
|
*/
|
|
class wxCondition
|
|
{
|
|
public:
|
|
/**
|
|
Default and only constructor.
|
|
The @a mutex must be locked by the caller before calling Wait() function.
|
|
Use IsOk() to check if the object was successfully initialized.
|
|
*/
|
|
wxCondition(wxMutex& mutex);
|
|
|
|
/**
|
|
Destroys the wxCondition object.
|
|
|
|
The destructor is not virtual so this class should not be used polymorphically.
|
|
*/
|
|
~wxCondition();
|
|
|
|
/**
|
|
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()
|
|
*/
|
|
wxCondError Broadcast();
|
|
|
|
/**
|
|
Returns @true if the object had been initialized successfully, @false
|
|
if an error occurred.
|
|
*/
|
|
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.
|
|
|
|
Note that this method may be called whether the mutex associated with this
|
|
condition is locked or not.
|
|
|
|
@see Broadcast()
|
|
*/
|
|
wxCondError 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.
|
|
|
|
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.
|
|
|
|
@return Returns wxCOND_NO_ERROR on success, another value if an error occurred.
|
|
|
|
@see WaitTimeout()
|
|
*/
|
|
wxCondError Wait();
|
|
|
|
/**
|
|
Waits until the condition is signalled and the associated condition true.
|
|
|
|
This is a convenience overload that may be used to ignore spurious
|
|
awakenings while waiting for a specific condition to become true.
|
|
|
|
Equivalent to
|
|
@code
|
|
while ( !predicate() )
|
|
{
|
|
wxCondError e = Wait();
|
|
if ( e != wxCOND_NO_ERROR )
|
|
return e;
|
|
}
|
|
return wxCOND_NO_ERROR;
|
|
@endcode
|
|
|
|
The predicate would typically be a C++11 lambda:
|
|
@code
|
|
condvar.Wait([]{return value == 1;});
|
|
@endcode
|
|
|
|
@since 3.0
|
|
*/
|
|
template<typename Functor>
|
|
wxCondError Wait(const Functor& predicate);
|
|
|
|
/**
|
|
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.
|
|
|
|
@param milliseconds
|
|
Timeout in milliseconds
|
|
|
|
@return Returns wxCOND_NO_ERROR if the condition was signalled,
|
|
wxCOND_TIMEOUT if the timeout elapsed before this happened or
|
|
another error code from wxCondError enum.
|
|
*/
|
|
wxCondError WaitTimeout(unsigned long milliseconds);
|
|
};
|
|
|
|
|
|
/**
|
|
@class wxCriticalSectionLocker
|
|
|
|
This is a small helper class to be used with wxCriticalSection objects.
|
|
|
|
A wxCriticalSectionLocker enters the critical section in the constructor and
|
|
leaves it in the destructor making it much more difficult to forget to leave
|
|
a critical section (which, in general, will lead to serious and difficult
|
|
to debug problems).
|
|
|
|
Example of using it:
|
|
|
|
@code
|
|
void Set Foo()
|
|
{
|
|
// gs_critSect is some (global) critical section guarding access to the
|
|
// object "foo"
|
|
wxCriticalSectionLocker locker(gs_critSect);
|
|
|
|
if ( ... )
|
|
{
|
|
// do something
|
|
...
|
|
|
|
return;
|
|
}
|
|
|
|
// do something else
|
|
...
|
|
|
|
return;
|
|
}
|
|
@endcode
|
|
|
|
Without wxCriticalSectionLocker, you would need to remember to manually leave
|
|
the critical section before each @c return.
|
|
|
|
@library{wxbase}
|
|
@category{threading}
|
|
|
|
@see wxCriticalSection, wxMutexLocker
|
|
*/
|
|
class wxCriticalSectionLocker
|
|
{
|
|
public:
|
|
/**
|
|
Constructs a wxCriticalSectionLocker object associated with given
|
|
@a criticalsection and enters it.
|
|
*/
|
|
wxCriticalSectionLocker(wxCriticalSection& criticalsection);
|
|
|
|
/**
|
|
Destructor leaves the critical section.
|
|
*/
|
|
~wxCriticalSectionLocker();
|
|
};
|
|
|
|
|
|
|
|
/**
|
|
@class wxThreadHelper
|
|
|
|
The wxThreadHelper class is a mix-in class that manages a single background
|
|
thread, either detached or joinable (see wxThread for the differences).
|
|
By deriving from wxThreadHelper, a class can implement the thread
|
|
code in its own wxThreadHelper::Entry() method and easily share data and
|
|
synchronization objects between the main thread and the worker thread.
|
|
|
|
Doing this prevents the awkward passing of pointers that is needed when the
|
|
original object in the main thread needs to synchronize with its worker thread
|
|
in its own wxThread derived object.
|
|
|
|
For example, wxFrame may need to make some calculations in a background thread
|
|
and then display the results of those calculations in the main window.
|
|
|
|
Ordinarily, a wxThread derived object would be created with the calculation
|
|
code implemented in wxThread::Entry. To access the inputs to the calculation,
|
|
the frame object would often need to pass a pointer to itself to the thread object.
|
|
Similarly, the frame object would hold a pointer to the thread object.
|
|
|
|
Shared data and synchronization objects could be stored in either object
|
|
though the object without the data would have to access the data through
|
|
a pointer.
|
|
However with wxThreadHelper the frame object and the thread object are
|
|
treated as the same object. Shared data and synchronization variables are
|
|
stored in the single object, eliminating a layer of indirection and the
|
|
associated pointers.
|
|
|
|
Example:
|
|
@code
|
|
wxDECLARE_EVENT(myEVT_THREAD_UPDATE, wxThreadEvent);
|
|
|
|
class MyFrame : public wxFrame, public wxThreadHelper
|
|
{
|
|
public:
|
|
MyFrame(...) { ... }
|
|
~MyFrame()
|
|
{
|
|
// it's better to do any thread cleanup in the OnClose()
|
|
// event handler, rather than in the destructor.
|
|
// This is because the event loop for a top-level window is not
|
|
// active anymore when its destructor is called and if the thread
|
|
// sends events when ending, they won't be processed unless
|
|
// you ended the thread from OnClose.
|
|
// See @ref overview_windowdeletion for more info.
|
|
}
|
|
|
|
...
|
|
void DoStartALongTask();
|
|
void OnThreadUpdate(wxThreadEvent& evt);
|
|
void OnClose(wxCloseEvent& evt);
|
|
...
|
|
|
|
protected:
|
|
virtual wxThread::ExitCode Entry();
|
|
|
|
// the output data of the Entry() routine:
|
|
char m_data[1024];
|
|
wxCriticalSection m_dataCS; // protects field above
|
|
|
|
wxDECLARE_EVENT_TABLE();
|
|
};
|
|
|
|
wxDEFINE_EVENT(myEVT_THREAD_UPDATE, wxThreadEvent)
|
|
wxBEGIN_EVENT_TABLE(MyFrame, wxFrame)
|
|
EVT_THREAD(wxID_ANY, myEVT_THREAD_UPDATE, MyFrame::OnThreadUpdate)
|
|
EVT_CLOSE(MyFrame::OnClose)
|
|
wxEND_EVENT_TABLE()
|
|
|
|
void MyFrame::DoStartALongTask()
|
|
{
|
|
// we want to start a long task, but we don't want our GUI to block
|
|
// while it's executed, so we use a thread to do it.
|
|
if (CreateThread(wxTHREAD_JOINABLE) != wxTHREAD_NO_ERROR)
|
|
{
|
|
wxLogError("Could not create the worker thread!");
|
|
return;
|
|
}
|
|
|
|
// go!
|
|
if (GetThread()->Run() != wxTHREAD_NO_ERROR)
|
|
{
|
|
wxLogError("Could not run the worker thread!");
|
|
return;
|
|
}
|
|
}
|
|
|
|
wxThread::ExitCode MyFrame::Entry()
|
|
{
|
|
// IMPORTANT:
|
|
// this function gets executed in the secondary thread context!
|
|
|
|
int offset = 0;
|
|
|
|
// here we do our long task, periodically calling TestDestroy():
|
|
while (!GetThread()->TestDestroy())
|
|
{
|
|
// since this Entry() is implemented in MyFrame context we don't
|
|
// need any pointer to access the m_data, m_processedData, m_dataCS
|
|
// variables... very nice!
|
|
|
|
// this is an example of the generic structure of a download thread:
|
|
char buffer[1024];
|
|
download_chunk(buffer, 1024); // this takes time...
|
|
|
|
{
|
|
// ensure no one reads m_data while we write it
|
|
wxCriticalSectionLocker lock(m_dataCS);
|
|
memcpy(m_data+offset, buffer, 1024);
|
|
offset += 1024;
|
|
}
|
|
|
|
|
|
// VERY IMPORTANT: do not call any GUI function inside this
|
|
// function; rather use wxQueueEvent():
|
|
wxQueueEvent(this, new wxThreadEvent(wxEVT_COMMAND_MYTHREAD_UPDATE));
|
|
// we used pointer 'this' assuming it's safe; see OnClose()
|
|
}
|
|
|
|
// TestDestroy() returned true (which means the main thread asked us
|
|
// to terminate as soon as possible) or we ended the long task...
|
|
return (wxThread::ExitCode)0;
|
|
}
|
|
|
|
void MyFrame::OnClose(wxCloseEvent&)
|
|
{
|
|
// important: before terminating, we _must_ wait for our joinable
|
|
// thread to end, if it's running; in fact it uses variables of this
|
|
// instance and posts events to *this event handler
|
|
|
|
if (GetThread() && // DoStartALongTask() may have not been called
|
|
GetThread()->IsRunning())
|
|
GetThread()->Wait();
|
|
|
|
Destroy();
|
|
}
|
|
|
|
void MyFrame::OnThreadUpdate(wxThreadEvent& evt)
|
|
{
|
|
// ...do something... e.g. m_pGauge->Pulse();
|
|
|
|
// read some parts of m_data just for fun:
|
|
wxCriticalSectionLocker lock(m_dataCS);
|
|
wxPrintf("%c", m_data[100]);
|
|
}
|
|
@endcode
|
|
|
|
@library{wxbase}
|
|
@category{threading}
|
|
|
|
@see wxThread, wxThreadEvent
|
|
*/
|
|
class wxThreadHelper
|
|
{
|
|
public:
|
|
/**
|
|
This constructor simply initializes internal member variables and tells
|
|
wxThreadHelper which type the thread internally managed should be.
|
|
*/
|
|
wxThreadHelper(wxThreadKind kind = wxTHREAD_JOINABLE);
|
|
|
|
/**
|
|
The destructor frees the resources associated with the thread, forcing
|
|
it to terminate (it uses wxThread::Kill function).
|
|
|
|
Because of the wxThread::Kill unsafety, you should always wait
|
|
(with wxThread::Wait) for joinable threads to end or call wxThread::Delete
|
|
on detached threads, instead of relying on this destructor for stopping
|
|
the thread.
|
|
*/
|
|
virtual ~wxThreadHelper();
|
|
|
|
/**
|
|
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.
|
|
|
|
You'll typically want your Entry() to look like:
|
|
@code
|
|
wxThread::ExitCode Entry()
|
|
{
|
|
while (!GetThread()->TestDestroy())
|
|
{
|
|
// ... do some work ...
|
|
|
|
if (IsWorkCompleted)
|
|
break;
|
|
|
|
if (HappenedStoppingError)
|
|
return (wxThread::ExitCode)1; // failure
|
|
}
|
|
|
|
return (wxThread::ExitCode)0; // success
|
|
}
|
|
@endcode
|
|
|
|
The returned value is the thread exit code which is only useful for
|
|
joinable threads and is the value returned by @c "GetThread()->Wait()".
|
|
|
|
This function is called by wxWidgets itself and should never be called
|
|
directly.
|
|
*/
|
|
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.
|
|
*/
|
|
wxThreadError Create(unsigned int stackSize = 0);
|
|
|
|
/**
|
|
Creates a new thread of the given @a kind.
|
|
|
|
The thread object is created in the suspended state, and you
|
|
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, e.g. Unix).
|
|
|
|
@return One of the ::wxThreadError enum values.
|
|
*/
|
|
wxThreadError CreateThread(wxThreadKind kind = wxTHREAD_JOINABLE,
|
|
unsigned int stackSize = 0);
|
|
|
|
/**
|
|
This is a public function that returns the wxThread object associated with
|
|
the thread.
|
|
*/
|
|
wxThread* GetThread() const;
|
|
|
|
/**
|
|
Returns the last type of thread given to the CreateThread() function
|
|
or to the constructor.
|
|
*/
|
|
wxThreadKind GetThreadKind() const;
|
|
};
|
|
|
|
/**
|
|
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
|
|
|
|
A critical section object is used for exactly the same purpose as 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 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
|
|
possible instead of directly using wxCriticalSection for the same reasons
|
|
wxMutexLocker is preferable to wxMutex - please see wxMutex for an example.
|
|
|
|
@library{wxbase}
|
|
@category{threading}
|
|
|
|
@note Critical sections can be used before the wxWidgets library is fully
|
|
initialized. In particular, it's safe to create global
|
|
wxCriticalSection instances.
|
|
|
|
@see wxThread, wxCondition, wxCriticalSectionLocker
|
|
*/
|
|
class wxCriticalSection
|
|
{
|
|
public:
|
|
/**
|
|
Default constructor initializes critical section object.
|
|
By default critical sections are recursive under Unix and Windows.
|
|
*/
|
|
wxCriticalSection( wxCriticalSectionType critSecType = wxCRITSEC_DEFAULT );
|
|
|
|
/**
|
|
Destructor frees the resources.
|
|
*/
|
|
~wxCriticalSection();
|
|
|
|
/**
|
|
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.
|
|
|
|
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();
|
|
|
|
/**
|
|
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.
|
|
*/
|
|
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
|
|
};
|
|
|
|
/**
|
|
@class wxThread
|
|
|
|
A thread is basically a path of execution through a program.
|
|
Threads are sometimes called @e light-weight processes, but the fundamental difference
|
|
between threads and processes is that memory spaces of different processes are
|
|
separated while all threads share the same address space.
|
|
|
|
While it makes it much easier to share common data between several threads, it
|
|
also makes it much easier to shoot oneself in the foot, so careful use of
|
|
synchronization objects such as mutexes (see wxMutex) or critical sections
|
|
(see wxCriticalSection) 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.
|
|
|
|
|
|
@section thread_types Types of wxThreads
|
|
|
|
There are two types of threads in wxWidgets: @e detached and @e joinable,
|
|
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 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).
|
|
|
|
Typically you'll want to store the instances of the detached wxThreads you
|
|
allocate, so that you can call functions on them.
|
|
Because of their nature however you'll need to always use a critical section
|
|
when accessing them:
|
|
|
|
@code
|
|
// declare a new type of event, to be used by our MyThread class:
|
|
wxDECLARE_EVENT(wxEVT_COMMAND_MYTHREAD_COMPLETED, wxThreadEvent);
|
|
wxDECLARE_EVENT(wxEVT_COMMAND_MYTHREAD_UPDATE, wxThreadEvent);
|
|
class MyFrame;
|
|
|
|
class MyThread : public wxThread
|
|
{
|
|
public:
|
|
MyThread(MyFrame *handler)
|
|
: wxThread(wxTHREAD_DETACHED)
|
|
{ m_pHandler = handler }
|
|
~MyThread();
|
|
|
|
protected:
|
|
virtual ExitCode Entry();
|
|
MyFrame *m_pHandler;
|
|
};
|
|
|
|
class MyFrame : public wxFrame
|
|
{
|
|
public:
|
|
...
|
|
~MyFrame()
|
|
{
|
|
// it's better to do any thread cleanup in the OnClose()
|
|
// event handler, rather than in the destructor.
|
|
// This is because the event loop for a top-level window is not
|
|
// active anymore when its destructor is called and if the thread
|
|
// sends events when ending, they won't be processed unless
|
|
// you ended the thread from OnClose.
|
|
// See @ref overview_windowdeletion for more info.
|
|
}
|
|
...
|
|
void DoStartThread();
|
|
void DoPauseThread();
|
|
|
|
// a resume routine would be nearly identic to DoPauseThread()
|
|
void DoResumeThread() { ... }
|
|
|
|
void OnThreadUpdate(wxThreadEvent&);
|
|
void OnThreadCompletion(wxThreadEvent&);
|
|
void OnClose(wxCloseEvent&);
|
|
|
|
protected:
|
|
MyThread *m_pThread;
|
|
wxCriticalSection m_pThreadCS; // protects the m_pThread pointer
|
|
|
|
wxDECLARE_EVENT_TABLE();
|
|
};
|
|
|
|
wxBEGIN_EVENT_TABLE(MyFrame, wxFrame)
|
|
EVT_CLOSE(MyFrame::OnClose)
|
|
EVT_MENU(Minimal_Start, MyFrame::DoStartThread)
|
|
EVT_COMMAND(wxID_ANY, wxEVT_COMMAND_MYTHREAD_UPDATE, MyFrame::OnThreadUpdate)
|
|
EVT_COMMAND(wxID_ANY, wxEVT_COMMAND_MYTHREAD_COMPLETED, MyFrame::OnThreadCompletion)
|
|
wxEND_EVENT_TABLE()
|
|
|
|
wxDEFINE_EVENT(wxEVT_COMMAND_MYTHREAD_COMPLETED, wxThreadEvent)
|
|
wxDEFINE_EVENT(wxEVT_COMMAND_MYTHREAD_UPDATE, wxThreadEvent)
|
|
|
|
void MyFrame::DoStartThread()
|
|
{
|
|
m_pThread = new MyThread(this);
|
|
|
|
if ( m_pThread->Run() != wxTHREAD_NO_ERROR )
|
|
{
|
|
wxLogError("Can't create the thread!");
|
|
delete m_pThread;
|
|
m_pThread = NULL;
|
|
}
|
|
|
|
// after the call to wxThread::Run(), the m_pThread pointer is "unsafe":
|
|
// at any moment the thread may cease to exist (because it completes its work).
|
|
// To avoid dangling pointers OnThreadExit() will set m_pThread
|
|
// to NULL when the thread dies.
|
|
}
|
|
|
|
wxThread::ExitCode MyThread::Entry()
|
|
{
|
|
while (!TestDestroy())
|
|
{
|
|
// ... do a bit of work...
|
|
|
|
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)
|
|
wxQueueEvent(m_pHandler, new wxThreadEvent(wxEVT_COMMAND_MYTHREAD_COMPLETED));
|
|
|
|
return (wxThread::ExitCode)0; // success
|
|
}
|
|
|
|
MyThread::~MyThread()
|
|
{
|
|
wxCriticalSectionLocker enter(m_pHandler->m_pThreadCS);
|
|
|
|
// the thread is being destroyed; make sure not to leave dangling pointers around
|
|
m_pHandler->m_pThread = NULL;
|
|
}
|
|
|
|
void MyFrame::OnThreadCompletion(wxThreadEvent&)
|
|
{
|
|
wxMessageOutputDebug().Printf("MYFRAME: MyThread exited!\n");
|
|
}
|
|
|
|
void MyFrame::OnThreadUpdate(wxThreadEvent&)
|
|
{
|
|
wxMessageOutputDebug().Printf("MYFRAME: MyThread update...\n");
|
|
}
|
|
|
|
void MyFrame::DoPauseThread()
|
|
{
|
|
// anytime we access the m_pThread pointer we must ensure that it won't
|
|
// be modified in the meanwhile; since only a single thread may be
|
|
// inside a given critical section at a given time, the following code
|
|
// is safe:
|
|
wxCriticalSectionLocker enter(m_pThreadCS);
|
|
|
|
if (m_pThread) // does the thread still exist?
|
|
{
|
|
// without a critical section, once reached this point it may happen
|
|
// that the OS scheduler gives control to the MyThread::Entry() function,
|
|
// which in turn may return (because it completes its work) making
|
|
// invalid the m_pThread pointer
|
|
|
|
if (m_pThread->Pause() != wxTHREAD_NO_ERROR )
|
|
wxLogError("Can't pause the thread!");
|
|
}
|
|
}
|
|
|
|
void MyFrame::OnClose(wxCloseEvent&)
|
|
{
|
|
{
|
|
wxCriticalSectionLocker enter(m_pThreadCS);
|
|
|
|
if (m_pThread) // does the thread still exist?
|
|
{
|
|
wxMessageOutputDebug().Printf("MYFRAME: deleting thread");
|
|
|
|
if (m_pThread->Delete() != wxTHREAD_NO_ERROR )
|
|
wxLogError("Can't delete the thread!");
|
|
}
|
|
} // exit from the critical section to give the thread
|
|
// the possibility to enter its destructor
|
|
// (which is guarded with m_pThreadCS critical section!)
|
|
|
|
while (1)
|
|
{
|
|
{ // was the ~MyThread() function executed?
|
|
wxCriticalSectionLocker enter(m_pThreadCS);
|
|
if (!m_pThread) break;
|
|
}
|
|
|
|
// wait for thread completion
|
|
wxThread::This()->Sleep(1);
|
|
}
|
|
|
|
Destroy();
|
|
}
|
|
@endcode
|
|
|
|
For a more detailed and comprehensive example, see @sample{thread}.
|
|
For a simpler way to share data and synchronization objects between
|
|
the main and the secondary thread see wxThreadHelper.
|
|
|
|
Conversely, @b joinable threads do not delete themselves when they are done
|
|
processing and as such 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
|
|
corresponding wxThread object yourself if you did not create it on the stack.
|
|
In contrast, detached threads are of the "fire-and-forget" kind: you only have
|
|
to start a detached thread and it will terminate and destroy itself.
|
|
|
|
|
|
@section thread_deletion wxThread Deletion
|
|
|
|
Regardless of whether it has terminated or not, you should call Wait() on a
|
|
@b joinable thread to release its memory, as outlined in @ref thread_types.
|
|
If you created a joinable thread on the heap, remember to delete it manually
|
|
with the @c delete operator or similar means as only detached threads handle
|
|
this type of memory management.
|
|
|
|
Since @b 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 Delete()
|
|
to gracefully end it (which implies that the thread will be deleted after
|
|
that call to Delete()). It should be implied that you should @b never attempt
|
|
to delete a detached thread with the @c delete operator or similar means.
|
|
|
|
As mentioned, Wait() or Delete() functions attempt to gracefully terminate a
|
|
joinable and a detached thread, respectively. They do this by waiting until
|
|
the thread in question calls TestDestroy() or ends processing (i.e. returns
|
|
from wxThread::Entry).
|
|
|
|
Obviously, if the thread does call TestDestroy() and does not end, the
|
|
thread which called Wait() or Delete() will come to halt.
|
|
This is why it's important to call TestDestroy() in the Entry() routine of
|
|
your threads as often as possible and immediately exit when it returns @true.
|
|
|
|
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 the object (although the wxThread object of
|
|
detached threads will still be deleted) and could leave the C runtime
|
|
library in an undefined state.
|
|
|
|
|
|
@section thread_secondary wxWidgets Calls in Secondary Threads
|
|
|
|
All threads other than the "main application thread" (the one running
|
|
wxApp::OnInit() or the one your main function runs in, for example) are
|
|
considered "secondary threads".
|
|
|
|
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 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().
|
|
This does not imply that calls to these classes are thread-safe, however,
|
|
as most wxWidgets classes are not thread-safe, including wxString.
|
|
|
|
|
|
@section thread_poll Don't Poll a wxThread
|
|
|
|
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 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
|
|
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.
|
|
|
|
Usually you only need to notify the main thread, in which case you can
|
|
post an event to it via wxQueueEvent().
|
|
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 (see wxMutex) and/or other synchronization
|
|
means if necessary.
|
|
|
|
@library{wxbase}
|
|
@category{threading}
|
|
|
|
@see wxThreadHelper, wxMutex, wxCondition, wxCriticalSection,
|
|
@ref overview_thread
|
|
*/
|
|
class wxThread
|
|
{
|
|
public:
|
|
/**
|
|
The return type for the thread functions.
|
|
*/
|
|
typedef void* ExitCode;
|
|
|
|
/**
|
|
This constructor creates a new detached (default) or joinable C++
|
|
thread object. It does not create or start execution of the real thread -
|
|
for this you should use the Run() method.
|
|
|
|
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);
|
|
|
|
/**
|
|
The destructor frees the resources associated with the thread.
|
|
Notice that you should never delete a detached thread -- you may only call
|
|
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.
|
|
*/
|
|
virtual ~wxThread();
|
|
|
|
/**
|
|
Creates a new thread.
|
|
|
|
The thread object is created in the suspended state, and you should call 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 system without @c pthread_attr_setstacksize).
|
|
|
|
If you do not specify the stack size, the system's default value is used.
|
|
|
|
@note
|
|
It is not necessary to call this method since 2.9.5, Run() will create
|
|
the thread internally. You only need to call Create() if you need to do
|
|
something with the thread (e.g. pass its ID to an external library)
|
|
before it starts.
|
|
|
|
@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 have a thread that requires more than just a few KB of memory, you
|
|
will have mysterious problems on some platforms but not on the common ones.
|
|
On the other hand, just indicating a large stack size by default will give you
|
|
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 address space can get tight unless you explicitly specify a
|
|
smaller amount of thread stack space for each thread.
|
|
|
|
@return One of:
|
|
- @b wxTHREAD_NO_ERROR - No error.
|
|
- @b wxTHREAD_NO_RESOURCE - There were insufficient resources to create the thread.
|
|
- @b wxTHREAD_NO_RUNNING - The thread is already running
|
|
*/
|
|
wxThreadError Create(unsigned int stackSize = 0);
|
|
|
|
/**
|
|
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
|
|
waits for its completion (i.e. it differs from Wait() because
|
|
it asks the thread to terminate before waiting).
|
|
|
|
See @ref thread_deletion for a broader explanation of this routine.
|
|
*/
|
|
wxThreadError Delete(ExitCode *rc = NULL,
|
|
wxThreadWait waitMode = wxTHREAD_WAIT_DEFAULT);
|
|
|
|
/**
|
|
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.
|
|
|
|
This can be used to uniquely identify threads, even if they are not wxThreads.
|
|
|
|
@see GetMainId()
|
|
*/
|
|
static wxThreadIdType GetCurrentId();
|
|
|
|
/**
|
|
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).
|
|
*/
|
|
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 0 (lowest) and 100 (highest).
|
|
|
|
@see SetPriority()
|
|
*/
|
|
unsigned int GetPriority() const;
|
|
|
|
/**
|
|
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.
|
|
*/
|
|
bool IsAlive() const;
|
|
|
|
/**
|
|
Returns @true if the thread is of the detached kind, @false if it is a
|
|
joinable one.
|
|
*/
|
|
bool IsDetached() const;
|
|
|
|
/**
|
|
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();
|
|
|
|
/**
|
|
Returns @true if the thread is paused.
|
|
*/
|
|
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() const;
|
|
|
|
/**
|
|
Immediately terminates the target thread.
|
|
|
|
@b "This function is dangerous and should be used with extreme care"
|
|
(and not used at all whenever possible)! The resources 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.
|
|
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 @b wxTHREAD_NOT_RUNNING error will be returned.
|
|
*/
|
|
wxThreadError Kill();
|
|
|
|
/**
|
|
Suspends the thread.
|
|
|
|
Under some implementations (Win32), the thread is 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 Resume();
|
|
|
|
/**
|
|
Starts the thread execution.
|
|
|
|
Note that once you Run() a @b detached thread, @e any function call you do
|
|
on the thread pointer (you must allocate it on the heap) is @e "unsafe";
|
|
i.e. the thread may have terminated at any moment after Run() and your pointer
|
|
may be dangling. See @ref thread_types for an example of safe manipulation
|
|
of detached threads.
|
|
|
|
This function can only be called from another thread context.
|
|
|
|
Finally, note that once a thread has completed and its Entry() function
|
|
returns, you cannot call Run() on it again (an assert will fail in debug
|
|
builds or @c wxTHREAD_RUNNING will be returned in release builds).
|
|
*/
|
|
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.
|
|
The value of 0 for @a level may be used to set the default one.
|
|
|
|
@return @true on success or @false otherwise (for example, if this function is
|
|
not implemented for this platform -- currently everything except Solaris).
|
|
*/
|
|
static bool SetConcurrency(size_t level);
|
|
|
|
/**
|
|
Sets the priority of the thread, between 0 (lowest) and 100 (highest).
|
|
|
|
The following symbolic constants can be used in addition to raw
|
|
values in 0..100 range:
|
|
- @c wxPRIORITY_MIN: 0
|
|
- @c wxPRIORITY_DEFAULT: 50
|
|
- @c wxPRIORITY_MAX: 100
|
|
|
|
Notice that in the MSW implementation the thread priority can currently
|
|
be only set after creating the thread with CreateThread(). But under
|
|
all platforms this method can be called either before launching the
|
|
thread using Run() or after doing it.
|
|
|
|
Please note that currently this function is not implemented when using
|
|
the default (@c SCHED_OTHER) scheduling policy under POSIX systems.
|
|
*/
|
|
void SetPriority(unsigned int priority);
|
|
|
|
/**
|
|
Pauses the thread execution for the given amount of time.
|
|
|
|
This is the same as wxMilliSleep().
|
|
*/
|
|
static void Sleep(unsigned long milliseconds);
|
|
|
|
/**
|
|
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.
|
|
*/
|
|
virtual bool TestDestroy();
|
|
|
|
/**
|
|
Return the thread object for the calling thread.
|
|
|
|
@NULL is returned if the calling thread is the main (GUI) thread, but
|
|
IsMain() should be used to test whether the thread is really the main one
|
|
because @NULL may also be returned for the thread not created with wxThread
|
|
class. Generally speaking, the return value for such a thread is undefined.
|
|
*/
|
|
static wxThread* This();
|
|
|
|
/**
|
|
Waits for a @b joinable thread to terminate and returns the value the thread
|
|
returned from Entry() or @c "(ExitCode)-1" on error. Notice that, unlike
|
|
Delete(), this function 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 @b joinable (not detached) threads.
|
|
|
|
This function can only be called from another thread context.
|
|
|
|
@param flags
|
|
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(wxThreadWait flags = wxTHREAD_WAIT_BLOCK);
|
|
|
|
/**
|
|
Give the rest of the thread's time-slice to the system allowing the other
|
|
threads to run.
|
|
|
|
Note that using this function is @b strongly discouraged, since in
|
|
many cases it indicates a design weakness of your threading model
|
|
(as does using Sleep() functions).
|
|
|
|
Threads should use the CPU in an efficient manner, i.e. they should
|
|
do their current work efficiently, then as soon as the work is done block
|
|
on a wakeup event (wxCondition, wxMutex, select(), poll(), ...) which will
|
|
get signalled e.g. by other threads or a user device once further thread
|
|
work is available.
|
|
Using Yield() or Sleep() indicates polling-type behaviour, since we're
|
|
fuzzily giving up our timeslice and wait until sometime later we'll get
|
|
reactivated, at which time we realize that there isn't really much to do
|
|
and Yield() again...
|
|
|
|
The most critical characteristic of Yield() is that it's operating system
|
|
specific: there may be scheduler changes which cause your thread to not
|
|
wake up relatively soon again, but instead many seconds later,
|
|
causing huge performance issues for your application.
|
|
|
|
<strong>
|
|
With a well-behaving, CPU-efficient thread the operating system is likely
|
|
to properly care for its reactivation the moment it needs it, whereas with
|
|
non-deterministic, Yield-using threads all bets are off and the system
|
|
scheduler is free to penalize them drastically</strong>, and this effect
|
|
gets worse with increasing system load due to less free CPU resources available.
|
|
You may refer to various Linux kernel @c sched_yield discussions for more
|
|
information.
|
|
|
|
See also Sleep().
|
|
*/
|
|
static void Yield();
|
|
|
|
protected:
|
|
|
|
/**
|
|
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().
|
|
This function is called by wxWidgets itself and should never be called
|
|
directly.
|
|
*/
|
|
virtual ExitCode Entry() = 0;
|
|
|
|
/**
|
|
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.
|
|
*/
|
|
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();
|
|
};
|
|
|
|
|
|
/** See wxSemaphore. */
|
|
enum wxSemaError
|
|
{
|
|
wxSEMA_NO_ERROR = 0,
|
|
wxSEMA_INVALID, //!< semaphore hasn't been initialized successfully
|
|
wxSEMA_BUSY, //!< returned by TryWait() if Wait() would block
|
|
wxSEMA_TIMEOUT, //!< returned by WaitTimeout()
|
|
wxSEMA_OVERFLOW, //!< Post() would increase counter past the max
|
|
wxSEMA_MISC_ERROR
|
|
};
|
|
|
|
/**
|
|
@class wxSemaphore
|
|
|
|
wxSemaphore is a counter limiting the number of threads concurrently accessing
|
|
a shared resource. This counter is always between 0 and the maximum value
|
|
specified during the semaphore creation. When the counter is strictly greater
|
|
than 0, a call to wxSemaphore::Wait() returns immediately and decrements the
|
|
counter. As soon as it reaches 0, any subsequent calls to wxSemaphore::Wait
|
|
block and only return when the semaphore counter becomes strictly positive
|
|
again as the result of calling wxSemaphore::Post which increments the counter.
|
|
|
|
In general, semaphores are useful to restrict access to a shared resource
|
|
which can only be accessed by some fixed number of clients at the same time.
|
|
For example, when modeling a hotel reservation system a semaphore with the counter
|
|
equal to the total number of available rooms could be created. Each time a room
|
|
is reserved, the semaphore should be acquired by calling wxSemaphore::Wait
|
|
and each time a room is freed it should be released by calling wxSemaphore::Post.
|
|
|
|
@library{wxbase}
|
|
@category{threading}
|
|
*/
|
|
class wxSemaphore
|
|
{
|
|
public:
|
|
/**
|
|
Specifying a @a maxcount of 0 actually makes wxSemaphore behave as if
|
|
there is no upper limit. If @a 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).
|
|
|
|
@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);
|
|
|
|
/**
|
|
Destructor is not virtual, don't use this class polymorphically.
|
|
*/
|
|
~wxSemaphore();
|
|
|
|
/**
|
|
Increments the semaphore count and signals one of the waiting
|
|
threads in an atomic way. Returns @e wxSEMA_OVERFLOW if the count
|
|
would increase the counter past the maximum.
|
|
|
|
@return One of:
|
|
- wxSEMA_NO_ERROR: There was no error.
|
|
- wxSEMA_INVALID : Semaphore hasn't been initialized successfully.
|
|
- wxSEMA_OVERFLOW: Post() would increase counter past the max.
|
|
- wxSEMA_MISC_ERROR: Miscellaneous error.
|
|
*/
|
|
wxSemaError Post();
|
|
|
|
/**
|
|
Same as Wait(), but returns immediately.
|
|
|
|
@return One of:
|
|
- wxSEMA_NO_ERROR: There was no error.
|
|
- wxSEMA_INVALID: Semaphore hasn't been initialized successfully.
|
|
- wxSEMA_BUSY: Returned by TryWait() if Wait() would block, i.e. the count is zero.
|
|
- wxSEMA_MISC_ERROR: Miscellaneous error.
|
|
*/
|
|
wxSemaError TryWait();
|
|
|
|
/**
|
|
Wait indefinitely until the semaphore count becomes strictly positive
|
|
and then decrement it and return.
|
|
|
|
@return One of:
|
|
- wxSEMA_NO_ERROR: There was no error.
|
|
- wxSEMA_INVALID: Semaphore hasn't been initialized successfully.
|
|
- wxSEMA_MISC_ERROR: Miscellaneous error.
|
|
*/
|
|
wxSemaError Wait();
|
|
|
|
/**
|
|
Same as Wait(), but with a timeout limit.
|
|
|
|
@return One of:
|
|
- wxSEMA_NO_ERROR: There was no error.
|
|
- wxSEMA_INVALID: Semaphore hasn't been initialized successfully.
|
|
- wxSEMA_TIMEOUT: Timeout occurred without receiving semaphore.
|
|
- wxSEMA_MISC_ERROR: Miscellaneous error.
|
|
*/
|
|
wxSemaError WaitTimeout(unsigned long timeout_millis);
|
|
};
|
|
|
|
|
|
|
|
/**
|
|
@class wxMutexLocker
|
|
|
|
This is a small helper class to be used with wxMutex objects.
|
|
|
|
A wxMutexLocker acquires a mutex lock in the constructor and releases
|
|
(or unlocks) the mutex in the destructor making it much more difficult to
|
|
forget to release a mutex (which, in general, will promptly lead to serious
|
|
problems). See wxMutex for an example of wxMutexLocker usage.
|
|
|
|
@library{wxbase}
|
|
@category{threading}
|
|
|
|
@see wxMutex, wxCriticalSectionLocker
|
|
*/
|
|
class wxMutexLocker
|
|
{
|
|
public:
|
|
/**
|
|
Constructs a wxMutexLocker object associated with mutex and locks it.
|
|
Call IsOk() to check if the mutex was successfully locked.
|
|
*/
|
|
wxMutexLocker(wxMutex& mutex);
|
|
|
|
/**
|
|
Destructor releases the mutex if it was successfully acquired in the ctor.
|
|
*/
|
|
~wxMutexLocker();
|
|
|
|
/**
|
|
Returns @true if mutex was acquired in the constructor, @false otherwise.
|
|
*/
|
|
bool IsOk() const;
|
|
};
|
|
|
|
|
|
/**
|
|
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
|
|
|
|
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
|
|
from its usefulness in coordinating mutually-exclusive access to a shared
|
|
resource as only one thread at a time can own a mutex object.
|
|
|
|
Mutexes may be recursive in the sense that a thread can lock a mutex which it
|
|
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 by default. The reason for this is that recursive
|
|
mutexes are not supported by all Unix flavours and, worse, they cannot be used
|
|
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 @e 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 @e 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}
|
|
|
|
@see wxThread, wxCondition, wxMutexLocker, wxCriticalSection
|
|
*/
|
|
class wxMutex
|
|
{
|
|
public:
|
|
/**
|
|
Default constructor.
|
|
*/
|
|
wxMutex(wxMutexType type = wxMUTEX_DEFAULT);
|
|
|
|
/**
|
|
Destroys the wxMutex object.
|
|
*/
|
|
~wxMutex();
|
|
|
|
/**
|
|
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();
|
|
|
|
/**
|
|
Try to lock the mutex object during the specified time interval.
|
|
|
|
@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.
|
|
|
|
@return One of: @c wxMUTEX_NO_ERROR, @c wxMUTEX_BUSY.
|
|
*/
|
|
wxMutexError TryLock();
|
|
|
|
/**
|
|
Unlocks the mutex object.
|
|
|
|
@return One of: @c wxMUTEX_NO_ERROR, @c wxMUTEX_UNLOCKED.
|
|
*/
|
|
wxMutexError Unlock();
|
|
};
|
|
|
|
|
|
|
|
// ============================================================================
|
|
// Global functions/macros
|
|
// ============================================================================
|
|
|
|
/** @addtogroup group_funcmacro_thread */
|
|
//@{
|
|
|
|
/**
|
|
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}
|
|
*/
|
|
#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 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()
|
|
{
|
|
static int s_counter = 0;
|
|
|
|
wxCRITICAL_SECTION(counter);
|
|
|
|
return ++s_counter;
|
|
}
|
|
@endcode
|
|
|
|
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 wxENTER_CRIT_SECT(critical_section)
|
|
|
|
/**
|
|
Returns @true if this thread is the main one. Always returns @true if
|
|
@c wxUSE_THREADS is 0.
|
|
|
|
@header{wx/thread.h}
|
|
*/
|
|
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
|
|
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:
|
|
|
|
@code
|
|
void MyThread::Foo(void)
|
|
{
|
|
// before doing any GUI calls we must ensure that
|
|
// this thread is the only one doing it!
|
|
|
|
wxMutexGuiEnter();
|
|
|
|
// Call GUI here:
|
|
my_window->DrawSomething();
|
|
|
|
wxMutexGuiLeave();
|
|
}
|
|
@endcode
|
|
|
|
This function is only defined on platforms which support preemptive
|
|
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.
|
|
|
|
@header{wx/thread.h}
|
|
*/
|
|
void wxMutexGuiEnter();
|
|
|
|
/**
|
|
This function is only defined on platforms which support preemptive
|
|
threads.
|
|
|
|
@see wxMutexGuiEnter()
|
|
|
|
@header{wx/thread.h}
|
|
*/
|
|
void wxMutexGuiLeave();
|
|
|
|
//@}
|
|
|