BLOCXX_NAMESPACE::Thread Class Reference

Descriptions of exceptions thrown assume that the object is used correctly, i.e., method preconditions are satisfied. More...

#include <Thread.hpp>

Inheritance diagram for BLOCXX_NAMESPACE::Thread:
BLOCXX_NAMESPACE::IntrusiveCountableBase

List of all members.

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 shutdown ()
 Call the thread's doShutdown(), which may be used by the thread to safely stop.
bool shutdown (const Timeout &timeout)
 Call the thread's doShutdown(), which may be used by the thread to safely stop, and then wait until the thread has exited or timeout has expired.
void cooperativeCancel ()
 Attempt to cooperatively cancel this Threads execution.
bool definitiveCancel (const Timeout &timeout=Timeout::relative(60))
 Attempt to cooperatively and then definitively cancel this Thread's execution.
bool definitiveCancel (UInt32 waitForCooperativeSecs) BLOCXX_DEPRECATED
void cancel ()
 Definitively cancel this Threads execution.
bool isRunning ()
bool timedWait (const Timeout &timeout)
 Wait for the thread to finish.
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 sleep (const Timeout &timeout)
 Suspend execution of the current thread until the given number of seconds have elapsed.
static void yield ()
 Voluntarily yield to the processor giving the next thread in the chain the opportunity to run.

Private Member Functions

void cancel_internal (bool is_locked)
virtual void doShutdown ()
 This function is available for subclasses of Thread to override if they wish to be notified when shutdown() is invoked on the instance.
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 &)
Threadoperator= (const Thread &)

Static Private Member Functions

static Int32 threadRunner (void *paramPtr)

Private Attributes

Thread_t m_id
bool m_isRunning
bool m_joined
Atomic_t m_cancelRequested
bool m_cancelled
NonRecursiveMutex m_stateGuard
Condition m_stateCond

Friends

void ThreadImpl::testCancel ()

Detailed Description

Descriptions of exceptions thrown assume that the object is used correctly, i.e., method preconditions are satisfied.

Definition at line 66 of file Thread.hpp.


Constructor & Destructor Documentation

BLOCXX_NAMESPACE::Thread::Thread (  ) 

Create a new Thread object.

Exceptions:
Exception if needed system resources exhausted

Definition at line 88 of file Thread.cpp.

BLOCXX_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 98 of file Thread.cpp.

BLOCXX_NAMESPACE::Thread::Thread ( const Thread  )  [private]

Member Function Documentation

void BLOCXX_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.

Exceptions:
Exception if needed system resources exhausted.

Definition at line 384 of file Thread.cpp.

References BLOCXX_LOG_DEBUG3, doDefinitiveCancel(), m_stateCond, and BLOCXX_NAMESPACE::Condition::timedWait().

Referenced by testCancel().

void BLOCXX_NAMESPACE::Thread::cancel_internal ( bool  is_locked  )  [private]

Definition at line 391 of file Thread.cpp.

References BLOCXX_LOG_ERROR.

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

Note that a thread may not be able to utilize doCooperativeCancel() in order to cleanly stop if it uses any blocking BloCxx APIs. Many of them call Thread::testCancel(), which will cause a ThreadCancelledException to be thrown, thus interrupting the thread's cleanup process. The supported mechanism for cleanly stopping a thread is for the thread to implement doShutdown().

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 if doCooperativeCancel throws it to indicate that the thread cannot be safely cancelled at this time.
whatever doCooperativeCancel() throws.

Definition at line 302 of file Thread.cpp.

bool BLOCXX_NAMESPACE::Thread::definitiveCancel ( UInt32  waitForCooperativeSecs  ) 

Definition at line 329 of file Thread.cpp.

