cthread.htm

A class that allows the simple implementation of worker threads

OnKill() method doesn't have to be invoked under any circumstances. If the thread regularly finished before the <B>Kill</B> method has been called the <B>Kill</B> method does nothing, thus, OnKill() method is not invoked. OnKill() is normally used as a last chance emergency clean-up.</P>
<H3>See Also</H3>
<B><P>Kill</B> <BR>
<B>ThreadHandler</P>
</B><P>Back to <A HREF="#CThread">CThread</A></P>
<P><HR></P>
<P><A NAME="CThread__OpenProcessLocking"></P>
<H1>CThread::OpenProcessLocking</H1>
<B><P></A>static void</B> <B>CThread::OpenProcessLocking(void) </P>
</B><P>Static method that opens the process synchronization. After the first call the process synchronization is opened. Additional call of this method has no any effect - the synchronization remains opened. The synchronization itself is accomplished by calling <B>ProcessLock</B> and <B>ProcessUnlock</B> methods between which is the critical code that is to be executed process-exclusively. Opened process-synchronization should be finally closed by <B>CloseProcessLocking</B> method. <BR>
This locking mechanism does not support an inter-process synchronization. <BR>
<BR>
As a static method may be used wherever in the code without constructing any CThread object.</P>
<H3>See Also</H3>
<B><P>CloseProcessLocking</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__Pause"></P>
<H1>CThread::Pause</H1>
<B><P></A>void</B> <B>CThread::Pause(void) </P>
</B><P>&#9;<B>throws CThreadException</B> of type: <BR>
&#9;CThreadException::CANNOT_SIGNAL_NOTIFICATION_OBJECT <BR>
<BR>
Fires CThread::CMD_PAUSE Command and notifies CThread object. Used in the owner thread. This method is valid only if CThread-derived class supports Thread Notification and CThread thread has been successfully started. Otherwise it has no any effect. <BR>
To use the method properly the <B>ThreadHandler</B> method must be able to handle CThread::CMD_PAUSE Command as well as implement the specific task corresponding to this command. <BR>
This method returns immediately after the command has been fired. The owner thread may, however, wait for completion of the corresponding task by using the paradigm described in the <B>WaitForActivityStatus</B> method. <BR>
<BR>
This method is a helper method simplifying the semantic control of Notificable CThread threads acting in a 'scheduler' or 'service' - like manner. It's up to the developer's responsibility how to interpret and implement (or refuse at all) this method. <BR>
<BR>
For more information see 'Developer.doc' documentation.</P>
<H3>See Also</H3>
<B><P>PostCommand</B> <BR>
<B>WaitForActivityStatus</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__PostCommand"></P>
<H1>CThread::PostCommand</H1>
<B><P></A>void</B> <B>CThread::PostCommand(int</B> <I>nCommand</I><B>) </P>
</B><P>&#9;<B>throws CThreadException</B> of type: <BR>
&#9;CThreadException::CANNOT_SIGNAL_NOTIFICATION_OBJECT <BR>
<BR>
PostCommand() method is the base method with which the owner thread may manage notificable CThread objects. By calling PostCommand() the owner thread fires desired commands to the thread belonging to CThread object. The thread consequently receives a signal to leave <B>WaitForNotification</B> method which is used in the <B>ThreadHandler</B> method (implemented in CThread-derived class) and restores the command fired from the owner thread. Obtained command is immediately executed in the thread body. Developer is responsible to handle the fired command in the <B>ThreadHandler</B> method. PostCommand() mechanism is the recommended way how to manage CThread objects. It's also the base concept for other command-oriented methods like Start(), Pause(), Continue(), Reset() or Stop(). Each of these methods sets the appropriate command and sends a signal to the thread which handles the command. Using this paradigm the thread notifications coming from outside keep the synchronization features provided by CThread class. <BR>
PostCommand() method supports so-called 'stackable commands' which allows the thread-owner process to pump all desired commands at one step. All such commands will be resolved in the thread task body in exactly the same order as they were pumped in the owner thread (cyclic stack mechanism). <BR>
User may define an arbitrary count of user-specific commands. For this purpose the CThread class offers the start offset command ID: CThread::CMD_USER_COMMAND. All command IDs below this value is reserved by CThread class and should not be used. In this case the user is responsible to handle the user-specific command in the <B>ThreadHandler</B> method in the CThread-derived class. <BR>
<BR>
This method is valid only if CThread-derived class supports Thread Notification. Thread Notification may be established by adding SUPPORT_THREAD_NOTIFICATION macro in the CThread-derived class constructor in which <B>ThreadHandler</B> method is actually implemented. Otherwise PostCommand() method has no any effect. <BR>
This method is usable after the CThread thread has been successfully started. <BR>
<BR>
PostCommand() returns immediately after the command has been actually fired. The owner thread may, however, wait for completion of the task corresponding to the fired command (implemented in the <B>ThreadHandler</B> method) by using the paradigm described in the <B>WaitForActivityStatus</B> method. <BR>
<BR>
Detailed information how to use this method as well as how to manage fired commands in the thread task body can be found in the 'Developer.doc' documentation.</P>
<H3>Parameters</H3>
<I><DL>
<DT>nCommand</I> </DT>
<DD>[in] Desired command fired from within the owner thread that is to be executed in CThread task body - <B>ThreadHandler</B>.</DD>
</DL>
<H3>See Also</H3>
<B><P>WaitForNotification</B> <BR>
<B>WaitForActivityStatus</B> <BR>
<B>HandleCommandImmediately</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__ProcessLock"></P>
<H1>CThread::ProcessLock</H1>
<B><P></A>static void</B> <B>CThread::ProcessLock(void) </P>
</B><P>Static method that marks the beginning of the critical code that is to be executed process-exclusively. <BR>
<B>ProcessUnlock</B> method is the counterpart of the ProcessLock() method which bounds the end of the critical code. Both methods should be used in a way to prevent eventual deadlocks. Before using the method the process-synchronization must be opened by <B>OpenProcessLocking</B> method. <BR>
This locking mechanism does not support an inter-process synchronization. <BR>
<BR>
As a static method may be used wherever in the code without constructing any CThread object.</P>
<H3>See Also</H3>
<B><P>OpenProcessLocking</B> <BR>
<B>CloseProcessLocking</B> <BR>
<B>ProcessUnlock</P>
</B><P>Back to <A HREF="#CThread">CThread</A></P>
<P><HR></P>
<P><A NAME="CThread__ProcessUnlock"></P>
<H1>CThread::ProcessUnlock</H1>
<B><P></A>static void</B> <B>CThread::ProcessUnlock(void) </P>
</B><P>Static method that marks the end of the critical code that is to be executed process-exclusively. <BR>
<B>ProcessLock</B> method is the counterpart of ProcessUnlock() method which bounds the start of the critical code. Both methods should be used in a way to prevent eventual deadlocks. Before using the method the process-synchronization must be opened by <B>OpenProcessLocking</B> method. <BR>
This locking mechanism does not support an inter-process synchronization. <BR>
<BR>
As a static method may be used wherever in the code without constructing any CThread object.</P>
<H3>See Also</H3>
<B><P>OpenProcessLocking</B> <BR>
<B>CloseProcessLocking</B> <BR>
<B>ProcessLock</P>
</B><P>Back to <A HREF="#CThread">CThread</A></P>
<P><HR></P>
<P><A NAME="CThread__Reset"></P>
<H1>CThread::Reset</H1>
<B><P></A>void</B> <B>CThread::Reset(void) </P>
</B><P>&#9;<B>throws CThreadException</B> of type: <BR>
&#9;CThreadException::CANNOT_SIGNAL_NOTIFICATION_OBJECT <BR>
<BR>
Fires CThread::CMD_RESET Command and notifies CThread object. Used in the owner thread. This method is valid only if CThread-derived class supports Thread Notification and CThread thread has been successfully started. Otherwise it has no any effect. <BR>
To use the method properly the <B>ThreadHandler</B> method must be able to handle CThread::CMD_RESET Command as well as implement the specific task corresponding to this command. <BR>
This method returns immediately after the command has been fired. The owner thread may, however, wait for completion of the corresponding task by using the paradigm described in the <B>WaitForActivityStatus</B> method. <BR>
<BR>
This method is a helper method simplifying the semantic control of Notificable CThread threads acting in a 'scheduler' or 'service' - like manner. It's up to the developer's responsibility how to interpret and implement (or refuse at all) this method. <BR>
<BR>
For more information see 'Developer.doc' documentation.</P>
<H3>See Also</H3>
<B><P>PostCommand</B> <BR>
<B>WaitForActivityStatus</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__ResetCommands"></P>
<H1>CThread::ResetCommands</H1>
<B><P></A>void</B> <B>CThread::ResetCommands(void) </P>
</B><P>Cancels all thread-notification commands fired by the <B>PostCommand</B> method and waiting in the queue to be processed. <BR>
This method is useful when the last important command is intended to be sent to the CThread object. To ensure that no any other command is to be processed, the owner thread may cancel all such commands pending in the CThread command queue.</P>
<H3>See Also</H3>
<B><P>PostCommand</B> <BR>
<B>WaitForNotification</P>
</B><P>Back to <A HREF="#CThread">CThread</A></P>
<P><HR></P>
<P><A NAME="CThread__Run"></P>
<H1>CThread::Run</H1>
<B><P></A>void</B> <B>CThread::Run(void) </P>
</B><P>&#9;<B>throws CThreadException</B> of type: <BR>
&#9;CThreadException::CANNOT_SIGNAL_NOTIFICATION_OBJECT <BR>
<BR>
Fires CThread::CMD_RUN Command and notifies CThread object. Used in the owner thread. This method is valid only if CThread-derived class supports Thread Notification and CThread thread has been successfully started. Otherwise it has no any effect. <BR>
To use the method properly the <B>ThreadHandler</B> method must be able to handle CThread::CMD_RUN Command as well as implement the specific task corresponding to this command. <BR>
This method returns immediately after the command has been fired. The owner thread may, however, wait for completion of the corresponding task by using the paradigm described in the <B>WaitForActivityStatus</B> method. <BR>
<BR>
This method is a helper method simplifying the semantic control of Notificable CThread threads acting in a 'scheduler' or 'service' - like manner. It's up to the developer's responsibility how to interpret and implement (or refuse at all) this method. <BR>
<BR>
For more information see 'Developer.doc' documentation.</P>
<H3>See Also</H3>
<B><P>PostCommand</B> <BR>
<B>WaitForActivityStatus</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__SetActivityStatus"></P>
<H1>CThread::SetActivityStatus</H1>
<B><P></A>void</B> <B>CThread::SetActivityStatus(int</B> <I>nActivityStatus</I><B>) </P>
</B><P>Sets CThread activity status. CThread activity status describes the current CThread activity. This method should be meaningfully used in the <B>ThreadHandler</B> CThread-derived class method. to inform the owner thread about the current CThread object activity. Owner thread may call <B>GetActivityStatus</B> method to restore the current status. <BR>
CThread class offers the predefined values as seen in the 'Parameters' section. <BR>
<BR>
For more information how to use this method see 'Developer.doc' documentation.</P>
<H3>Parameters</H3>
<I><DL>
<DT>nActivityStatus</I> </DT>
<DD>[in] CThread activity status.</DD>
<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>GetActivityStatus</P>
</B><P>Back to <A HREF="#CThread">CThread</A></P>
<P><HR></P>
<P><A NAME="CThread__SetAttributes"></P>
<H1>CThread::SetAttributes</H1>
<B><P></A>void</B> <B>CThread::SetAttributes(LPSECURITY_ATTRIBUTES</B> <I>lpThreadAttributes</I> <B>= NULL) </P>
</B><P>Sets the WINDOWS thread security attributes (see WINDOWS Threads in Microsoft MSDN documentation). <BR>
Thread attributes - if necessary - should be set before CThread thread is started.</P>
<H3>Parameters</H3>
<I><DL>
<DT>lpThreadAttributes</DT>
</I><DD>[in] Pointer to the security attributes structure.</DD>
<DT>SECURITY_ATTRIBUTES structure may be created temporarily. Passing its pointer to this method means copying the structure contents to the internal data space of CThread object. Therefore, thread attributes remain valid regardless the SECURITY_ATTRIBUTES structure (which 'lpThreadAttributes' parameter points to) exists or not. </DT>
</DL>
<H3>See Also</H3>
<B><P>GetAttributes</B> </P>
<P>Back to <A HREF="#CThread">CThread</A></P>
<P><HR></P>
<P><A NAME="CThread__SetOwnerParams"></P>
<H1>CThread::SetOwnerParams</H1>
<B><P></A>void</B> <B>CThread::SetOwnerParams(void*</B> <I>pOwnerObject</I><B>, LPARAM</B> <I>lParam</I> <B>= 0) </P>
</B><P>Sets CThread Owner object parameters. 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 can be read after the CThread object construction by calling the <B>GetOwnerParams</B> method.</P>
<H3>Parameters</H3>
<I><DL>
<DT>pOwnerObject</I> </DT>
<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>GetOwnerParams</B> </P>
<P>Back to <A HREF="#CThread">CThread</A></P>
<P><HR></P>
<P><A NAME="CThread__SetPriority"></P>
<H1>CThread::SetPriority</H1>
<B><P></A>DWORD</B> <B>CThread::SetPriority(int</B> <I>nPriority</I> <B>= THREAD_PRIORITY_NORMAL) </P>
</B><P>This method sets the WINDOWS thread priority. The priority may be set after the WINDOWS thread has been started. <BR>
SetPriority() just encapsulates the WINDOWS SetThreadPriority() function. For more information see Win32 SDK Programmer's Reference.</P>
<H3>Return Value</H3>
<P>TRUE - the priority was properly set. <BR>
FALSE - the priority was not set or the thread is not runnning.</P>
<H3>Parameters</H3>
<I><DL>