#include <CThread.h>
Collaboration diagram for CThread:
manipulators | |
CThread & | operator= (const CThread &) |
Assign thread handle. | |
void | cancel () |
Cancel thread. | |
void | setPriority (int n) |
Change thread priority. | |
void | unblockPollSocket () |
Force pollSocket() to return. | |
static void | exit (void *) |
Terminate the calling thread. | |
accessors | |
bool | wait (double timeout=-1.0) const |
Wait for thread to terminate. | |
void * | getResult () const |
Get the exit result. | |
IArchMultithread::ThreadID | getID () const |
Get the thread id. | |
bool | operator== (const CThread &) const |
Compare thread handles. | |
bool | operator!= (const CThread &) const |
Compare thread handles. | |
static CThread | getCurrentThread () |
Get current thread's handle. | |
static void | testCancel () |
Test for cancellation. | |
Public Member Functions | |
CThread (IJob *adoptedJob) | |
Run adoptedJob in a new thread. | |
CThread (const CThread &) | |
Duplicate a thread handle. | |
~CThread () | |
Release a thread handle. |
Creating a CThread creates a new context of execution (i.e. thread) that runs simulatenously with the calling thread. A CThread is only a handle to a thread; deleting a CThread does not cancel or destroy the thread it refers to and multiple CThread objects can refer to the same thread.
Threads can terminate themselves but cannot be forced to terminate by other threads. However, other threads can signal a thread to terminate itself by cancelling it. And a thread can wait (block) on another thread to terminate.
Most functions that can block for an arbitrary time are cancellation points. A cancellation point is a function that can be interrupted by a request to cancel the thread. Cancellation points are noted in the documentation.
Definition at line 40 of file CThread.h.
CThread::CThread | ( | IJob * | adoptedJob | ) |
Run adoptedJob
in a new thread.
Create and start a new thread executing the adoptedJob
. The new thread takes ownership of adoptedJob
and will delete it.
Definition at line 26 of file CThread.cpp.
Referenced by getCurrentThread().
CThread::CThread | ( | const CThread & | ) |
Duplicate a thread handle.
Make a new thread object that refers to an existing thread. This does not start a new thread.
Definition at line 36 of file CThread.cpp.
References m_thread.
CThread::~CThread | ( | ) |
Release a thread handle.
Release a thread handle. This does not terminate the thread. A thread will keep running until the job completes or calls exit() or allows itself to be cancelled.
Definition at line 46 of file CThread.cpp.
void CThread::cancel | ( | ) |
Cancel thread.
Cancel the thread. cancel() never waits for the thread to terminate; it just posts the cancel and returns. A thread will terminate when it enters a cancellation point with cancellation enabled. If cancellation is disabled then the cancel is remembered but not acted on until the first call to a cancellation point after cancellation is enabled.
A cancellation point is a function that can act on cancellation. A cancellation point does not return if there's a cancel pending. Instead, it unwinds the stack and destroys automatic objects, as if cancel() threw an exception (which is, in fact, what it does). Threads must take care to unlock and clean up any resources they may have, especially mutexes. They can catch(XThreadCancel)
to do that then rethrow the exception or they can let it happen automatically by doing clean up in the d'tors of automatic objects (like CLock). Clients are strongly encouraged to do the latter. During cancellation, further cancel() calls are ignored (i.e. a thread cannot be interrupted by a cancel during cancellation).
Clients that catch(XThreadCancel)
must always rethrow the exception. Clients that catch
(...) must either rethrow the exception or include a catch(XThreadCancel)
handler that rethrows. The RETHROW_XTHREAD
macro may be useful for that.
Definition at line 71 of file CThread.cpp.
Referenced by CSocketMultiplexer::~CSocketMultiplexer().
void CThread::exit | ( | void * | ) | [static] |
Terminate the calling thread.
Terminate the calling thread. This function does not return but the stack is unwound and automatic objects are destroyed, as if exit() threw an exception (which is, in fact, what it does). The argument is saved as the result returned by getResult(). If you have catch
(...) blocks then you should add the following before each to avoid catching the exit:
catch(CThreadExit&) { throw; }
RETHROW_XTHREAD
macro to the catch
(...) block.
Definition at line 65 of file CThread.cpp.
CThread CThread::getCurrentThread | ( | ) | [static] |
Get current thread's handle.
Return a CThread object representing the calling thread.
Definition at line 89 of file CThread.cpp.
References CThread().
IArchMultithread::ThreadID CThread::getID | ( | ) | const |
Get the thread id.
Returns an integer id for this thread. This id must not be used to check if two CThread objects refer to the same thread. Use operator==() for that.
Definition at line 116 of file CThread.cpp.
void * CThread::getResult | ( | ) | const |
Get the exit result.
Returns the exit result. This does an implicit wait(). It returns NULL immediately if called by a thread on itself or on a thread that was cancelled.
(cancellation point)
Definition at line 107 of file CThread.cpp.
References wait().
bool CThread::operator!= | ( | const CThread & | ) | const |
Compare thread handles.
Returns true if two CThread objects do not refer to the same thread.
Definition at line 128 of file CThread.cpp.
References m_thread.
Assign thread handle.
Assign a thread handle. This has no effect on the threads, it simply makes this thread object refer to another thread. It does not start a new thread.
Definition at line 52 of file CThread.cpp.
References m_thread.
bool CThread::operator== | ( | const CThread & | ) | const |
Compare thread handles.
Returns true if two CThread objects refer to the same thread.
Definition at line 122 of file CThread.cpp.
References m_thread.
void CThread::setPriority | ( | int | n | ) |
Change thread priority.
Change the priority of the thread. Normal priority is 0, 1 is the next lower, etc. -1 is the next higher, etc. but boosting the priority may not be permitted and will be silenty ignored.
Definition at line 77 of file CThread.cpp.
void CThread::testCancel | ( | ) | [static] |
Test for cancellation.
testCancel() does nothing but is a cancellation point. Call this to make a function itself a cancellation point. If the thread was cancelled and cancellation is enabled this will cause the thread to unwind the stack and terminate.
(cancellation point)
Definition at line 95 of file CThread.cpp.
Referenced by CXWindowsEventQueueBuffer::waitForEvent().
void CThread::unblockPollSocket | ( | ) |
Force pollSocket() to return.
Forces a currently blocked pollSocket() in the thread to return immediately.
Definition at line 83 of file CThread.cpp.
Referenced by CSocketMultiplexer::addSocket(), CSocketMultiplexer::removeSocket(), and CSocketMultiplexer::~CSocketMultiplexer().
bool CThread::wait | ( | double | timeout = -1.0 |
) | const |
Wait for thread to terminate.
Waits for the thread to terminate (by exit() or cancel() or by returning from the thread job) for up to timeout
seconds, returning true if the thread terminated and false otherwise. This returns immediately with false if called by a thread on itself and immediately with true if the thread has already terminated. This will wait forever if timeout
< 0.0.
(cancellation point)
Definition at line 101 of file CThread.cpp.
Referenced by CMSWindowsKeyState::fakeCtrlAltDel(), getResult(), COSXScreen::~COSXScreen(), and CSocketMultiplexer::~CSocketMultiplexer().