bool BLOCXX_NAMESPACE::Thread::definitiveCancel ( const Timeout timeout = Timeout::relative(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:
timeout The time 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 if doCooperativeCancel throws this to indicate that the thread cannot be safely cancelled at this time.
whatever doCooperativeCancel throws
std::bad_alloc if memory exhausted
Exception if needed system resources exhausted
ThreadCancelledException 

Definition at line 335 of file Thread.cpp.

References m_id, and BLOCXX_NAMESPACE::ThreadImpl::sendSignalToThread().

void BLOCXX_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.

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 

Definition at line 424 of file Thread.cpp.

void BLOCXX_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 429 of file Thread.cpp.

Referenced by cancel().

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

Definition at line 269 of file Thread.cpp.

void BLOCXX_NAMESPACE::Thread::doShutdown (  )  [private, virtual]

This function is available for subclasses of Thread to override if they wish to be notified when shutdown() is invoked on the instance.

This function will be invoked in a separate thread. For instance, a thread may use this function to: 1. Set a flag and then signal a condition variable to wake up the thread. 2. Write to a pipe or socket, if Thread::run() is blocked in select(), it can be unblocked and then exit.

Definition at line 419 of file Thread.cpp.

Thread_t BLOCXX_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.
Exceptions:
no exception

Definition at line 306 of file Thread.hpp.

bool BLOCXX_NAMESPACE::Thread::isRunning (  )  [inline]
Returns:
true if this thread is currently running. Otherwise false.

Definition at line 270 of file Thread.hpp.

Int32 BLOCXX_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.

Precondition:
start() called on this object.
Exceptions:
ThreadException (programmer error only)
Returns:
The return value from the thread's run()

Definition at line 146 of file Thread.cpp.

Thread& BLOCXX_NAMESPACE::Thread::operator= ( const Thread  )  [private]
virtual Int32 BLOCXX_NAMESPACE::Thread::run (  )  [private, pure virtual]

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

bool BLOCXX_NAMESPACE::Thread::shutdown ( const Timeout timeout  ) 

Call the thread's doShutdown(), which may be used by the thread to safely stop, and then wait until the thread has exited or timeout has expired.

Returns:
true if the thread is finished, false if the timeout expired.
Exceptions:
whatever doShutdown() throws.
ThreadCancelledException. 

Definition at line 295 of file Thread.cpp.

void BLOCXX_NAMESPACE::Thread::shutdown (  ) 

Call the thread's doShutdown(), which may be used by the thread to safely stop.

Exceptions:
whatever doShutdown() throws.

Definition at line 289 of file Thread.cpp.

References m_isRunning, m_stateCond, m_stateGuard, and BLOCXX_NAMESPACE::Condition::notifyAll().

static void BLOCXX_NAMESPACE::Thread::sleep ( const Timeout timeout  )  [inline, static]

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

Parameters:
seconds The number of seconds to suspend execution for.
Exceptions:
ThreadCancelledException 
Exception if needed system resources exhausted

Definition at line 328 of file Thread.hpp.

References BLOCXX_NAMESPACE::ThreadImpl::sleep().

static void BLOCXX_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.
Exceptions:
ThreadCancelledException 
Exception if needed system resources exhausted

Definition at line 317 of file Thread.hpp.

References BLOCXX_NAMESPACE::ThreadImpl::sleep().

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

Start this Thread's execution.

Precondition:
start() not previously called on this object.
Exceptions:
std::bad_alloc if memory exhausted.
Exception if needed system resources exhausted.
ThreadCancelledException 
ThreadException (programmer error only)

Definition at line 120 of file Thread.cpp.

References BLOCXX_NAMESPACE::ThreadImpl::destroyThread().

void BLOCXX_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.

Exceptions:
ThreadCancelledException 

Definition at line 412 of file Thread.cpp.

References cancel(), and m_id.

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

Definition at line 163 of file Thread.cpp.

bool BLOCXX_NAMESPACE::Thread::timedWait ( const Timeout timeout  ) 

Wait for the thread to finish.

If the return value is true, join() can be called without blocking indefinitely.

Parameters:
timeout How long to wait
Returns:
true if the thread is finished, false if the timeout expired.
Exceptions:
ThreadCancelledException 

Definition at line 435 of file Thread.cpp.

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

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

Exceptions:
ThreadCancelledException 
Exception if needed system resources exhausted

Definition at line 338 of file Thread.hpp.

References BLOCXX_NAMESPACE::ThreadImpl::yield().


Friends And Related Function Documentation

void ThreadImpl::testCancel (  )  [friend]

Member Data Documentation

Definition at line 354 of file Thread.hpp.

Definition at line 353 of file Thread.hpp.

Thread_t BLOCXX_NAMESPACE::Thread::m_id [private]

Definition at line 348 of file Thread.hpp.

Referenced by definitiveCancel(), and testCancel().

Definition at line 349 of file Thread.hpp.

Referenced by shutdown().

Definition at line 350 of file Thread.hpp.

Definition at line 357 of file Thread.hpp.

Referenced by cancel(), and shutdown().

Definition at line 356 of file Thread.hpp.

Referenced by shutdown().


The documentation for this class was generated from the following files:
Generated on Mon Jul 5 19:59:59 2010 for blocxx by  doxygen 1.6.3