Wefts::Thread Class Reference
[Thread object incapsulation]

Implements the abstraction of a thread. More...

#include <wefts_thread.h>

Inheritance diagram for Wefts::Thread:

[legend]Collaboration diagram for Wefts::Thread:

[legend]List of all members.

Public Member Functions
	Thread (OSPriority prio=PrioNormal, int boost=0)
	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 ()
	Returns true if thread is in detached state.
virtual void *	join () throw ( NotJoinableError )
	Joins a thread, waiting for its termination.
bool	running ()
	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.
bool	priority (OSPriority Prio, int boost=0)
	Changes the priority scheduling and boost of this thread.
virtual void *	run ()=0
	Main thread function.
void *	getRunReturn ()
	Returns run return code, if run has completed and returned.
Protected Member Functions
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.
Protected Attributes
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.
bool	m_stopped
	True if the thread has been stopped at low level (exit pending).
bool	m_wasCanceled
	True if the thread received a stop() request while cancelation is disabled.
volatile bool	m_running
	True if thread if running.
int	m_thSequence
	This is the count of threads previously started plus two.
Private Member Functions
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.
OSPriority	m_reqPriority
	Requested scheduling policy.
int	m_reqBoost
	Requested priority boost.
Mutex	m_guard
	Internal mutex used to protect concurrent access to internal variables.
void *	m_runReturn
	Used by the C cleanup routine to set the return value on need.
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 moment. This is called a "kind" cancellation request, as the "final" word upon termination or is left to the application level code.

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:

• Holding a mutex while entering in cancellation points (if thread is cancelable)
• Test for cancel while holding mutexes.
• Not releasing mutexes before to exit.

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 (  OSPriority  prio = PrioNormal, int  boost = 0 )

Fills member variables with default values. Note: IMPORTANT: Never, NEVER create threads as static items. Thread items must always be dynamically allocated, or the cleanup system will be fooled. The thread object must stay alive for the whole life of the system thread, and static allocation would not grant this capability; other than that, the system needs to know what is going on in a thread object. To automatically deallocate the thread item on termination, use start( true ); this makes the thread "detached", that will destroy the pointer to the thread object created by the constructor. If there is the need to access the thread after is termination, join it and work on the thread pointer; then delete it. Deleting a thread object after that the thread routine is terminated is safe. Long story short: thread objects are meant to be created only via the new constructor, or equivalent dynamic memory allocation method. The caller can set a default scheduling policy, and eventually a default priority boost, that will be enacted on the thread as soon as it is created. There may be some delay between the creation of the thread and the schedule policy change. Parameters: prio  Scheduling policy (priority) for thread at start() request. boost  Scheduling priority boost. See also: OSThreadBase::priority() for details on schedule and priority handling.

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

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

void* Wefts::Thread::getRunReturn (   )  [inline]

Returns run return code, if run has completed and returned. If this not happened, 0 is returned.

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: this thread cleanly terminates; in this case join() returns the void * returned by run() (that may be 0). this thread is detached; in this case join throws an NotJoinableError. 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::priority (  OSPriority  Prio, int  boost = 0 )

Changes the priority scheduling and boost of this thread. See also: OSThreadBase::priority() for details on priority management. Parameters: prio  Scheduling policy. boost  priority boost. Returns: true on success, false on failure.

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. Also, if the thread is not detached, after its termination the return value of this method is available by calling getRunReturn(). 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 (   )  [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.

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. Stop() method will stop the thread, privided it's running. If the cancelation is currently disabled the stop request will be cached; in the case cancelation is re-enabled, the stop request is re-iterated. Note that this does not makes setCancel() a cancelation point; reiterating at low level the stop request will not cause termination of the thread until a cancelation point is met. Simply, if setCancel() is disabled, stop() won't do nothing except (atomically) recording the fact that it has been called; this fact will become meaningful only in the event of cancelation being enabled in a second moment. See also: setCancel() Returns: false if the stop request can be honored, false if it can't be honored currently due to setCancel() policy or running status.

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. As this function is the only one that has the right to delete the thread object in case of detached thread, this function is also responsible to set the m_runReturn parameter in case the thread is NOT detached. For this reasion, this function is fed with a ThreadAndReturn pointer as parameter. Parameters: param  a ThreadAndReturn structure pointer, containing the thread object and the run return value, if the run function had the chance to return, or 0 otherwise.

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.

Mutex Wefts::Thread::m_guard [private]

Internal mutex used to protect concurrent access to internal variables.

int Wefts::Thread::m_reqBoost [private]

Requested priority boost.

OSPriority Wefts::Thread::m_reqPriority [private]

Requested scheduling policy.

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

True if thread if running. See also: running()

void* Wefts::Thread::m_runReturn [private]

Used by the C cleanup routine to set the return value on need.

bool Wefts::Thread::m_stopped [protected]

True if the thread has been stopped at low level (exit pending).

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

bool Wefts::Thread::m_wasCanceled [protected]

True if the thread received a stop() request while cancelation is disabled.

---

The documentation for this class was generated from the following files:

• wefts_thread.h
• wefts_thread.cpp

---