FTObjectClass Module

FTObject is the root class for all object types.

Overview

FTObject defines the basic methods that are essential for reference counted objects.

FTObject is generally not going to be instantiated by itself, but rather it will be subclassed and one will work with instances of the subclasses. Otherwise, pointers of type FTObject that point to instances of subclasses will be stored in the container classes.

Tasks

• init()

  Initializes an object and any memory that it needs to allocate, etc. Should be orrerrided in subclasses.The base class implementation does nothing but increase the reference count of the object.

• destruct()

  Destructor of the object, which releases and deallocates owned objects and memory. Should be overridden in subclasses. The base class implementation does nothing but decrease the reference count of the object.

• printDescription(iUnit)

  Prints a description of the object to a specified file unit. The base class implementation does nothing but print "FTObject"

• copy()

  Creates a copy (pointer) to the object of CLASS(FTObject) sourced with the object.

• retain()

  Increases the reference count of the object. Any procedure or object that retain()'s an object gains an ownership stake in that object. This procedure is not overridable.

• release()

  Decreases the reference count of an object. To be called only by objects or procedures that have ownership in an object pointer, i.e., for which init() or retain() have been called. Override this procedure in subclasses for releasing the actual type.

• isUnreferenced()

  Test to see if there are no more owners of an object.

• refCount()

  Returns the number of owners of an object. Usually this is of interest only for debugging purposes. This procedure is not overridable.

Subclassing FTObject

In general, subclasses of FTObject override

• init()
• destruct()
• printDescription()
• release()

They should also provide a cast() subroutine to convert from the base class to a subclass. The cast() routine can look something like

 SUBROUTINE castToSubclass(obj,cast) 
    IMPLICIT NONE  
    CLASS(FTObject), POINTER :: obj
    CLASS(SubClass), POINTER :: cast

    cast => NULL()
    SELECT TYPE (e => obj)
       TYPE is (SubClass)
          cast => e
       CLASS DEFAULT

    END SELECT

 END SUBROUTINE castToSubclass

Subclassing init

The init() procedure performs subclass specific operations to initialize an object.

Subclasses that override init() must include a call to the super class method. For example, overriding init looks like

 SUBROUTINE initSubclass(self) 
    IMPLICIT NONE
    CLASS(Subclass) :: self

    CALL self % FTObject % init()
    Allocate and initialize all member objects
    ... Other Subclass specific code
 END SUBROUTINE initSubclass

Subclassing destruct

The destruct() procedure reverses the operations done in the init() procedure. It releases and deallocates any pointers that it owns. Subclasses that override destruct() must include a call to the super class method. For example, overriding destruct looks like

 SUBROUTINE destructSubclass(self) 
    IMPLICIT NONE
    CLASS(Subclass) :: self

    Release and deallocate (if necessary) all member objects
    CALL self % FTObject % destruct()

 END SUBROUTINE destructSubclass

Subclassing printDescription(iUnit)

printDescription is a method whose existence is to support debugging. Call printDescription(iUnit) on any objects owned by self for a cascading of what is stored in the object.

Casting an object from the base to a subclass

Container classes and the copy function return pointers to a CLASS(FTObject). To use any subclass features one must "cast" to the subclass. We like to have a specific cast routine to do this as painlessly as possible. Each subclass should include a SUBROUTINE like this:

 SUBROUTINE castToSubclass(obj,cast) 
    IMPLICIT NONE  
    CLASS(FTObject), POINTER :: obj
    CLASS(Subclass), POINTER :: cast
    cast => NULL()
    SELECT TYPE (e => obj)
       TYPE is (Subclass)
          cast => e
       CLASS DEFAULT
    END SELECT
 END SUBROUTINE castToValue

Subclassing className

The className() procedure returns the name of the class.

Subclasses should override className() !>

Created: January 7, 2013 11:30 AM @author David A. Kopriva