blocxx
Public Member Functions | Static Public Member Functions | Private Member Functions | Static Private Member Functions | Private Attributes | Friends

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:
Exceptionif needed system resources exhausted

Definition at line 109 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 119 of file Thread.cpp.

References BLOCXX_NAMESPACE::ThreadImpl::destroyThread(), join(), m_id, m_isRunning, and m_joined.

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:
Exceptionif needed system resources exhausted.

Definition at line 405 of file Thread.cpp.

References cancel_internal().

Referenced by cancel_internal().

void BLOCXX_NAMESPACE::Thread::cancel_internal ( bool  is_locked) [private]
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:
CancellationDeniedExceptionif doCooperativeCancel throws it to indicate that the thread cannot be safely cancelled at this time.
whateverdoCooperativeCancel() throws.

Definition at line 323 of file Thread.cpp.

References doCooperativeCancel(), isRunning(), m_cancelRequested, m_id, and BLOCXX_NAMESPACE::ThreadImpl::sendSignalToThread().

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:
timeoutThe 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:
CancellationDeniedExceptionif doCooperativeCancel throws this to indicate that the thread cannot be safely cancelled at this time.
whateverdoCooperativeCancel throws
std::bad_allocif memory exhausted
Exceptionif needed system resources exhausted
ThreadCancelledException

Definition at line 356 of file Thread.cpp.

References BLOCXX_NAMESPACE::TimeoutTimer::asAbsoluteTimeout(), BLOCXX_LOG_DEBUG3, BLOCXX_LOG_ERROR, cancel_internal(), BLOCXX_NAMESPACE::FileSystem::COMPONENT_NAME, doCooperativeCancel(), doDefinitiveCancel(), isRunning(), m_cancelled, m_cancelRequested, m_id, m_stateCond, m_stateGuard, BLOCXX_NAMESPACE::ThreadImpl::sendSignalToThread(), and BLOCXX_NAMESPACE::Condition::timedWait().

Referenced by definitiveCancel().

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

Definition at line 350 of file Thread.cpp.

References definitiveCancel(), and BLOCXX_NAMESPACE::Timeout::relative().

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

Referenced by cooperativeCancel(), and definitiveCancel().

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

Referenced by definitiveCancel().

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

Definition at line 290 of file Thread.cpp.

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

Referenced by threadRunner().

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

Referenced by shutdown().

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

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.

Referenced by cooperativeCancel(), definitiveCancel(), and start().

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

References BLOCXX_ASSERT, BLOCXX_THROW, BLOCXX_NAMESPACE::ThreadImpl::joinThread(), m_id, and m_joined.

Referenced by ~Thread().

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.

Referenced by threadRunner().

void BLOCXX_NAMESPACE::Thread::shutdown ( )

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

Exceptions:
whateverdoShutdown() throws.

Definition at line 310 of file Thread.cpp.

References doShutdown().

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:
whateverdoShutdown() throws.
ThreadCancelledException.

Definition at line 316 of file Thread.cpp.

References doShutdown(), and timedWait().

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:
milliSecondsThe number of milliseconds to suspend execution for.
Exceptions:
ThreadCancelledException
Exceptionif needed system resources exhausted

Definition at line 317 of file Thread.hpp.

References BLOCXX_NAMESPACE::ThreadImpl::sleep().

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:
secondsThe number of seconds to suspend execution for.
Exceptions:
ThreadCancelledException
Exceptionif needed system resources exhausted

Definition at line 328 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_allocif memory exhausted.
Exceptionif needed system resources exhausted.
ThreadCancelledException
ThreadException(programmer error only)

Definition at line 141 of file Thread.cpp.

References BLOCXX_THREAD_FLG_JOINABLE, BLOCXX_THROW, BLOCXX_THROW_ERRNO_MSG1, BLOCXX_NAMESPACE::ThreadImpl::createThread(), isRunning(), m_id, thread_barrier, threadRunner(), and BLOCXX_NAMESPACE::ThreadBarrier::wait().

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

Referenced by BLOCXX_NAMESPACE::cpp::upread().

Int32 BLOCXX_NAMESPACE::Thread::threadRunner ( void *  paramPtr) [static, private]
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:
timeoutHow long to wait
Returns:
true if the thread is finished, false if the timeout expired.
Exceptions:
ThreadCancelledException

Definition at line 456 of file Thread.cpp.

References BLOCXX_NAMESPACE::TimeoutTimer::asAbsoluteTimeout(), m_isRunning, m_stateCond, m_stateGuard, and BLOCXX_NAMESPACE::Condition::timedWait().

Referenced by shutdown().

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

Referenced by cancel_internal(), and definitiveCancel().

Definition at line 353 of file Thread.hpp.

Referenced by cooperativeCancel(), and definitiveCancel().

Thread_t BLOCXX_NAMESPACE::Thread::m_id [private]

Definition at line 349 of file Thread.hpp.

Referenced by cancel_internal(), doneRunning(), threadRunner(), timedWait(), and ~Thread().

Definition at line 350 of file Thread.hpp.

Referenced by join(), and ~Thread().

Definition at line 357 of file Thread.hpp.

Referenced by cancel_internal(), definitiveCancel(), doneRunning(), and timedWait().

Definition at line 356 of file Thread.hpp.

Referenced by cancel_internal(), definitiveCancel(), doneRunning(), and timedWait().


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