A class for worker threads

.
Copyright ) 1999, Bratislava, Slovakia, Europe

Worker Thread developing Guidelines

CThread class written in Microsoft Visual C++ is a wrapper class that constitutes the base for the comfortable WINDOWS worker thread handling in the MFC environment. CThread itself is an abstract class from which user thread-specific classes have to be derived. CThread class offers the basic opportunities how to define, implement and handle thread objects. Most functionality is done in this base class, the developer is just responsible to implement the thread-specific task and handle incoming notifications fired from the owner of the thread. CThread class is fully compliant to the Object-Oriented Paradigm.

CThread Class Conception

Thread-task paradigms

CThread abstract class defines conception describing the main requirements regarding the thread handling. There are two main paradigms concerning thread task implementation:

Trivial Threads

Thread task is a simple sequence of commands that are to be done. After starting the thread, the thread terminates after completing the whole task. No any notification is accepted from outside and no any activity status is provided for the owner application. The only way how to communicate with a thread is to use a user-defined object which is incorporated in the thread handler body and call it’s methods from outside. This communication, however, is not thread safe, no any synchronization or an effective runtime notification feature is guaranteed. It’s up to the developer responsibility to solve all risky consequences coming from the concurrent thread handling. Although it’s easy to implement this conception, it’s recommended for simple, non-critical or single tasks only. Thread supporting this paradigm is called Trivial Thread.

Notificable Threads

Thread task is application-sensitive and listens to the application commands. In this case the thread task is a loop in which thread waits for incoming notifications (commands). After receiving a notification (command) the thread execute this command. Simultaneously it should set the current thread activity status to inform the thread-owner process. This is the most recommended paradigm how to establish thread tasks. This thread is called Notificable Thread.

CThread class supports both paradigms but prefers and emphasizes developers to use the second one.

Thread Synchronization

Thread-Handler-Oriented Synchronization

CThread derived classes may utilize the synchronization feature which is implemented in the base CThread class. That means, developers do not deal too much with synchronization among thread objects using the same thread-task handler (the ThreadHandler() method). Developers just use Lock() or Unlock() CThread methods to lock the critical code that is to be executed exclusively in the ThreadHandler() method. Developers may, however, omit the synchronization feature and define the CThread derived class, which does not support this kind of synchronization. It's up to the developer’s responsibility to implement non-critical thread task or instantiate just one thread object of such class. Each CThread derived class requiring its own synchronization must declare this feature explicitly (this can be automatically established while working with Worker Thread Class Generator Wizard).

This kind of synchronization is so-called Thread-Handler-Oriented synchronization. Suppose a developer utilizes two CThread derived classes CThreadDerived1 and CThreadDerived2 and each class implements its own ThreadHandler() method. Let Thread11 and Thread12 are the instantiated objects of the class CThreadDerived1 and Thread21 and Thread22 are the objects of the class CThreadDerived2. Thread11 is synchronized with Thread12 but not with Thread21 or Thread22 (and vice versa). All thread objects of the CThreadDerived1 class are synchronized among each other (as well as all objects of the CThreadDerived2 class) but the synchronization of the CThreadDerived1 objects is fully independent to the synchronization of the CThreadDerived2 objects.

On the other hand, if the CThreadDerived3 class is derived from the CThreadDerived2 but do not implement the ThreadHandler() method (uses the handler implemented in the CThreadDerived2 class), the CThreadDerived3 objects are automatically synchronized with the CThreadDerived2 objects and vice versa.

Important Note 1:

If the CThreadDerived2 class implements the ThreadHandler() method and the CThreadDerived3 class (derived from CThreadDerived2) does not implement its own handler (utilizes the same thread handler as the CThreadDerived2 class does – see the next article) CThreadDerived3 inherits the synchronization ability from CThreadDerived2. That means if CThreadDerived2 supports the synchronization, CThreadDerived3 objects utilizes the same synchronization as CThreadDerived2 objects. If CThreadDerived2 is not intended to use the synchronization at all, CThreadDerived3 objects cannot utilize the synchronization as well.

