View source for SomDestruct

{{DISPLAYTITLE:somDestruct}}
This method uninitializes the receiving object, and (if so directed) frees object storage after uninitialization has been completed. Replaces somUninit as the preferred method for uninitializing objects. For performance reasons, it is recommended that somDestruct always be overridden. Not normally invoked directly by object clients.

; Original Class : [[SOMObject]]

==Syntax==
 void somDestruct (SOMObject receiver, octet dofree, somDestructCtrl ctrl)

==Parameters==
;  receiver (SOMObject) : A pointer to an object. 

; dofree (octet) : A boolean indicating whether the caller wants the object storage freed after uninitialization of the current class has been completed. Passing 1 (true) indicates the object storage should be freed. 

; ctrl (somDestructCtrl) : A pointer to a somDestructCtrl data structure. SOMobjects uses this data structure to control the uninitialization of the ancestor classes, thereby ensuring that no ancestor class receives multiple uninitialization calls. If a user invokes somDestruct on an object directly, a NULL (that is, zero) ctrl pointer can be passed. This instructs the receiving code to obtain a somDestructCtrl data structure from the class of the object.
==Return Code==
rc (void)

==Remarks==
Every class must support the somDestruct method. This is accomplished either by overriding somDestruct (in which case a specialized stub procedure will be generated in the implementation template file), or else SOMobjects will automatically provide a generic procedure that implements somDestruct for the class. The generic procedure calls somUninit (if this was overridden) to perform local uninitialization, then completes execution of the method appropriately.

Because the specialized stub procedure generated by the template emitter is more efficient than the generic procedure provided when somDestruct is not overridden, it is recommended that somDestruct always be overridden. The stub procedure that is generated in this case requires no modification for correct operation. The only modification appropriate within this stub procedure is to uninitialize locally introduced instance variables. See Section 5.5, `Initializing and Unitializing Objects,' of the SOM Programming Guide for further details.

Uninitialization with somDestruct executes as follows: For any given class in the ancestor chain, somDestruct first uninitializes that class's introduced instance variables (if this is appropriate), and then calls the next ancestor class's implementation of somDestruct, passing 0 (that is, false) as the interim dofree argument. Then, after all ancestors of the given class have been uninitialized, if the class's own somDestruct method were originally invoked with dofree as 1 (that is, true), then that object's storage is released.

'''Note:''' It is not appropriate to override both somDestruct and somUninit. If this is done, the somUninit code will not be executed. The best way to convert an old class that overrides somUninit to use of the more efficient somDestruct (if this is desired) is as follows: (1) Replace the somUninit override in the class's .idl file with an override for somDestruct, (2) run the emitter to produce a stub procedure for somDestruct in the implementation template file, and then (3) simply call the class's somUninit procedure directly (not using a method invocation) from the somDestruct procedure.

==Example Code==
<PRE>
// SOM IDL
#include <Animal.idl>

interface Dog : Animal
{
    implementation {
        releaseorder: ;
            somDestruct: override;
        };
};
</PRE>

==Related==
===Methods===
* [[somDefaultInit]]

[[Category:SOM Kernel]]