#include <wefts_thread.h>
Inheritance diagram for Wefts::Thread:
Public Methods | |
Thread () | |
Fills member variables with default values. | |
virtual | ~Thread () |
Ensure that the thread is released. | |
bool | start (bool detachable=false, bool cancelable=true) |
Start asynchronous execution of the run() method. | |
bool | stop () |
Issue a stop request on the thread. | |
void | detach () |
Set this thread as "detached". | |
bool | detached () const |
Returns true if thread is in detached state. | |
virtual void * | join () throw ( NotJoinableError ) |
Joins a thread, waiting for its termination. | |
bool | running () const |
Returns true if thread is currently operating. | |
OSThread * | getThread () |
Returns the OS specific thread id associated with this thread object. | |
void | setData (void *data) |
Set optional specific thread data. | |
int | sequence () const |
Returns the sequence count of this thread. | |
virtual void | cleanup () |
Termination hook called by the thread termination process. | |
bool | pushCleanup (CleanupHandler *handler, int value=0) |
Adds a cleanup handler at thread termination. | |
bool | popCleanup (bool execute=false) |
Removes latest registered cleanup handler. | |
virtual void * | run ()=0 |
Main thread function. | |
Protected Methods | |
void | testCancel () |
Tests if a stop request has been issued, and if so, terminates the thread. | |
void | setCancel (bool cando) |
Sets the cancelable thread mode. | |
void | doDetach () |
Phisically detaches this thread, removing all unneeded data. | |
void | setReturn (void *ret) |
Sets the return value that can then be checked by listeners. | |
Protected Attributes | |
void * | m_runReturnValue |
Value returned by run() method. | |
OSThread | m_thread |
Machine/os thread identificator for this object. | |
bool | m_canCancel |
True if deferred cancelation is turned on. | |
void * | m_thread_data |
Optional thread specific data that can be used by this object. | |
bool | m_detached |
True if thread is detached. | |
volatile bool | m_stopped |
True if a stop request has been issued. | |
volatile bool | m_running |
True if thread if running. | |
int | m_thSequence |
This is the count of threads previously started plus two. | |
Private Methods | |
virtual void | executionEnd () |
Minimal thraed termination routines. | |
void | setCancel () |
Used internally to communicate the low-level threading system what cancelation mode is used. | |
Private Attributes | |
CleanupList | m_cleanupHandlers |
Stack of cleanup handlers to call at termination. | |
Friends | |
void | s_ThreadCleanupper (void *) |
Function used (internally) to invoke thread->cleanup() in case of cancelation. | |
void | s_ThreadRunner (void *) |
void * | s_ThreadRunFunc (void *) |
Function used (internally) to invoke thread->run(). |
A thread is an object that can be executed in a separate (parallel) environment.
The applications are required to overload the pure virtual method run(); that method should not be called directly, as the start() method will create a new thread and execute the run() function in parallel with the caller.
In both modes, the testCancel() protected member honors cancelation requests immediately, if they have been issued, immediately terminating the thread (and eventually destroying it if it is detached).
The thread can also switch to cancellable or uncancellable mode after its creation. The run() method is guaranteed not being interrupted before its execution begins, so it is possible to call the setCancel() protected member to override any default the start() method may have bestowed upon the thread. setCancel() method can also be called later on to "mark" critical sections where, although having access to blocking resources, the thread wish not to be interrupted.
Things NOT TO DO:
There isn't any control over programs misbehaving in this way, so the programmers must take care never doing something like this; anyway, the Cleanup Sequence system provides a good support to automatize this aspect (Cancellation Issues).
|
Fills member variables with default values.
|
|
Ensure that the thread is released. It is important that detachable thread subclass overload this destructor to provide automatic cancelation schemes. |
|
Termination hook called by the thread termination process. This method is called just before the thread terminates, and if the thread is detached, also just before thread destructor. This gives a chance to this thread to provide cleanup actions (as freeing mutexes not previously releases, close files and connections, logging the imminent termination, signaling in member variables things that an eventual join()er should know etc.). The Thread class implementation of cleanup() calls all the cleanup functions, so a subthread is advised to call Thread::cleanup(), at least if it can check that there are pending cleanup handlers, or suspects it. A subclass may also declare itself derived from both Thread and CleanupHandler, and then use pushCleanupHandler( this ) to subscribe itself to the thread object, instead of overloading this method; overloading is more efficient, but this latter strategy may be useful if the thread knows that many other cleanup handlers will be called randomly, and that its cleanup code must be queued in proper order.
Reimplemented in Wefts::MoaningThread. |
|
Set this thread as "detached". Set the thread type to detached: at thread termination, the object encapsulating this thread will be deleted (as well as OS resources needed to run this thread). This choice is not reversible; once a thread is detached, it can't be set to non-detachable state. A joining thread waiting for this thread to terminate will be left in waiting state until the thread terminates, but it will receive no return data and its representation of this object will be unuseable after join().
|
|
Returns true if thread is in detached state.
|
|
Phisically detaches this thread, removing all unneeded data. The detach() method only singals that this thread will not be joined by anyone, so (future) joiners are advised and the cleanup routine knows how to handle this thread. The job of signaling to OS that this thread is to be destroyed upon termination is done by this method. This is usually called by the automatic cleanup routine, but if there is some reason by which you want to terminate cleanly the thread with an early m_thread.exit(), you can use this doDetach() to prevent memory leaks. |
|
Returns the OS specific thread id associated with this thread object.
|
|
Joins a thread, waiting for its termination. This method makes the caller to wait for this thread to be terminated. It can return in three cases:
Reimplemented in Wefts::MoaningThread. |
|
Removes latest registered cleanup handler. If execute is set to true, the cleanup code will be executed immediately.
|
|
Adds a cleanup handler at thread termination. This method will return true unless the thread has been requested to stop, or it is already engaged in the cleanup process. Cleanup handlers are executed in a LIFO order (they are stacked and the last one arrive is the first that will be called).
|
|
Main thread function. This pure virtual method must be overloaded by subclasses to implement the thread main rountine. This is executed after that start() method launches the new thread. It is possible to call run() directly i.e. when your class may run both in parallel ( run() is called indirectly by start() ) and sequence ( run() is called directly by the caller ). The return value is available to communicate directly with a thread evetnaully joining this one: the returned void pointer will be passed as return of the other thread join() method. Joining a detached thread will always result in a void return, regardless of what run() method returned.
So, unless you have special reasons, run() method should always return 0. |
|
Returns true if thread is currently operating. There may be a little time in which the thread is reported to be running, but the run() method is still not executed, and another in which the thread is reported not to be running, but the OS level thread is still not terminated. Anyway, this problem can be safely ignored, as in the first case, nothing is going to stop the thread from run as soon as possible, and the OS resource for the thread are ready to go, while in the latter case the Wefts thread is not operating anymore and the OS level thread will be terminated as soon as possible. (It is under all aspects a "dead thread walking" :-) |
|
Returns the sequence count of this thread. Used for reference and debugging purposes. The main thread has a "vritual" sequence of 1; the threads started with start() method have a number ranging from 2 to MAXINT. Notice that this sequence count is invalid if thread has not been started yet (i.e. if you are running the run() method sequentially.
|
|
Sets the cancelable thread mode. If the parameter is ture, the thread can be canceled at wait or blocking points, as waits for OS calls to return or in Wefts::Sleep() calls. If set false, only an explicit testCancel() call, or a hand-made check on the m_stopped member variable will terminate the thread upon request.
|
|
Used internally to communicate the low-level threading system what cancelation mode is used.
|
|
Set optional specific thread data.
|
|
Sets the return value that can then be checked by listeners. Used mainly internally. |
|
Start asynchronous execution of the run() method. The execution of the run method is started as soon as possible, but both the m_thid and m_thSequence members are immediately set; also the count of active threads is updated immediately.
|
|
Issue a stop request on the thread. The thread will honor the request depeding on its current cancelable policy and on its own decision. Is thus important designing threads so that they never enter endless loops or deadlocks so that they can't check for stop requests being issued.
|
|
Tests if a stop request has been issued, and if so, terminates the thread. This method works the same both if the thread is cancelable or not. Indeed, if the thread is not cancellable, this is the best way to honor eventual cancelation requets issued in the meanwhile. Also, this can be useful in testing for cancelation requests issued while the thread is engaged in long computations. |
|
Function used (internally) to invoke thread->cleanup() in case of cancelation.
|
|
Function used (internally) to invoke thread->run().
|
|
|
|
True if deferred cancelation is turned on.
|
|
Stack of cleanup handlers to call at termination.
|
|
True if thread is detached.
|
|
True if thread if running.
|
|
Value returned by run() method.
|
|
True if a stop request has been issued.
|
|
Machine/os thread identificator for this object.
|
|
Optional thread specific data that can be used by this object.
|
|
This is the count of threads previously started plus two.
|