cthread.htm

A class that allows the simple implementation of worker threads

<DT>nPriority</DT>
</I><DD>[in] WINDOWS thread priority. Can be one of the following: <BR>
<BR>
THREAD_PRIORITY_NORMAL <BR>
THREAD_PRIORITY_ABOVE_NORMAL <BR>
THREAD_PRIORITY_BELOW_NORMAL <BR>
THREAD_PRIORITY_HIGHEST <BR>
THREAD_PRIORITY_IDLE <BR>
THREAD_PRIORITY_LOWEST <BR>
THREAD_PRIORITY_TIME_CRITICAL</DD>
</DL>
<H3>See Also</H3>
<B><P>GetPriority</B> </P>
<P>Back to <A HREF="#CThread">CThread</A></P>
<P><HR></P>
<P><A NAME="CThread__SetStackSize"></P>
<H1>CThread::SetStackSize</H1>
<B><P></A>void</B> <B>CThread::SetStackSize(DWORD</B> <I>dwStackSize</I> <B>= 0) </P>
</B><P>Sets the WINDOWS thread stack size (see WINDOWS Threads in Microsoft MSDN documentation). <BR>
Thread stack size - if necessary - should be set before CThread thread is started.</P>
<H3>Parameters</H3>
<I><DL>
<DT>dwStackSize</DT>
</I><DD>[in] Desired WINDOWS thread stack size.</DD>
</DL>
<H3>See Also</H3>
<B><P>GetStackSize</B> </P>
<P>Back to <A HREF="#CThread">CThread</A></P>
<P><HR></P>
<P><A NAME="CThread__Start"></P>
<H1>CThread::Start</H1>
<B><P></A>void</B> <B>CThread::Start(void) </P>
</B><P>&#9;<B>throws CThreadException</B> of types: <BR>
&#9;CThreadException::CANNOT_CREATE_THREAD, <BR>
&#9;CThreadException::THREAD_ALREADY_STARTED, <BR>
&#9;CThreadException::CANNOT_CREATE_NOTIFICATION_OBJECT, <BR>
&#9;CThreadException::CANNOT_SIGNAL_NOTIFICATION_OBJECT <BR>
<BR>
This method starts the WINDOWS thread connected to CThread object. Used in the owner thread. Once established the WINDOWS thread cannot be started again until it terminates. <BR>
Before starting a thread user may set up WINDOWS thread attributes or thread stack size if necessary. This can be accomplished by calling the <B>SetAttributes</B> or <B>SetStackSize</B> methods. <BR>
In notificable threads Start() method fires CThread::CMD_INITIALIZE Command immediately after the WINDOWS thread was being established. CThread::CMD_INITIALIZE Command must be handled in the <B>ThreadHandler</B> method. <BR>
<BR>
This method is a synchronous method. It returns only if the WINDOWS thread has been successfully started or some significant error occurs. In this case the method returns immediately by throwing the appropriate CThreadException exception.</P>
<H3>See Also</H3>
<B><P>Stop</B> <BR>
<B>SetAttributes</B> <BR>
<B>SetStackSize</B> <BR>
<B>PostCommand</B> <BR>
<B>WaitForNotification</P>
</B><P>Back to <A HREF="#CThread">CThread</A></P>
<P><HR></P>
<P><A NAME="CThread__Stop"></P>
<H1>CThread::Stop</H1>
<B><P></A>BOOL</B> <B>CThread::Stop(DWORD&amp;</B> <I>dwExitCode</I><B>, DWORD</B> <I>dwTimeout</I> <B>= CThread::DW_INFINITE) </P>
</B><P>&#9;<B>throws CThreadException</B> of type: <BR>
&#9;CThreadException::CANNOT_SIGNAL_NOTIFICATION_OBJECT <BR>
<BR>
This method stops the WINDOWS running thread connected to CThread object. Used in the owner thread. In notificable threads Stop() method fires CThread::CMD_STOP Command immediately after the WINDOWS thread was asked to be stopped. CThread::CMD_STOP Command must be handled in <B>ThreadHandler</B> method to properly terminate the thread. If CThread object does not support Thread Notification, Stop() will wait until the WINDOWS thread actually terminates. In both modes the method returns only in the case when the WINDOWS thread actually terminates, the timeout interval elapses or some significant error occurs. Otherwise it waits (synchronous stopping). When an immediate return is required the user may set 'dwTimeout' variable to zero. In such case, however, the user is responsible to find out if the thread actually runs or is already stopped.</P>
<H3>Return Value</H3>
<P>Stop return status</P>
<DL>
<DT>TRUE </DT>
<DD>WINDOWS thread was properly stopped.</DD>
<DT>FALSE </DT>
<DD>WINDOWS thread was not stopped after the timeout interval elapsed.</DD>
</DL>
<H3>Parameters</H3>
<I><DL>
<DT>dwExitCode</I> </DT>
<DD>[out] WINDOWS thread exit code.</DD>
<I><DT>dwTimeout</DT>
</I><DD>[in] Timeout interval in tenths of second.</DD>
</DL>
<H3>See Also</H3>
<B><P>Start</B> <BR>
<B>PostCommand</B> <BR>
<B>WaitForNotification</B> </P>
<P>Back to <A HREF="#CThread">CThread</A></P>
<P><HR></P>
<P><A NAME="CThread__ThreadHandler"></P>
<H1>CThread::ThreadHandler</H1>
<B><P></A>DWORD</B> <B>CThread::ThreadHandler(void) </P>
</B><P>Main CThread-handler virtual abstract method declaration. <BR>
<BR>
This method is not implemented in the CThread class and must be implemented at least at one CThread-derived class in the CThread class hierarchy. <BR>
ThreadHandler() method concentrates the whole task that CThread thread has to execute. The implementation itself varies according to the type of CThread thread operating on this method (Trivial or Notificable Threads). <BR>
<BR>
For Notificable CThread threads the method contains a main loop with the <B>WaitForNotification</B> method resolving incoming commands fired from the owner thread. <BR>
<BR>
Detailed information as well as the examples how to implement, manage and use this method for both Trivial and Notificable CThread threads can be found in the 'Developer.doc' documentation.</P>
<H3>Return Value</H3>
<P>Thread task completion exit code. Developers may define an arbitrary exit code here except the WINDOWS predefined constant = STILL_ACTIVE (0x00000103L), which indicates the thread-is-alive status.</P>
<H3>See Also</H3>
<B><P>PostCommand</B> <BR>
<B>WaitForNotification</B> <BR>
<B>HandleCommandImmediately</B> </P>
<P>Back to <A HREF="#CThread">CThread</A></P>
<P><HR></P>
<P><A NAME="CThread__Unlock"></P>
<H1>CThread::Unlock</H1>
<B><P></A>void</B> <B>CThread::Unlock(void) </P>
</B><P>Marks the end of the critical code in Thread-Handler-Oriented synchronization mode. This method must be preceded by <B>Lock</B> method. <BR>
<BR>
<B><I>Important note: <BR>
</B></I>Both Lock() and Unlock() methods may be called from within the appropriate CThread thread only (represented by the ThreadHandler() method body). The methods should not be publiced and cannot be delegated to other threads - otherwise unpredictable deadlocks may arise.</P>
<H3>See Also</H3>
<B><P>Lock</P>
</B><P>Back to <A HREF="#CThread">CThread</A></P>
<P><HR></P>
<P><A NAME="CThread__WaitForActivityStatus"></P>
<H1>CThread::WaitForActivityStatus</H1>
<B><P></A>BOOL</B> <B>CThread::WaitForActivityStatus(int</B> <I>nActivityStatus</I><B>, DWORD</B> <I>dwTimeout</I> <B>= CThread::DW_INFINITE) </P>
</B><P>Waits until the desired CThread activity status is reached. Used in the owner thread. <BR>
This is a "good-servant-but-bad-master" method. The owner thread may fire an arbitrary command to the CThread object by the <B>PostCommand</B> method. That means, the <B>PostCommand</B> method fires a command and returns immediately. However, in some cases the owner thread may want to wait until the command is actually handled. For this reason the process may use this method which waits until the desired activity status is set in the <B>ThreadHandler</B> method. In this case the user is responsible to set the desired activity status in the <B>ThreadHandler</B> by the <B>SetActivityStatus</B> method. <BR>
Using of this method requires an implementation of the proper 'set-thread-activity-status' strategy. If, for example, the desired activity status is not properly set or is immediately rewritten by another value, the desired status is consequently never reached and the WaitForActivityStatus() method hangs. Sometimes the thread-synchronization locking mechanism is necessary. <BR>
WaitForActivityStatus() method returns only in the case when the desired activity status was actually reached or timeout interval elapsed. <BR>
<BR>
<I>Note: <BR>
</I>The Start() and Stop() methods do not have to be checked by this method. These methods are executed synchronously and return when the CThread-thread actually starts or stops. <BR>
<BR>
<B><I>Important note: <BR>
</B></I>If the CThread thread utilizes the main application message queue be aware of using this method. WaitForActivityStatus() method blocks the application thread from which is called and may not allow the CThread thread to complete its task requiring the message queue handling. This may lead to a deadlock. For more information see 'Developers.doc' documentation.</P>
<H3>Return Value</H3>
<P>TRUE if the desired acivity status is reached; FALSE if the timeout elapsed OR the thread has been prematurely terminated before the desired status was reached. Developers should always check this return value if there is no an explicit guaranty about the thread's lifetime.</P>
<H3>Parameters</H3>
<I><DL>
<DT>nActivityStatus</I> </DT>
<DD>[in] Desired CThread activity status that is to be reached.</DD>
<I><DT>dwTimeout</DT>
</I><DD>[in] Timeout interval in tenths of second.</DD>
</DL>
<H3>See Also</H3>
<B><P>SetActivityStatus</B> <BR>
<B>PostCommand</B> <BR>
<B>ThreadHandler</B> </P>
<P>Back to <A HREF="#CThread">CThread</A></P>
<P><HR></P>
<P><A NAME="CThread__WaitForNotification"></P>
<H1>CThread::WaitForNotification</H1>
<B><P></A>void</B> <B>CThread::WaitForNotification(int&amp;</B> <I>nIncomingCommand</I><B>, DWORD</B> <I>dwDefaultTimeout</I> <B>= CThread::DW_INFINITE) </P>
</B><P>The main <B>ThreadHandler</B> notification method. This method must be implemented inside the <B>ThreadHandler</B> method for Notificable CThread threads (see 'Developer.doc' documentation). <BR>
The method waits for incoming notifications (commands) fired from the owner thread via <B>PostCommand</B> method and returns immediately after the command was received. Returned command has to be handled in <B>ThreadHandler</B> method. <BR>
User may, however, set the timeout interval which forces the method to return after the timeout interval elapses. <BR>
<BR>
This method is valid only if CThread-derived class supports Thread Notification. Thread Notification can be established by adding SUPPORT_THREAD_NOTIFICATION macro in CThread-derived class constructor in which <B>ThreadHandler</B> method is actually implemented. Otherwise it has no any effect and the method returns immediately. <BR>
This method is usable after the CThread thread has been successfully started. <BR>
<BR>
Detailed information how to use this method as well as how to manage fired commands in the thread task handler can be found in the 'Developer.doc' documentation.</P>
<H3>Parameters</H3>
<I><DL>
<DT>nIncomingCommand</I> </DT>
<DD>[out] Reference to the Command ID that was fired from within the owner thread.</DD>
<I><DT>dwDefaultTimeout</DT>
</I><DD>[in] Timeout interval in 'miliseconds'.</DD>
</DL>
<H3>See Also</H3>
<B><P>PostCommand</B> <BR>
<A HREF="#CThread">CThread Predefined Commands</A> </P>
<P>Back to <A HREF="#CThread">CThread</A></P>
<P><HR></P>
<P><A NAME="CThread___7eCThread"></P>
<H1>CThread::~CThread</H1>
<B><P></A>CThread::~CThread(void) </P>
</B><P>CThread destructor. CThread destructor kills the running WINDOWS thread that was not previously stopped and closes the CThread notification mode.</P>
<P>Back to <A HREF="#CThread">CThread</A></P>
<P><HR></P>
<P><A NAME="CThreadException"></P>
<H1>CThreadException class</H1>
<P></A>CThreadException <B>class CThreadException: public CException</P>
</B><P>CThreadException Class Members</P>
<H3>Class Members</H3>
<B><P><BR>
Public Members:</B> </P>
<DL>
<DT><A HREF="#CThreadException__CThreadException">CThreadException</A><B>(CThread* pThread = NULL)</B> </DT>
<DD>CThreadException Constructor</DD>
<DT><A HREF="#CThreadException__CThreadException_1">CThreadException</A><B>(CThread* pThread, CString strErrorMsg, int nExceptionType = CThreadException::UNKNOWN_ERROR)</B> </DT>
<DD>CThreadException Constructor</DD>
<DT><A HREF="#CThreadException__CThreadException_2">CThreadException</A><B>(CThread* pThread, UINT nErrorMsgID, int nExceptionType = CThreadException::UNKNOWN_ERROR)</B> </DT>
<DD>CThreadException Constructor</DD>
<B><DT>CThread*</B> <A HREF="#CThreadException__GetThread">GetThread</A><B>() const</B> </DT>
<DD>Get CThread Object</DD>
<B><DT>CString</B> <A HREF="#CThreadException__GetErrorMsg">GetErrorMsg</A><B>() const</B> </DT>
<DD>Get Error Message</DD>
<B><DT>int</B> <A HREF="#CThreadException__GetType">GetType</A><B>() const</B> </DT>
<DD>Get Type of Thrown Exception</DD>
<B><DT>virtual int</B> <A HREF="#CThreadException__ReportError">ReportError</A><B>(UINT nType = MB_OK, UINT nMessageID = 0)</B> </DT>
<DD>Report Error</DD>
<B><DT>static CString</B> <A HREF="#CThreadException__GetLastSystemErrorMsg">GetLastSystemErrorMsg</A><B>(DWORD dwSysErrorCode)</B> </DT>
<DD>Get String Representation Corresponding to the System Error Code</DD>
</DL>
<H3>Class Members</H3>
<B><P><BR>
Protected Members:</B> </P>
<B><DL>
<DT>void</B> <A HREF="#CThreadException__SetThread">SetThread</A><B>(CThread* pThread)</B> </DT>
<DD>Set CThread Object Throwing an Exception</DD>
<B><DT>void</B> <A HREF="#CThreadException__SetErrorMsg">SetErrorMsg</A><B>(CString strErrorMsg)</B> </DT>
<DD>Set Error Message</DD>
<B><DT>void</B> <A HREF="#CThreadException__SetErrorMsg">SetErrorMsg</A><B>(UINT nErrorMsgID)</B> </DT>
<DD>Set Error Message</DD>
<B><DT>void</B> <A HREF="#CThreadException__SetType">SetType</A><B>(int nType)</B> </DT>
<DD>Set Exception Type</DD>
</DL>
<P><HR></P>
<P><A NAME="CThreadException__CThreadException_1"></P>
<H1>CThreadException::CThreadException</H1>
<B><P></A>CThreadException::CThreadException(CThread*</B> <I>pThread</I><B>, CString</B> <I>strErrorMsg</I><B>, int</B> <I>nExceptionType</I> <B>= CThreadException::UNKNOWN_ERROR) </P>
</B><P>CThreadException constructor. General CThreadException class intended to be used by CThread-derived classes. CThread-derived methods should always throw CThreadException exceptions. To distinguish the origin of thrown exceptions the user should use the type of CThreadException exception. CThread methods use predefined CThreadException types but the user may define own types in CThread-derived class. Predefined types used in CThread class are described in 'Parameters' section.</P>
<H3>Parameters</H3>
<I><DL>
<DT>pThread</I> </DT>