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