Although an establishing of the synchronization in CThreadDerived3 objects in such case is theoretically possible (by rewriting the generated code) developers should never do that. Note that thread objects of both types use the same thread handler, which means in consequence, that some of them will be synchronized and some not. This conceptual idea was primarily refused and was being claimed as forbidden.

Single Thread Object Synchronization

CThread class itself implements an internal synchronization. This is the special synchronization feature that is not visible from within the thread-owner process. Internal synchronization does not impact Lock() or Unlock() mechanism mentioned in the above paragraph under any circumstances. The benefit of the internal synchronization is the synchronized access to the critical CThread internal methods while accessing to one instance of CThread object asynchronously.

This kind of synchronization is sometimes called Single Thread Object Synchronization. If, for example, the childThread is an instance of CThread-derived class, which is shared by two other (arbitrary) threads parentThread1 and parentThread2, both these parent threads operate on the childThread asynchronously. The Internal Synchronization implemented in CThread class guarantees that all critical childThread methods will be resolved properly regardless the parent thread that owns the current child-thread-task focus.

This kind of synchronization is established automatically while registering CThread classs.

Process Synchronization

CThread-derived class offers also the global locking mechanism which is exclusive for the whole process. The user may use ProcessLock() or ProcessUnlock() CThread static methods (that were previously opened by OpenProcessLocking() method) whereever in the code. These methods are static so there is no necessary to instantiate any CThread object. User may use this synchronization mechanism to accomplish an exclusive access to the global-critical resources (opening the file, common communication object, singleton etc.). Process Synchronization may be used in an arbitrary part of the code not necessarily in CThread tasks only.

The mentioned synchronization does not support an inter-process synchronization.

Thread Notification

Notificable Threads react to the thread-owner incoming commands and allow the owner to obtain the current thread activity status. Thread-owner process may use SendCommand() CThread method which fires an appropriate command to the thread. Thread immediately reacts to the incoming command (inside ThreadHandler() virtual method) and is responsible to handle this command. Simultaneously, the thread should set the current activity status by using SetActivityStatus() method. Thread-owner process uses GetActivityStatus() to obtain the current status.

Stackable Commands

The user should always communicate with CThread notificable threads via Commands. Start(), Pause(), Continue(), Reset(), Stop() or the general SendCommand() CThread methods are intended for such use. Although, this is not the only way how to communicate with CThread threads (we may, for example, use the methods of the specific object operating in the thread handler directly), it is highly recommended to use the Command communication. The main benefit is a synchronized access to the thread-critical code sections.

SendCommand() method supports cyclic stack mechanism. That means, for example, the calling sequence: Start(), Pause(), Reset(), Continue(), Stop() fired in one step will be handled exactly in the same order in which they were called.

Generating CThread Derived Class

CThread derived classes can be generated automatically by using the Worker Thread Class Generator Wizard enclosed in this delivery. User may choose the base CThread derived class from which he wants to derive his own CThread derived class, defines its own thread handler and implements the thread specific task by writing down the code in the generated source file. He may also establish the specific class synchronization or share the synchronization already established in the base class (see ‘Important Note’ in the previous article). The Worker Thread Class Generator workaround does not require any special explanation its intuitive at first glance.

Implementing CThread Task Handler

After generating the CThread derived class the developer has to implement the thread handler at least in one such class (from the Class Object Hierarchy point of view). The thread handler is declared and implemented in the *.h and *.cpp files as a virtual method: CThreadDerived::ThreadHandler().

According to the article 1 the user may implement one of the two possible paradigms.

1. Trivial Thread: Simple sequence of commands. Thread task implemented in such handler does not receive any command from outside and does not notify the thread-owner process. ThreadHandler() in this case looks very simple as follows:


