Creating Singleton Objects using Visual C++

========================================================================
                     Readme.Txt - Singleton Classes
========================================================================

This file ( Readme.txt ) contains the following

1. About this application
2. Usage
3. File List
4. Known Bug

1. About this application
=========================

This is a sample application to emphasize the concept of Singleton classes
explained in my article, "Creating Singleton Objects Using Visual C++".

A class which has only one object of its type is called a "Singleton Class". 
In this application, the concept of Singleton is explained using a simple "Message handler" 
example.  Message handlers can be used for formatting or logging application messages, 
before displaying the messages to the user.  

Three message handler classes are used in this application, which includes

a ) CMsgHndlr - Base class for message handlers. It is responsible for creating
the required message handler object when GetMsgHndlr method is called. It is also 
responsible for notifying the window with the message when HandleMessage method is 
called. 

b ) CSmpHndlr - This class is derived from CMsgHndlr and it is responsible for 
displaying the message in a message box when HandleMessage method is called.

c ) CLogHndlr - This class is derived from CMsgHndlr, it is responsible for logging 
and displaying the message in a message box when HandleMessage method is called. 

Message handlers register their runtime class information with a message handler 
registry. CMsgHndlrRegistry, a template class derived from CObjRegistry is used to 
store these runtime class information. CMsgHndlr uses "MSGHNDLR" as the key to register
its runtime class.  CSmpHndlr registers its runtime class using "SMPHNDLR" as the key and 
CLogHndlr uses "LOGHNDLR" as the key.  This key is passed as a command-line argument to the 
application to select and create the required message handler object. A message handler
class can register or unregister itself without affecting other message handlers.  
So, a new message handler can register itself without affecting any other source files 
of the application. By passing the key as a command-line argument, the choice of 
message handler can be made at runtime. 

NOTE : In this application, I've included the message handler classes as part of the 
project itself. I've to recompile the project, when I add a new message handler. 
But, message handler classes can also be implemented as a separate DLL. Since, the message 
handler class information is registered only at run time, a new message handler class 
added to the DLL can be used without recompiling the application.

CSmartCleaner is used by message handler classes to do the object cleanup when
the application terminates.

This application is developed using Visual C++ 4.2.  This project is compiled 
WITHOUT any optimization because of a known problem with the optimizer. This problem is 
explained at the end of this file ( see Known Bug ). 

2. Usage 
========

User should be able select the required message handler at runtime. This application
takes a key as a command-line argument to select the required message handler.
As explained earlier, use "MSGHNDLR" as key to use CMsgHndlr object, use "SMPHNDLR"
as key to use CSmpHndlr object and use "LOGHNDLR" as key to use CLogHndlr object.

3. File List
============

/////////////////////////////////////////////////////////////////////////////

Message handler files:

MsgHndlr.h, MsgHndlr.cpp - the Singleton base class for message handlers.
    These files contain CMsgHndlr class. 

SmpHndlr.h, SmpHndlr.cpp - These files contain CSmpHndlr class.  
    This class is derived from CMsgHndlr. 

LogHndlr.h, LogHndlr.cpp - These files contain CLogHndlr class.  
    This class is derived from CMsgHndlr. 

/////////////////////////////////////////////////////////////////////////////

Registration files

ObjReg.h - This file contains CObjRegistry class. Object registry is used for storing
    runtime class information of the objects.  Given the key or the class name, 
    CObjRegistry queries and returns the Runtime Class to the client.

MsgHndlrReg.h - This file contains CMsgHndlrRegistry class. This class is derived from 
    CObjRegistry. Runtime class information of message handlers are registered to 
    CObjRegistry via this class.

/////////////////////////////////////////////////////////////////////////////

Smart cleaner file:

SmtClnr.h - This file contains CSmartCleaner class.  This class is responsible for 
    the cleanup of the object associated with it during its destruction.

/////////////////////////////////////////////////////////////////////////////

Application files:

Singleton.h
    This is the main header file for the application.  It includes other
    project specific headers (including Resource.h) and declares the
    CSingletonApp application class.

Singleton.cpp
    This is the main application source file that contains the application
    class CSingletonApp.

Singleton.rc
    This is a listing of all of the Microsoft Windows resources that the
    program uses.  It includes the icons, bitmaps, and cursors that are stored
    in the RES subdirectory.

res\Singleton.ico
    This is an icon file, which is used as the application's icon.  This
    icon is included by the main resource file Singleton.rc.

res\Singleton.rc2
    This file contains resources that are not edited by Microsoft 
	 Developer Studio.

Singleton.clw
    This file contains information used by ClassWizard to edit existing
    classes or add new classes.  ClassWizard also uses this file to store
    information needed to create and edit message maps and dialog data
    maps and to create prototype member functions.

/////////////////////////////////////////////////////////////////////////////

For the main frame window:

MainFrm.h, MainFrm.cpp
    These files contain the frame class CMainFrame, which is derived from
    CFrameWnd and controls all SDI frame features.


/////////////////////////////////////////////////////////////////////////////

Document and view files:

SingletonDoc.h, SingletonDoc.cpp - the document
    These files contain CSingletonDoc class.  

SingletonView.h, SingletonView.cpp - the view of the document
    These files contain CSingletonView class.


/////////////////////////////////////////////////////////////////////////////
Other standard files:

StdAfx.h, StdAfx.cpp
    These files are used to build a precompiled header (PCH) file
    named Singleton.pch and a precompiled types file named StdAfx.obj.

Resource.h
    This is the standard header file, which defines new resource IDs.

/////////////////////////////////////////////////////////////////////////////

4. Known Bug
============

This project is compiled WITHOUT any optimization, because of a known problem with 
the Visual C++ optimizer when working on local static objects. Refer to the article, 
"BUG: Static Object No Longer Static When Optimized" ( PSS ID Number: Q119328 ) in 
Visual C++ Knowledge Base and Bug Lists, for more details.