blocxx
|
Descriptions of exceptions thrown assume that the object is used correctly, i.e., method preconditions are satisfied. More...
#include <Thread.hpp>
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 &) | |
Thread & | operator= (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 () |
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.
BLOCXX_NAMESPACE::Thread::Thread | ( | ) |
Create a new Thread object.
Exception | if 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] |
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.
Exception | if 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] |
Definition at line 412 of file Thread.cpp.
References cancel(), m_cancelled, m_id, m_isRunning, m_stateCond, m_stateGuard, and BLOCXX_NAMESPACE::Condition::notifyAll().
Referenced by cancel(), and definitiveCancel().
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.
CancellationDeniedException | if doCooperativeCancel throws it to indicate that the thread cannot be safely cancelled at this time. |
whatever | doCooperativeCancel() 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.
timeout | The time to wait for cooperative cancellation to succeed before attempting to forcibly cancel the thread. |
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 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.
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.
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.
no | exception |
Definition at line 306 of file Thread.hpp.
bool BLOCXX_NAMESPACE::Thread::isRunning | ( | ) | [inline] |
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.
ThreadException | (programmer error only) |
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().
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.
whatever | doShutdown() 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.
whatever | doShutdown() 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.
milliSeconds | The number of milliseconds to suspend execution for. |
ThreadCancelledException | |
Exception | if 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.
seconds | The number of seconds to suspend execution for. |
ThreadCancelledException | |
Exception | if 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.
std::bad_alloc | if memory exhausted. |
Exception | if 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.
ThreadCancelledException |
Definition at line 433 of file Thread.cpp.
Referenced by BLOCXX_NAMESPACE::cpp::upread().
Int32 BLOCXX_NAMESPACE::Thread::threadRunner | ( | void * | paramPtr | ) | [static, private] |
Definition at line 184 of file Thread.cpp.
References BLOCXX_ASSERT, BLOCXX_LOG_ERROR, cb, BLOCXX_NAMESPACE::FileSystem::COMPONENT_NAME, doneRunning(), BLOCXX_NAMESPACE::ThreadImpl::exitThread(), m_id, m_isRunning, run(), BLOCXX_NAMESPACE::ThreadImpl::saveThreadInTLS(), thread_barrier, BLOCXX_NAMESPACE::Exception::type(), and BLOCXX_NAMESPACE::ThreadBarrier::wait().
Referenced by start().
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.
timeout | How long to wait |
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.
ThreadCancelledException | |
Exception | if needed system resources exhausted |
Definition at line 338 of file Thread.hpp.
References BLOCXX_NAMESPACE::ThreadImpl::yield().
void ThreadImpl::testCancel | ( | ) | [friend] |
bool BLOCXX_NAMESPACE::Thread::m_cancelled [private] |
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 348 of file Thread.hpp.
Referenced by cancel_internal(), cooperativeCancel(), definitiveCancel(), join(), start(), threadRunner(), and ~Thread().
bool BLOCXX_NAMESPACE::Thread::m_isRunning [private] |
Definition at line 349 of file Thread.hpp.
Referenced by cancel_internal(), doneRunning(), threadRunner(), timedWait(), and ~Thread().
bool BLOCXX_NAMESPACE::Thread::m_joined [private] |
Definition at line 350 of file Thread.hpp.
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().