OW_NAMESPACE::Thread Class Reference

#include <OW_Thread.hpp>

Inheritance diagram for OW_NAMESPACE::Thread:

[legend]Collaboration diagram for OW_NAMESPACE::Thread:


Public Member Functions
	Thread ()
	Create a new Thread object.
virtual	~Thread ()
	Destroy this Thread object.
virtual void	start (const ThreadDoneCallbackRef &cb=ThreadDoneCallbackRef(0))
	Start this Thread's execution.
void	cooperativeCancel ()
	Attempt to cooperatively cancel this Threads execution.
bool	definitiveCancel (UInt32 waitForCooperativeSecs=60)
	Attempt to cooperatively and then definitively cancel this Thread's execution.
void	cancel ()
	Definitively cancel this Threads execution.
bool	isRunning ()
Int32	join ()
	Join with this Thread's execution.
Thread_t	getId ()
	Get this Thread object's id.
Static Public Member Functions
static void	testCancel ()
	Test if this thread has been cancelled.
static void	sleep (UInt32 milliSeconds)
	Suspend execution of the current thread until the given number of milliSeconds have elapsed.
static void	yield ()
	Voluntarily yield to the processor giving the next thread in the chain the opportunity to run.
Private Member Functions
virtual void	doCooperativeCancel ()
	This function is available for subclasses of Thread to override if they wish to be notified when a cooperative cancel is being invoked on the instance.
virtual void	doDefinitiveCancel ()
	See the documentation for doCooperativeCancel().
virtual Int32	run ()=0
	The method that will be run when the start method is called.
void	doneRunning (const ThreadDoneCallbackRef &cb)
	Thread (const Thread &)
Thread &	operator= (const Thread &)
Static Private Member Functions
static Int32	threadRunner (void *paramPtr)
Private Attributes
Thread_t	m_id
bool	m_isRunning
bool	m_isStarting
bool	m_joined
NonRecursiveMutex	m_cancelLock
Condition	m_cancelCond
bool	m_cancelRequested
bool	m_cancelled
Friends
void	ThreadImpl::testCancel ()

Detailed Description

Definition at line 57 of file OW_Thread.hpp.

Constructor & Destructor Documentation

OW_NAMESPACE::Thread::Thread ( )

Create a new Thread object.

Definition at line 85 of file OW_Thread.cpp.

OW_NAMESPACE::Thread::~Thread ( ) [virtual]

Destroy this Thread object.
The destructor will call join() if it hasn't been previously called. This function won't return until the thread has exited.
Definition at line 96 of file OW_Thread.cpp.
References OW_NAMESPACE::ThreadImpl::destroyThread(), join(), m_id, m_isRunning, m_joined, OW_NAMESPACE::NULLTHREAD, and OW_NAMESPACE::sameId().

OW_NAMESPACE::Thread::Thread ( const Thread & ) [private]

Member Function Documentation

void OW_NAMESPACE::Thread::cancel ( )

Definitively cancel this Threads execution.
The thread is *NOT* given a chance to clean up or override the cancellation. DO NOT call this function without first trying definitiveCancel().
You should still call join() in order to clean up resources allocated for this thread.
Note that when using this function, any objects on the thread's stack will not be cleaned up unless the operating system and compiler support stack unwinding on thread cancellation. As such, it may cause memory leaks or inconsistent state or even memory corruption. Also note that this still may not stop the thread, since a thread can make itself non-cancellable, or it may not ever call any cancellation points. By default all Thread objects are asynchronously cancellable, and so may be immediately cancelled. The thread may (unlikely) still be running after this function returns.
Definition at line 338 of file OW_Thread.cpp.
References OW_NAMESPACE::ThreadImpl::cancel(), m_cancelled, and m_id.
Referenced by definitiveCancel().

void OW_NAMESPACE::Thread::cooperativeCancel ( )

Attempt to cooperatively cancel this Threads execution.
You should still call join() in order to clean up resources allocated for this thread. This function will set a flag that the thread has been cancelled, which can be checked by testCancel(). If the thread does not call testCancel(), it may keep running. The thread may (probably) still be running after this function returns, and it will exit as soon as it calls testCancel().
It is also possible for an individual thread to override the cancellation request, if it knows that cancellation at this time may crash the system or cause a deadlock. If this happens, a CancellationDeniedException will be thrown.

