Objects are persistent, meaning they exist in memory until you destroy them. We can break the life of an object into three phases: creation and initialization, use, and destruction. Object lifecycle routines allow the creation and destruction of object references; lifecycle methods associated with an object allow you to control what happens when an object is created or destroyed. This section discusses the first and last phases of the object lifecycle.

Creation and Initialization

Object references are created using one of two lifecycle routines: OBJ_NEW or OBJARR. Newly-created objects are initialized upon creation in two ways:

  1. The object reference is created based on the class structure specified,
  2. The object’s Init method (if it has one) is called to initialize the object’s instance data (contained in fields defined by the class structure). If the object does not have an Init method, the object’s superclasses (if any) are searched for an Init method.

The Init Method

An object’s lifecycle method Init is a function named Class::Init (where Class is the actual name of the class). The purpose of the Init method is to populate a newly-created object with instance data. Init should return a scalar TRUE value (such as 1) if the initialization is successful, and FALSE (such as 0) if the initialization fails.

The Init method is unusual in that it cannot be called outside an object-creation operation. This means that—unlike most object methods—you cannot call the Init method on an object directly. You can, however, call an object’s Init method from within the Init method of a subclass of that object. This allows you to specify parameters used by the superclass’ Init method along with those used by the Init method of the object being created. In practice, this is often done using the _EXTRA keyword.

Implicit Object Creation and the OBJ_NEW Function

You can create an object reference to a new object heap variable in one of two ways:

  • The implicit object creation method - use the class name as a function
  • The OBJ_NEW function

The implicit method uses the name of the class structure as a function that creates a new object.

With OBJ_NEW, you supply the name of a class structure as its argument, and OBJ_NEW creates a new object.

In both methods, the new object contains an instance of that class structure.

Note that the fields of the newly-created object's instance data structure will all be empty. For example, the following commands both create a new object heap variable that contains an instance of the class structure ClassName, and places an object reference to this heap variable in obj1:

obj1 = Classname([argument])

or

obj1 = OBJ_NEW('ClassName')

Either method creates a new object heap variable that contains an instance of the class structure ClassName, and places an object reference to this heap variable in obj1. If you do not supply an argument, the newly-created object will be a null object.

When creating an object from a class structure, object creation follows these steps:

  1. If the class structure has not been defined, IDL will attempt to find and call a procedure to define it automatically. If the structure is still not defined, object creation fails and issues an error.
  2. If the class structure has been defined, object creation creates an object heap variable containing a zeroed instance of the class structure.
  3. Once the new object heap variable has been created, object creation looks for a method function named Class::Init (where Class is the actual name of the class). If an Init method exists, it is called with the new object as its implicit SELF argument, as well as any arguments and keywords specified in the call. If the class has no Init method, the usual method-searching rules are applied to find one from a superclass.

Note: OBJ_NEW does not call all the Init methods in an object’s class hierarchy. Instead, it calls the first one it finds. Therefore, the Init method for a class should call the Init methods of its direct superclasses as necessary.

  1. If the Init method returns true, or if no Init method exists, OBJ_NEW returns an object reference to the heap variable. If Init returns false, OBJ_NEW destroys the new object and returns the NULL object reference, indicating that the operation failed. Note that in this case the Cleanup method is not called.

See OBJ_NEW for further details.

The OBJARR Function

Use the OBJARR function to create an array of objects of up to eight dimensions. Every element of the array created by OBJARR is set to the null object. For example, the following command creates a 3 x 3 element object reference array with each element containing the null object reference:

obj2 = OBJARR(3, 3)

See OBJARRfor further details.

Destruction

Call the object's Cleanup method or use the OBJ_DESTROY procedure to destroy an object. If the object’s class or one of its superclasses supplies a procedure method named Cleanup, that method is called and all arguments and keywords passed by the user are passed to it. The Cleanup method should perform any required cleanup on the object and return. Whether a Cleanup method actually exists or not, IDL will destroy the heap variable representing the object and return.

The Cleanup method cannot be called outside an object-destruction operation. This means that (unlike most object methods) you cannot call the Cleanup method on an object directly. You can, however, call an object's Cleanup method from within the Cleanup method of a subclass of that object.

See OBJ_DESTROY for further details.

Implicit Calling of Superclass Cleanup Methods

If you create an object class and do not implement a Cleanup method for it, when you destroy an object of your class IDL will call the Cleanup method of the class’ superclass, if it has one.

If your class has multiple superclasses, on destruction IDL will attempt to call the Cleanup method of the first superclass. If that superclass has a Cleanup method, IDL will execute it and then destroy the object. If the first superclass does not have a Cleanup method, IDL will proceed through the list of superclasses in the order they are specified in the class structure definition statement until it either finds a Cleanup method to execute or reaches the end of the list.

To ensure that Cleanup methods from multiple superclasses are called, create a Cleanup method for your class and call the superclass’ Cleanup methods explicitly.