DWORD CThreadDerived::ThreadHandler()
{
	BOOL bEverythingOK;

	<Command_1>;
	<Command_2>;
	<Command_3>;
	...
	<Command_n>;
	...

	if (bEverythingOK)
		return CThread::DW_OK	;	// return 0 if finished successfully
	else
		return CThread::DW_ERROR;	// return –1 otherwise
}

2. Notificable Thread: ThreadHandler() implements the task which is sensitive to the thread-owner incoming commands. The thread-owner may obtain the current thread activity status in an arbitrary phase of running thread. ‘Thread Handler()’ in such case should look as follows:


// CThread derived class supporting thread object synchronization
DWORD CThreadDerived::ThreadHandler()
{
	BOOL bContinue = TRUE;
	int nIncomingCommand;

	do
	{
		WaitForNotification(nIncomingCommand, CThreadDerived::DEFAULT_TIMEOUT);

		/////////////////////////////////////////////////////////////////////////////
		//	Main Incoming Command Handling:
		/////////////////////////////////////////////////////////////////////////////
		switch (nIncomingCommand)
		{

		case CThread::CMD_TIMEOUT_ELAPSED:
			SetActivityStatus(CThread::THREAD_PENDING);
			UserSpecificTimeoutElapsedHandler();
			Run();										// fire CThread::CMD_RUN Command if needed
			break;

		case CThread::CMD_INITIALIZE:		// initialize Thread Task
			// this Command MUST be handled; it’s fired when the Thread starts
			SetActivityStatus(CThread::THREAD_RUNNING);
			UserSpecificOnInitializeHandler();
			Run();										// fire CThread::CMD_RUN Command
			break;

		case CThread::CMD_RUN:					// handle 'OnRun' Command
			SetActivityStatus(CThread::THREAD_RUNNING);
			UserSpecificOnRunHandler();
			// the critical code which requires an exclusive handling (synchronization)
			Lock();										// CThread method
			UserSpecificCriticalCode();
			Unlock();									// CThread method
			break;

		case CThread::CMD_PAUSE:				// handle 'OnPause' Command
			if (GetActivityStatus() == CThread::THREAD_RUNNING)
			{
				SetActivityStatus(CThread::THREAD_PAUSED);
				UserSpecificOnPauseHandler();
			};
			break;

		case CThread::CMD_CONTINUE:			// handle 'OnContinue' Command
			if (GetActivityStatus() == CThread::THREAD_PAUSED)
			{
				SetActivityStatus(CThread::THREAD_CONTINUING);
				UserSpecificOnContinueHandler();
				Run();									// fire CThread::CMD_RUN Command if needed
			};
			break;

		case CThreadDerived::CMD_USER_SPECIFIC:	// handle the user-specific Command
			SetActivityStatus(CThreadDerived::THREAD_USER_SPECIFIC);
			UserSpecificOnUserCommandHandler();
			break;

		case CThread::CMD_STOP:					// handle 'OnStop' Command
			UserSpecificOnStopHandler();
			bContinue = FALSE;						// ... and leave thread function finally
			break;

		default:										// handle other Commands...
			break;

		};

	} while (bContinue);

	return (DWORD)CThread::DW_OK;						//... if Thread task completition OK
}

Establishing (… and starting) thread objects of the CThreadDerived class in the thread-owner process as well as handling these threads may look as in the following example:


CMainProgram::HandleThreads();
{
	CThreadDerived	thread1, thread2;

	// start threads
	try
	{
		thread1.Start();
		thread2.Start();

		...
		thread1.Pause();
			...
		thread2.Continue();

		// ... or send the user-specific command...
		// (must be recognizable in ThreadHandler())
		thread2.SendCommand(CThreadDerived::CMD_USER_SPECIFIC);

		...
		// stop threads
		thread1.Stop();		// (synchronous) waits until the thread actually finishes
		thread2.Stop();		// (synchronous) waits until the thread actually finishes
	}
	catch (CThreadException* pe)
	{
		if (!pe->GetErrorMsg().IsEmpty())
			pe->ReportError();
		pe->Delete();
	};
}