Exceptions:

CancellationDeniedException may be thrown if the thread cannot be safely cancelled at this time.

Definition at line 266 of file OW_Thread.cpp.
References doCooperativeCancel(), isRunning(), m_cancelLock, m_cancelRequested, m_id, and OW_NAMESPACE::ThreadImpl::sendSignalToThread().

bool OW_NAMESPACE::Thread::definitiveCancel ( UInt32 waitForCooperativeSecs = 60 )

Attempt to cooperatively and then definitively cancel this Thread's execution.
You should still call join() in order to clean up resources allocated for this thread. This function will set a flag that the thread has been cancelled, which can be checked by testCancel(). definitiveCancel() wil first try to stop the thread in a cooperative manner to avoid leaks or corruption. If the thread has not exited after waitForCoopeartiveSecs seconds, it will be cancelled. Note that when using this function, any objects on the thread's stack will not be cleaned up unless the operating system and compiler support stack unwinding on thread cancellation. As such, it may cause memory leaks or inconsistent state or even memory corruption. Also note that this still may not stop the thread, since a thread can make itself non-cancellable, or it may not ever call any cancellation points. By default all Thread objects are asynchronously cancellable, and so may be immediately cancelled. The thread may (unlikely) still be running after this function returns.
It is also possible for an individual thread to override the cancellation request, if it knows that cancellation at this time may crash the system or cause a deadlock. If this happens, an CancellationDeniedException will be thrown.

Parameters:

waitForCooperativeSecs The number of seconds to wait for cooperative cancellation to succeed before attempting to forcibly cancel the thread.

Returns:
true if the thread exited cleanly. false if the thread was forcibly cancelled.

Exceptions:

CancellationDeniedException may be thrown if the thread cannot be safely cancelled at this time.

Definition at line 294 of file OW_Thread.cpp.
References cancel(), doCooperativeCancel(), doDefinitiveCancel(), isRunning(), m_cancelCond, m_cancelled, m_cancelLock, m_cancelRequested, m_id, OW_NAMESPACE::ThreadImpl::sendSignalToThread(), and OW_NAMESPACE::Condition::timedWait().

void OW_NAMESPACE::Thread::doCooperativeCancel ( ) [private, virtual]

This function is available for subclasses of Thread to override if they wish to be notified when a cooperative cancel is being invoked on the instance.
Note that this function will be invoked in a separate thread. For instance, a thread may use this function to write to a pipe or socket, if Thread::run() is blocked in select(), it can be unblocked and instructed to exit.
It is also possible for an individual thread to override the cancellation request, if it knows that cancellation at this time may crash the system or cause a deadlock. To do this, the thread should throw an CancellationDeniedException. Note that threads are usually only cancelled in the event of a system shutdown or restart, so a thread should make a best effort to actually shutdown.

Exceptions:

CancellationDeniedException

Reimplemented in OW_NAMESPACE::PollingManagerThread, and OW_NAMESPACE::IndicationServerImplThread.
Definition at line 359 of file OW_Thread.cpp.
Referenced by cooperativeCancel(), and definitiveCancel().

void OW_NAMESPACE::Thread::doDefinitiveCancel ( ) [private, virtual]

See the documentation for doCooperativeCancel().
When definitiveCancel() is called on a thread, first doCooperativeCancel() will be called, and then doDefinitiveCancel() will be called.

Exceptions:

CancellationDeniedException

Definition at line 364 of file OW_Thread.cpp.
Referenced by definitiveCancel().

void OW_NAMESPACE::Thread::doneRunning ( const ThreadDoneCallbackRef & cb ) [private]

Definition at line 239 of file OW_Thread.cpp.
References m_cancelCond, m_cancelled, m_cancelLock, m_isRunning, m_isStarting, and OW_NAMESPACE::Condition::notifyAll().

Thread_t OW_NAMESPACE::Thread::getId ( ) [inline]

Get this Thread object's id.
This function cannot be called on a non-joinable self-deleting thread after it has started.

Returns:
The id of this Thread if it is currently running. Otherwise return a NULL thread id.

Definition at line 235 of file OW_Thread.hpp.

