cthread.htm

A class that allows the simple implementation of worker threads

</B><P>CThread constructor. User may pass a so-called 'Owner object' to the CThread class. The Owner object is an arbitrary object claimed to be an owner of CThread object. In such way the Owner object may be notified by CThread object while running the thread. Optional LPARAM parameter allows the user to pass an additional useful information. It's up to the developer's responsibility how to interpret and implement the Owner object parameters in CThread-derived class. CThread class itself just stores the passed values.The mentioned parameters may be also set up or read after CThread object construction by calling the <B>SetOwnerParams</B> and <B>GetOwnerParams</B> methods. <BR>
<BR>
While constructing CThread object no any WINDOWS thread is being started.</P>
<H3>Parameters</H3>
<I><DL>
<DT>pOwnerObject</DT>
</I><DD>[in] CThread Owner object.</DD>
<I><DT>lParam</DT>
</I><DD>[in] General parameter passed to CThread object.</DD>
</DL>
<H3>See Also</H3>
<B><P>SetOwnerParams</B> <BR>
<B>GetOwnerParams</B> </P>
<P>Back to <A HREF="#CThread">CThread</A></P>
<P><HR></P>
<P><A NAME="CThread__GetActivityStatus"></P>
<H1>CThread::GetActivityStatus</H1>
<B><P></A>int</B> <B>CThread::GetActivityStatus(void) </P>
</B><P>Gets the current CThread activity status. This method is normally called from within the owner thread to obtain the current activity of the owned thread. <BR>
CThread class offers the predefined values as seen in the 'Return Value' section.</P>
<H3>Return Value</H3>
<P>Current CThread activity status.</P>
<DL>
<DT>CThread::THREAD_CREATED </DT>
<DD>Thread was successfully created (activity status set by the Start() method).</DD>
<DT>CThread::THREAD_STOPPED </DT>
<DD>Thread is stopped.</DD>
<DT>CThread::THREAD_RUNNING </DT>
<DD>Thread is running.</DD>
<DT>CThread::THREAD_PAUSED </DT>
<DD>Thread is paused.</DD>
<DT>CThread::THREAD_CONTINUING </DT>
<DD>Thread is continuing.</DD>
<DT>CThread::THREAD_PENDING </DT>
<DD>Thread is pending.</DD>
<DT>CThread::THREAD_USER_ACTIVITY </DT>
<DD>Base offset for user-defined activity statuses.</DD>
</DL>
<H3>See Also</H3>
<B><P>SetActivityStatus</P>
</B><P>Back to <A HREF="#CThread">CThread</A></P>
<P><HR></P>
<P><A NAME="CThread__GetAttributes"></P>
<H1>CThread::GetAttributes</H1>
<B><P></A>SECURITY_ATTRIBUTES</B> <B>CThread::GetAttributes(void) </P>
</B><P>Gets the WINDOWS thread security attributes (see WINDOWS Threads in Microsoft MSDN documentation).</P>
<H3>Return Value</H3>
<P>Fills up the SECURITY_ATTRIBUTES structure with valid data. If the WINDOWS thread is not created the SECURITY_ATTRIBUTES structure is null-reset.</P>
<H3>See Also</H3>
<B><P>SetAttributes</P>
</B><P>Back to <A HREF="#CThread">CThread</A></P>
<P><HR></P>
<P><A NAME="CThread__GetExitCode"></P>
<H1>CThread::GetExitCode</H1>
<B><P></A>DWORD</B> <B>CThread::GetExitCode(void) </P>
</B><P>Gets CThread thread exit code - a value that is returned by <B>ThreadHandler</B> method - or, generally, it's a return value of the thread controlling function. <BR>
GetExitCode() method returns the valid exit code regardless the WINDOWS thread is alive or not.</P>
<H3>Return Value</H3>
<P>CThread thread exit code.</P>
<P>Back to <A HREF="#CThread">CThread</A></P>
<P><HR></P>
<P><A NAME="CThread__GetHandle"></P>
<H1>CThread::GetHandle</H1>
<B><P></A>HANDLE</B> <B>CThread::GetHandle(void) </P>
</B><P>Gets the WINDOWS thread handle (see WINDOWS Threads in Microsoft MSDN documentation).</P>
<H3>Return Value</H3>
<P>Handle of WINDOWS thread or NULL if the thread is not created.</P>
<P>Back to <A HREF="#CThread">CThread</A></P>
<P><HR></P>
<P><A NAME="CThread__GetID"></P>
<H1>CThread::GetID</H1>
<B><P></A>DWORD</B> <B>CThread::GetID(void) </P>
</B><P>Gets the WINDOWS thread ID (see WINDOWS Threads in Microsoft MSDN documentation).</P>
<H3>Return Value</H3>
<P>WINDOWS thread ID or 0 if the thread is not created.</P>
<P>Back to <A HREF="#CThread">CThread</A></P>
<P><HR></P>
<P><A NAME="CThread__GetOwnerParams"></P>
<H1>CThread::GetOwnerParams</H1>
<B><P></A>void</B> <B>CThread::GetOwnerParams(void*&amp;</B> <I>pOwnerObject</I><B>, LPARAM&amp;</B> <I>lParam</I><B>) </P>
</B><P>Retrieves the CThread Owner object parameters.</P>
<H3>Parameters</H3>
<I><DL>
<DT>pOwnerObject</I> </DT>
<DD>[out] Reference to the CThread Owner object being retrieved.</DD>
<I><DT>lParam</I> </DT>
<DD>[out] Reference to the LPARAM parameter being retrieved.</DD>
</DL>
<H3>See Also</H3>
<B><P>SetOwnerParams</P>
</B><P>Back to <A HREF="#CThread">CThread</A></P>
<P><HR></P>
<P><A NAME="CThread__GetPriority"></P>
<H1>CThread::GetPriority</H1>
<B><P></A>int</B> <B>CThread::GetPriority(void) </P>
</B><P>This method gets the WINDOWS thread priority. <BR>
<BR>
GetPriority() just encapsulates the WINDOWS GetThreadPriority() function. For more information see Win32 SDK Programmer's Reference.</P>
<H3>Return Value</H3>
<P>Current WINDOWS thread priority or THREAD_PRIORITY_ERROR_RETURN if an error occurs. 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</P>
<H3>See Also</H3>
<B><P>SetPriority</P>
</B><P>Back to <A HREF="#CThread">CThread</A></P>
<P><HR></P>
<P><A NAME="CThread__GetStackSize"></P>
<H1>CThread::GetStackSize</H1>
<B><P></A>DWORD</B> <B>CThread::GetStackSize(void) </P>
</B><P>Gets the WINDOWS thread stack size (see WINDOWS Threads).</P>
<H3>Return Value</H3>
<P>WINDOWS thread stack size.</P>
<H3>See Also</H3>
<B><P>SetStackSize</P>
</B><P>Back to <A HREF="#CThread">CThread</A></P>
<P><HR></P>
<P><A NAME="CThread__HandleCommandImmediately"></P>
<H1>CThread::HandleCommandImmediately</H1>
<B><P></A>void</B> <B>CThread::HandleCommandImmediately(int</B> <I>nCommand</I><B>) </P>
</B><P>This helper method is used for immediate sending of CThread commands fired from within the <B>ThreadHandler</B> method in the actual Notificable CThread thread. <BR>
<BR>
In Notificable CThread threads the <B>ThreadHandler</B> method contains the 'case' switch in which incoming commands are handled. In some cases the resolved and executed command has to immediately invoke (and handle) another internal command in this 'case' switch to properly complete its task. Users should not use the <B>PostCommand</B> oriented methods in such case because the command queue may not be empty. This queue may be namely filled up by another thread and, thus, an additional internal completion command will be just posted at the end of the queue. In consequence, the next handled command will be the first pending in the queue and not that one intended to be handled immediately. <BR>
For this reason a special command-handling mechanism is desired and is supported by this method. Requested internal command to be handled immediately is stored in the standard CThread command queue as the first pending command bypassing all already stored commands. Restoring of internal commands is accomplished by the same method as other standard commands, by the <B>WaitForNotification</B> method. The difference is that an internal command is handled always as the first command. <BR>
<BR>
As an example we may consider the starting of a notificable CThread thread. After starting the thread the CMD_INITIALIZE command is fired as the first command. This command is handled in the corresponding 'case' branch in the <B>ThreadHandler</B> method, in which the basic initialization is accomplished. As the next logical step after the initialization is to get run the main thread task immediately. Thus, before leaving the initialization 'case' branch the HandleCommandImmediately(CMD_RUN) method is called. CMD_RUN command fired in such manner bypasses all pending commands and is returned (via the <B>WaitForNotification</B> method) back to the 'case' switch as the following command. All pending commands will be resolved afterwards. <BR>
<BR>
The term 'internal commands' means just another kind of firing and handling of standard commands. Users use the same commands (more precisely, command IDs) as in the <B>PostCommand</B> method. <BR>
<BR>
This method is valid only if CThread-derived class supports Thread Notification and the CThread thread has been successfully started. Otherwise it has no any effect. <BR>
<BR>
<B><I>Important note: <BR>
</B></I>This method should be called only in the CThread thread (in the <B>ThreadHandler</B> method).</P>
<H3>Return Value</H3>
<P>TRUE if the command was inserted in the command queue.</P>
<H3>Parameters</H3>
<I><DL>
<DT>nCommand</I> </DT>
<DD>[in] Desired command to be handled immediately.</DD>
</DL>
<H3>See Also</H3>
<B><P>ThreadHandler</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__IsAlive"></P>
<H1>CThread::IsAlive</H1>
<B><P></A>BOOL</B> <B>CThread::IsAlive(void) </P>
</B><P>Checks if the current CThread thread is still alive.</P>
<H3>Return Value</H3>
<P>TRUE if the thread is alive otherwise FALSE.</P>
<P>Back to <A HREF="#CThread">CThread</A></P>
<P><HR></P>
<P><A NAME="CThread__Kill"></P>
<H1>CThread::Kill</H1>
<B><P></A>void</B> <B>CThread::Kill(DWORD</B> <I>dwExitCode</I> <B>= CThread::DW_OK, BOOL</B> <I>bCloseAnyway</I> <B>= FALSE</B> <B>) </P>
</B><P>&#9;<B>throws CThreadException</B> of type: <BR>
&#9;CThreadException::CANNOT_TERMINATE_THREAD <BR>
<BR>
This method kills the WINDOWS thread connected to CThread object. Used in the owner thread. The method returns after the WINDOWS thread has been actually killed, or some significant error occurs. <BR>
CThread threads should always terminate either by leaving the thread-controlling function attached to the WINDOWS thread or by calling <B>Stop</B> method in notificable threads. <BR>
Killing threads is the last-chance stopping mechanism and should be used in emergency cases only. While killing the thread by using this method the <B>OnKill</B> virtual method is invoked to provide the last chance for making necessary unallocations specific to the thread being killed. <BR>
<BR>
For more information see 'Terminating WINDOWS Threads' in Microsoft MSDN documentation.</P>
<H3>Parameters</H3>
<I><DL>
<DT>dwExitCode</DT>
</I><DD>[in] Suggested WINDOWS thread exit code. (see 'TerminateThread()' WINDOWS function in Microsoft MSDN documentation).</DD>
<I><DT>bCloseAnyway</DT>
</I><DD>[in] Closes the CThread-thread regardless the thread has been destroyed or not. By using this parameter the CThread-thread is correctly closed and unregistered even if the corresponding WINDOWS thread cannot be properly terminated. Users should call this method again (using 'bCloseAnyway = TRUE') if it's not possible to recover the termination failure - best way is to call it in the 'catch' clause for an exception thrown by this method. By enabling this parameter no any CThreadException exception is thrown.</DD>
</DL>
<H3>See Also</H3>
<B><P>OnKill</B> <BR>
<B>Stop</B> </P>
<P>Back to <A HREF="#CThread">CThread</A></P>
<P><HR></P>
<P><A NAME="CThread__Lock"></P>
<H1>CThread::Lock</H1>
<B><P></A>void</B> <B>CThread::Lock(void) </P>
</B><P>Marks the beginning of the critical code to be 'Thread-Handler-Oriented' synchronized. This special synchronization mechanism allows to lock the critical code and make it exclusive for the first thread reaching this method. Consequently all other CThread objects that operate on the same <B>ThreadHandler</B> are blocked until the thread unlocks the critical code. Other threads operating on the different <B>ThreadHandler</B> are not blocked and are synchronized in exactly same way in their own group. Thus, CThreads objects can be splitted into the groups operating on the same <B>ThreadHandler</B> method. Each group is synchronized independently to each other. <BR>
All managing concerning this kind of synchronization is done automatically, users do not care about any aspect of synchronization. All they have to do is to use the Lock() and <B>Unlock</B> methods to bound the critical code. <BR>
Thread-Handler-Oriented synchronization is, however, not always usable. If the user needs to lock the shared common object that cannot be accessed simultaneously under any circumstances, he should use <B>ProcessLock</B> and <B>ProcessUnlock</B> methods. These methods guarantee the process-exclusive access to the critical code (but not an inter-process exclusive access). <BR>
Lock() method must be followed by <B>Unlock</B> method in a way to prevent eventual deadlocks. <BR>
<BR>
This kind of synchronization can be established by adding SUPPORT_THREAD_SYNCHRONIZATION(<I>ClassName</I>) macro to the user CThread-derived class constructor in which <B>ThreadHandler</B> method is implemented. <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>Unlock</B> <BR>
<B>ProcessLock</B> <BR>
<B>ProcessUnlock</P>
</B><P>Back to <A HREF="#CThread">CThread</A></P>
<P><HR></P>
<P><A NAME="CThread__OnKill"></P>
<H1>CThread::OnKill</H1>
<B><P></A>void</B> <B>CThread::OnKill(void) </P>
</B><P>Virtual method that is invoked while the <B>Kill</B> method is being executed. OnKill() is called after the WINDOWS thread has been actually destroyed. Users may unallocate all extra resources that were needed in the CThread-derived instance object. <BR>
Default version does nothing users may, however, implement this method in their CThread-derived class. <BR>
All extra resources should be referenced through CThread-derived class member data, because in the moment of OnKill() execution all local variables in the <B>ThreadHandler</B> method are not more valid - thread is already destroyed and its controlling function is detached. <BR>
OnKill() virtual method doesn't have to call the base CThread::OnKill() method. <BR>
<BR>
Note 1: <BR>
Users should unallocate (detach, close...) resources that rely only to the current instance of CThread-derived object that is being killed. Keep in mind that in some cases the same resources may be used by other running instances as well. In this situation the user is responsible to clean up such shared resources. <BR>
<BR>
Note 2: <BR>