---

Wefts::Thread Class Reference

Implements the abstraction of a thread. More...

#include <wefts_thread.h>

Inheritance diagram for Wefts::Thread:

[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 ()
	Detach the thead.
bool	detached ()
	Returns true if thread is in detached state.
virtual void *	join ()
	Joins a thread, waiting for its termination.
bool	running ()
	Returns true if thread is currently operating.
pthread_t	getId ()
	Returns the OS specific thread id associated with this thread object.
void	setData (void *data)
	Set optional specific thread data.
int	sequence ()
	Returns the sequence count of this thread.
virtual void	cleanup ()
	Termination hook called by the thread termination process.
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.
Protected Attributes
void *	m_runReturnValue
	Value returned by run() method.
pthread_t	m_thid
	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 a stop request has been issued.
int	m_thSequence
	This is the count of threads previously started plus two.
Private Methods
virtual void	executionEnd ()
	Minimal thraed termination routines This routine is executed at thread termination to ensure that all non class-dependant operations are done before cleanup() routine and then the destructors are called.
void	setCancel ()
	Used internally to communicate the low-level threading system what cancelation mode is used.
Friends
void *	s_ThreadRunFunc (void *)
	Function used (internally) to invoke thread->run().
void	s_ThreadCleanupper (void *)
	Function used (internally) to invoke thread->cleanup() in case of cancelation.

---

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 thread: 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 it's 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

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 this 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:

• 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. Notice that condition waits are cancelation points, but while waiting the lock() on the condition is automatically released.

---

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

virtual void Wefts::Thread::cleanup (    )  [inline, 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() does nothing. Reimplemented in Wefts::MoaningThread.

void Wefts::Thread::detach (    )  [inline]

Detach the thead. 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.

bool Wefts::Thread::detached (    )  [inline]

Returns true if thread is in detached state.

virtual void Wefts::Thread::executionEnd (    )  [inline, private, virtual]

Minimal thraed termination routines This routine is executed at thread termination to ensure that all non class-dependant operations are done before cleanup() routine and then the destructors are called. This function marks the point after which the Wefts level thread object is not considered "running" anymore.

pthread_t Wefts::Thread::getId (    )  [inline]

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

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

Joins a thread, waiting for its termination. Returns: the value returned from thread's run() method. The return value of a detached thread will always be 0. Reimplemented in Wefts::MoaningThread.

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

---

Member Data Documentation

bool Wefts::Thread::m_canCancel [protected]

True if deferred cancelation is turned on.

bool Wefts::Thread::m_detached [protected]

True if thread is detached.

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

Value returned by run() method.

bool Wefts::Thread::m_stopped [protected]

True if a stop request has been issued.

pthread_t Wefts::Thread::m_thid [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:

• wefts_thread.h
• wefts_thread.cpp

---