Documentation

HCL_Base is the base class for all HCL classes. The purpose of having a common base class is to implement reference counting. HCL_Base contains an integer called ReferenceCount; whenever a programmer wants to copy a pointer to a HCL object rather than copying the object itself, he must call the method IncCount(), which increments ReferenceCount. The object cannot be deleted unless its ReferenceCount is 1; however, in order for this scheme to work, the function HCL_delete must be used in place of the operator delete. Note that the programmer who increments the reference count is responsible for calling HCL_delete for that object (just as a programmer who calls new is responsible for calling delete).

The most common situation in which one wants to copy a pointer to a HCL object is in a constructor. Suppose an object is constructed which depends on a HCL object. It may not be desirable to make a copy of the HCL object (due to time or space overhead). One can just copy the pointer to the object and increment its reference count; then the HCL object cannot be deleted until its reference count has be decremented by a call to HCL_delete.

Example:

MyObject::MyObject( HCL_Object * obj,... ) // constructor for MyObject
{
   hclobj = obj;   // hclobj is a data member of type HCL_Object*
   obj->IncCount();  // Increment obj's reference count
   // etc.
}

MyObject::~MyObject()  // destructor for MyObject
{
   HCL_delete( hclobj ); // Decrement obj's reference count
   // etc.
}

The point of HCL's reference counting is to provide protection against an object being deleted by one part of the code while another part of the code is still using it. In the above example, the object pointed to by hclobj will not disappear while the MyObject object still points to it.

HCL_Base also mandates that every instantiable HCL object have a Write method which sends a description of the object to an output stream. Of course the class implementor will decide what ``description of the object'' means in each instance. The most useful meaning seems to be: whatever is necessary to aid in debugging.