Main Page   Modules   Namespace List   Class Hierarchy   Alphabetical List   Compound List   File List   Namespace Members   Compound Members   File Members   Related Pages  

Wefts::Thread Class Reference
[Thread object incapsulation]

Implements the abstraction of a thread. More...

#include <wefts_thread.h>

Inheritance diagram for Wefts::Thread:

Inheritance graph
[legend]
Collaboration diagram for Wefts::Thread:

Collaboration graph
[legend]
List of all members.

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.

OSThreadgetThread ()
 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().


Detailed Description

Implements the abstraction of a thread.

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.

Note:
run() method can be called directrly, if the application can be sure that the method is fully reentrant (does not use any global unguarded data). In fact, this is a common way to allow execution of a procedure in sequence or in parallel (or both) depending on external conditions or on user choice.
There are mainly two kind of threads: detached and non-detached. A detached thread is automatically destroyed as soon as it terminates, without further need of attention by the caller. A non-detached thread will not clean its data upon termination or cancelation; this allows a caller to inspect the non-detached thread after its termination. Non detached threads have also a synchronization method, join(), that MUST be called by some thread in the application to 1) know when the thread is done and 2) free OS specific data needed for parallel execution (join() won't free internal class data, that must be deleted manually). Anyway, join() can be called also on detached threads to know when they are finished, but immediately after join() return, a detached thread object must be considered invalid (already deleted). A wefts thread can be created detached or can be detached at any moment in its run() function with the detach() method. Use this method if you know that no other thread is going to join a running thread.

Note:
this differs from posix implementation of threads. A detached posix thread can't be joined (doing it would immediately return with error).
Wefts threads also implement deferred and kind cancellation. The thread can be created in cancellable and uncancellable mode. In cancellable mode, the thread can be interrupted and terminated in functions that are waiting for an external event to happen by the stop() method; this include input output functions and wait ( e.g. Wefts::Sleep() ) routines. In non-cancellable mode, the thread won't receive such uncontrollable cancel orders, but the member variable m_stopped will be set to true if thread is requested to terminate. The thread can then check periodically a variable and honor the request, if it wills, immediately or at any later mode. This is called a "kind" cancellation request, as the "final" word upon termination or is left to the thread.

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).


Constructor & Destructor Documentation

Wefts::Thread::Thread  
 

Fills member variables with default values.

Wefts::Thread::~Thread   [virtual]
 

Ensure that the thread is released.

It is important that detachable thread subclass overload this destructor to provide automatic cancelation schemes.


Member Function Documentation

void Wefts::Thread::cleanup   [virtual]
 

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.

Note:
Cleanup sequence is Experimental; it works, but there is the need to expermient more on the race conditions and how/where use mutexes to make it fast but not unsafe. Don't push handlers except from the thread that will have to handle them.
Todo:
tests about stability of cleanup in stress environment (pushing handlers from other threads. Has it any sense?).

See also:
Cleanup system

Reimplemented in Wefts::MoaningThread.

void Wefts::Thread::detach   [inline]
 

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().

See also:
join()

bool Wefts::Thread::detached   const [inline]
 

Returns true if thread is in detached state.

void Wefts::Thread::doDetach   [inline, protected]
 

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.

OSThread* Wefts::Thread::getThread   [inline]
 

Returns the OS specific thread id associated with this thread object.

void * Wefts::Thread::join   throw ( NotJoinableError ) [virtual]
 

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:

  1. this thread cleanly terminates; in this case join() returns the void * returned by run() (that may be 0).
  2. this thread is detached; in this case join throws an NotJoinableError.
  3. the calling thread is interrupted by a signal; also in this case, join() throws the error. If a join() trows a NotJoinableError, the caller should never use anymore the called object: in fact, a detached thread is destroyed before join can return, and using it would cause an immediate crash, while if the calling thread is awaken by a signal, there is no safe way to know if the joined thread will still be valid when the joiner tries to handle it.