Note 2:

The communication from the thread-owner process to the Notificable Thread should always be established by sending the commands that are recognizable in the ThreadHandler() method.

Note 3:

Phrases using italic font in the mentioned source code list mean CThreadDerived specific methods or data members. All others are WINDOWS System functions or CThread provided methods and data members.

Remark

The user may utilize CThread-constructor parameters while constructing a CThread object. The first parameter is a void pointer and the second is LPARAM value. Void pointer may point to an arbitrary useful object (an owner of this thread e.g.). During thread task operation the thread may notify the owner object if needed. For example, the running thread may set the task progress position in the progress bar implemented in the owner object. Thread must, of course, be familiar with the architecture of the owner object.

Before Starting the Work

CThread features mentioned on this page are introduced in very general fashion only. Before starting the work user should download and unzip the enclosed 'CThread.zip' file on the local machine where the whole necessary code, documentation and the code wizard will be placed. After the installation developers may utilize Developor.doc documentation or CThread.hlp Reference Manual. Documentation provides detailed information how to deal with CThread objects offering examples as well as an exact description of all CThread methods. This documentation can be found in '\Doc' subdirectory of the main installation directory.

Documentation

More detailed information concerning CThread class can be found in CThread.hlp or CThread.htm Reference Manuals in '/Doc' subdirectory of the main installation directory.

Unzipping 'CThread.zip'

'CThread.zip' file should be unzipped to the empty directory (installation directory) on the local machine. It automatically expands to the desired subdirectory hierarchy.

Subdirectory Contents:

  • <root> - Worker Thread Class Generator Wizard (ThreadGenerator.exe)
  • /BaseClass - contains CThread.h and CThread.cpp implementation files of the base abstract CThread class.
  • /Doc - Developers Guidelines and the CThread Reference Manual
  • /Templates - source file templates used by the Worker Thread Class Generator Wizard

Download source - 172 Kb