bool OW_NAMESPACE::Thread::isRunning ( ) [inline]

Returns:
true if this thread is currently running. Otherwise false.

Definition at line 210 of file OW_Thread.hpp.
Referenced by cooperativeCancel(), definitiveCancel(), and start().

Int32 OW_NAMESPACE::Thread::join ( )

Join with this Thread's execution.
This method should be called on all joinable threads. The destructor will call it as well. If this Thread object is executing, this method will block until this Thread's run method returns. join() should not be called until after start() has returned. It may be called by a different thread.

Exceptions:

ThreadException

Returns:
The return value from the thread's run()

Definition at line 145 of file OW_Thread.cpp.
References OW_NAMESPACE::ThreadImpl::joinThread(), m_id, m_isRunning, m_joined, OW_NAMESPACE::NULLTHREAD, OW_ASSERT, OW_THROW, and OW_NAMESPACE::sameId().
Referenced by OW_NAMESPACE::PollingManagerThread::shutdown(), OW_NAMESPACE::IndicationServerImplThread::shutdown(), and ~Thread().

Thread& OW_NAMESPACE::Thread::operator= ( const Thread & ) [private]

virtual Int32 OW_NAMESPACE::Thread::run ( ) [private, pure virtual]

The method that will be run when the start method is called.

Implemented in OW_NAMESPACE::PollingManagerThread, and OW_NAMESPACE::IndicationServerImplThread.

static void OW_NAMESPACE::Thread::sleep ( UInt32 milliSeconds ) [inline, static]

Suspend execution of the current thread until the given number of milliSeconds have elapsed.

Parameters:

milliSeconds The number of milliseconds to suspend execution for.

Definition at line 244 of file OW_Thread.hpp.
References OW_NAMESPACE::ThreadImpl::sleep().

void OW_NAMESPACE::Thread::start ( const ThreadDoneCallbackRef & cb = ThreadDoneCallbackRef(0) ) [virtual]

Start this Thread's execution.

Exceptions:

ThreadException

Definition at line 118 of file OW_Thread.cpp.
References OW_NAMESPACE::ThreadImpl::createThread(), isRunning(), m_id, m_isStarting, OW_NAMESPACE::NULLTHREAD, OW_THREAD_FLG_JOINABLE, OW_THROW, OW_NAMESPACE::sameId(), threadRunner(), and OW_NAMESPACE::ThreadBarrier::wait().

void OW_NAMESPACE::Thread::testCancel ( ) [static]

Test if this thread has been cancelled.
If so, a ThreadCancelledException will be thrown. DO NOT catch this exception. ThreadCancelledException is not derived from anything. Except for in destructors, do not write code like this: try { //... } catch (...) { // swallow all exceptions }
Instead do this: try { //... } catch (ThreadCancelledException&) { throw; } catch (std::exception& e) { // handle the exception } The only place ThreadCancelledException should be caught is in Thread::threadRunner() or a destructor. main() shouldn't need to catch it, as the main thread of an application should never be cancelled. The main thread shouldn't need to ever call testCancel. Note that this method is staic, and it will check if the current running thread has been cancelled. Thus, you can't call it on an object that doesn't represent the current running thread and expect it to work.
Definition at line 353 of file OW_Thread.cpp.
References OW_NAMESPACE::ThreadImpl::testCancel().

Int32 OW_NAMESPACE::Thread::threadRunner ( void * paramPtr ) [static, private]

Definition at line 164 of file OW_Thread.cpp.
References OW_NAMESPACE::ThreadParam::cb, OW_NAMESPACE::ThreadImpl::exitThread(), OW_ASSERT, OW_NAMESPACE::ThreadImpl::saveThreadInTLS(), OW_NAMESPACE::ThreadParam::thread, OW_NAMESPACE::ThreadParam::thread_barrier, OW_NAMESPACE::Exception::type(), and OW_NAMESPACE::ThreadBarrier::wait().
Referenced by start().

static void OW_NAMESPACE::Thread::yield ( ) [inline, static]

Voluntarily yield to the processor giving the next thread in the chain the opportunity to run.

Definition at line 252 of file OW_Thread.hpp.
References OW_NAMESPACE::ThreadImpl::yield().