Returns:
the void* returned from thread's run() method (may be 0).

Reimplemented in Wefts::MoaningThread.

bool Wefts::Thread::popCleanup bool    execute = false [inline]
 

Removes latest registered cleanup handler.

If execute is set to true, the cleanup code will be executed immediately.

Note:
Cleanup sequence is Experimental; it works, but there is the need to expermient more on the race conditions and how/where use mutexes to make it fast but not unsafe. Don't use it except for experimental code.
Returns:
false if there aren't handlers to remove
See also:
CleanupHandler

bool Wefts::Thread::pushCleanup CleanupHandler   handler,
int    value = 0
[inline]
 

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).

Note:
Cleanup sequence is Experimental; it works, but there is the need to expermient more on the race conditions and how/where use mutexes to make it fast but not unsafe. Don't use it except for experimental code.
See also:
CleanupHandler

virtual void* Wefts::Thread::run   [pure virtual]
 

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.

Note:
Never return a dynamically allocated object in run() when the thread is detached; this would result in memory leaks, unless the returned object is anyway destroyed by the class destructor. Return code should be something like:
         ...
         if ( detached() )
            return 0;
         else
            return myCuteObject;
         ...
Anyway, object oriented implementation offers more elegant solutions, as providing a member variable (eventually guarded with accessors) to the joining thread.

So, unless you have special reasons, run() method should always return 0.

bool Wefts::Thread::running   const [inline]
 

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" :-)

int Wefts::Thread::sequence   const [inline]
 

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.

See also:
m_thSequence

void Wefts::Thread::setCancel bool    cando [protected]
 

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.

Parameters:
cando  true if thread is cancelable, false otherwise.

void Wefts::Thread::setCancel   [inline, private]
 

Used internally to communicate the low-level threading system what cancelation mode is used.

void Wefts::Thread::setData void *    data [inline]
 

Set optional specific thread data.

void Wefts::Thread::setReturn void *    ret [inline, protected]
 

Sets the return value that can then be checked by listeners.

Used mainly internally.

bool Wefts::Thread::start bool    detachable = false,
bool    cancelable = true
 

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.

Parameters:
detachable  true if thread is detached, false otherwise
cancelable  true if thread is cancelable, false otherwise
Returns:
true if thread can be started, false on error

bool Wefts::Thread::stop  
 

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.

Returns:
false if the thread is not being run, true otherwise

void Wefts::Thread::testCancel   [inline, protected]
 

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.


Friends And Related Function Documentation

void s_ThreadCleanupper void *    param [friend]
 

Function used (internally) to invoke thread->cleanup() in case of cancelation.

void* s_ThreadRunFunc void *    param [friend]
 

Function used (internally) to invoke thread->run().

void s_ThreadRunner void *    data [friend]
 


Member Data Documentation

bool Wefts::Thread::m_canCancel [protected]
 

True if deferred cancelation is turned on.

CleanupList Wefts::Thread::m_cleanupHandlers [private]
 

Stack of cleanup handlers to call at termination.

bool Wefts::Thread::m_detached [protected]
 

True if thread is detached.

volatile bool Wefts::Thread::m_running [protected]
 

True if thread if running.

See also:
running()

void* Wefts::Thread::m_runReturnValue [protected]
 

Value returned by run() method.

volatile bool Wefts::Thread::m_stopped [protected]
 

True if a stop request has been issued.

OSThread Wefts::Thread::m_thread [protected]
 

Machine/os thread identificator for this object.

void* Wefts::Thread::m_thread_data [protected]
 

Optional thread specific data that can be used by this object.

int Wefts::Thread::m_thSequence [protected]
 

This is the count of threads previously started plus two.

See also:
sequence()


The documentation for this class was generated from the following files:
Generated on Mon Dec 22 04:12:40 2003 for Wefts by doxygen1.2.18