Comments

  • Problems with 98

    Posted by Legacy on 09/13/2002 12:00am

    Originally posted by: Andre

    Hi, this is a very usefull class to me, thanks a lot.

    But I have problem, which I believe is with Kernel32.lib on 98.
    I compile the program on 2000, it doesn't run on 98.
    DLL Kernel32.lib missing.

    What's the catch ? is the function CreateThread that should be replaced with AfxBeginThread ?

    Thanks a lot,

    Andr�

    Reply
  • how can handle mutiple threads.....

    Posted by Legacy on 02/21/2002 12:00am

    Originally posted by: everjit

    suppose i create multiple threads with same function calling.
    so how can i handle perticular thread with in this large no of generated threads??
    is it nessesary that i have to give handle name to each thread when creating??
    plz give me example.

    Reply
  • You should create threads using the _beginthreadex function

    Posted by Legacy on 01/14/2000 12:00am

    Originally posted by: Stefano Maioli

    Hi,

    I've noticed that in the CThread::Start() function you have used the Win32 API ::CreateThread(...) to create the thread.

    If you are writing Win32-based applications using C or C++, you should create threads using the _beginthreadex function and not use CreateThread.

    Please refer to MSJ Q&A July 1999 for more information.

    I've replaced CreateThread with _beginthreadex and all works fine.

    Bye,

    Stefano Maioli.
    Florence, ITALY.

    Reply
  • how to get the wizard to work?

    Posted by Legacy on 06/01/1999 12:00am

    Originally posted by: a

    I must be missing something so basic that I can't find any documentation on it: How do I use the enclosed class generator? When called as a standalone exe, it doesn't allow me to specify a file for the base class and it won't create any output. Do I install into VC? and if so how? Thank you.

    Reply
  • Revised version available

    Posted by Legacy on 05/06/1999 12:00am

    Originally posted by: Dominik Filipp

      A new revised version of CThread class is now available. I had to fix a bug concerning CThread
    Synchronization. In the old version CThread objects instantiated from different CThread-derived classes but
    operating on the same ThreadHandler() method are not properly synchronized - in spite of the guarantee given
    and provided by Thread-Handler-Oriented Synchronization model.
    
    This problem is already fixed. I had also to modify the CThread Class Generator Wizard a bit. The whole new stuff is available in the enclosed zip.

    For those who already implemented CThread class I introduce few steps how to accommodate an existing code:
    __________________

    1) Remove the whole contents of the CThread installation directory (but not the directory itself).

    2) Extract the contents of new zip into this directory.

    3) Replace 'CThread.cpp' and 'CThread.h' source files in your projects with the actual version of these files.

    4) In your CThread-derived class (where the ThreadHandler() method is implemented and which supports the CThread Synchronization) modify the SUPPORT_THREAD_SYNCHRONIZATION macro in the class constructor by adding <ClassName> parameter as shown below:

    CThreadDerived::CThreadDerived(void* pOwnerObject, LPARAM lParam)
    : CThread(pOwnerObject, lParam)
    {
    // add the ClassName as a parameter in this macro
    SUPPORT_THREAD_SYNCHRONIZATION(CThreadDerived)
    ...
    }
    __________________


    ...That's all. There are no other impacts in the standard CThread functionality.

    Reply
  • Problem with class generator - explanation

    Posted by Legacy on 04/23/1999 12:00am

    Originally posted by: Dominik Filipp

      I know about this problem. Normally, the whole CThread class (including the wizard and the documentation)
    is the part of the installation program which properly installs the whole stuff. During installation process
    also some registry data are defined - mainly the name of an installation folder in which the stuff is
    originally placed.
    
    However, installation version is not accepted on the CodeGuru page in general, just pure zip package. Therefore you may have problems while invoking 'ClassGenerator.exe' from outside. Class Generator cannot read registry specific data (having not been established at all); cannot restore the installation directory name and the program fails.

    The recommended way how to invoke the Class Generator is to invoke it using the standard WINDOWS File Explorer from within the CThread installation directory directly..., this should help.

    But anyway, I have already sent the newer, more stable version of the 'ClassGenerator.exe' (enclosed in the 'worker_thread_class.zip' update) to the webmaster.
    Just visit the page later on.

    ***
    To ensure that the new version of 'worker_thread_class.zip' is already available check the creation time of the 'ClassGenerator.exe' program:


    Old 'ClassGenerator.exe' version (problematic):
    Creation time: 3/30/99 2:37 PM

    ... and the new corrected one should have...
    Creation time: 4/22/99 12:54 PM (... or later)

    Reply
  • Hi quality docs. Congratulations

    Posted by Legacy on 04/22/1999 12:00am

    Originally posted by: pierre

    You worked hard.
    Not bad about source code, but very good on
    documentation.

    I think that Zafir could open a new contest
    on a subject (GUI, DCOM, TCPIP ..), but where
    the judgement will foucuse not only about
    the technical interrest, but also on the supplied
    documentation - example: technical -> 75% of final score,
    and doc. -> 25% of final score.

    I think you can be on the top 5 winners, as I was on
    COM contest.

    Regards

    Reply
Leave a Comment
  • Your email address will not be published. All fields are required.

Top White Papers and Webcasts

  • Java developers know that testing code changes can be a huge pain, and waiting for an application to redeploy after a code fix can take an eternity. Wouldn't it be great if you could see your code changes immediately, fine-tune, debug, explore and deploy code without waiting for ages? In this white paper, find out how that's possible with a Java plugin that drastically changes the way you develop, test and run Java applications. Discover the advantages of this plugin, and the changes you can expect to see …

  • Packaged application development teams frequently operate with limited testing environments due to time and labor constraints. By virtualizing the entire application stack, packaged application development teams can deliver business results faster, at higher quality, and with lower risk.

Most Popular Programming Stories

More for Developers

Latest Developer Headlines

RSS Feeds