The Object Lifecycle

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 will discuss the first and last phases of the object lifecycle; the remainder of this chapter discusses manipulation of existing objects and use of object method routines. To get information about an object, see Returning Object Type and Validity (Using IDL).

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. SeeKeyword Inheritance for details.

The OBJ_NEW Function

Use the OBJ_NEW function to create an object reference to a new object heap variable. If you supply the name of a class structure as its argument, OBJ_NEW creates a new object containing 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 command: 

obj1 = OBJ_NEW('ClassName')

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, OBJ_NEW goes through the following steps:

  1. If the class structure has not been defined, IDL will attempt to find and call a procedure to define it automatically. See Automatic Class Structure Definition for details. If the structure is still not defined, OBJ_NEW fails and issues an error.
  2. If the class structure has been defined, OBJ_NEW creates an object heap variable containing a zeroed instance of the class structure.
  3. Once the new object heap variable has been created, OBJ_NEW 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 to OBJ_NEW. If the class has no Init method, the usual method-searching rules are applied to find one from a superclass. For more information on methods and method-searching rules, see Creating Custom Object Method Routines.

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

  4. 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" (IDL Reference Guide) 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 by 3 element object reference array with each element contain the null object reference: 

obj2 = OBJARR(3, 3)

See "OBJARR" (IDL Reference Guide) for further details.

Destruction

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 is unusual in that it 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.

Note that the object references themselves are not destroyed. Object references that refer to nonexistent object heap variables are known as dangling references, and are discussed in more detail in Dangling References.

See "OBJ_DESTROY" (IDL Reference Guide) 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.