Handle Class Destructor

Basic Knowledge

 Terms and Concepts

Syntax of Class Destructor Method

When destroying an object, MATLAB implicitly calls the class destructor method, if the class defines one. Create a destructor method by implementing a method named delete. However, MATLAB recognizes a class method named delete as the class destructor only if you define delete as an ordinary method with the appropriate syntax.

To be a valid class destructor, the delete method:

  • Must have one scalar input argument that is an object of the class.

  • Must not define output arguments

  • Cannot be Sealed, Static, or Abstract

In addition, destructors should not:

  • Throw errors

  • Create new handles to the object being destroyed

If you define a delete method that can be called with more than one input argument, or that returns any output arguments, then MATLAB does not recognize that method as the class destructor, and does not call it when destroying an object of the class.

Declare delete as an ordinary method:

methods
   function delete(obj)
      % obj is always scalar
   ...
   end
end

Calling Delete on an Array

MATLAB calls the destructor method element-wise on an array of objects. Because MATLAB calls the delete method separately for each element in an object array, each delete method is passed only one scalar argument.

When to Define a Destructor Method

Use a class destructor to perform any necessary cleanup operations before MATLAB destroys an object of the class.

For example, suppose an object opens a file for writing and you want to close the file in your delete method. This delete function calls fclose on a file identifier that the object's FileID property stores:

function delete(obj)
   fclose(obj.FileID);
end 

The Filewriter Class is an example of a class that uses this delete method.

Destructors in Class Hierarchies

If you create a hierarchy of classes, each class can define its own class destructor method. When destroying an object, MATLAB calls the destructor of each class in the hierarchy. Therefore, defining a delete method in a handle subclass does not override the handle class delete method; the subclass delete methods augment the superclass delete methods.

Inheriting a Sealed Delete Method

You cannot define a valid destructor that is Sealed. MATLAB returns an error when you attempt to instantiate a class that defines a Sealed destructor.

Normally, declaring a method as Sealed prevents subclasses from overriding that method. However, because destructors must be named delete, an inherited method named delete that is Sealed does not prevent subclasses from defining valid destructors.

For example, if a superclass defines a method named delete that is not a valid destructor and is Sealed, then subclasses:

  • Can define valid destructors (which are always named delete).

  • Cannot define methods named delete that are not valid destructors.

Destructors in Heterogeneous Hierarchies

Heterogeneous class hierarchies (matlab.mixin.Heterogeneous) require that all methods to which heterogeneous arrays are passed must be sealed. However, the rule does not apply to class destructor methods. Because destructor methods cannot be sealed, you can define a valid destructor in a heterogeneous hierarchy that is not sealed, but does function as a destructor.

Object Lifecycle

MATLAB invokes the destructor delete method when the lifecycle of an object ends. The lifecycle of an object ends when the object is:

  • No longer referenced anywhere

  • Explicitly deleted by calling delete on the handle

Inside a Function

The lifecycle of an object referenced by a local variable or input argument exists from the time the variable is assigned until the time it is reassigned, cleared, or no longer referenced within that function or any handle array.

A variable goes out of scope when you explicitly clear it or when its function ends. When a variable goes out of scope, if its value belongs to a handle class that defines a delete method, MATLAB calls that method. MATLAB defines no ordering among variables in a function. Do not assume that MATLAB destroys one value before another value when the same function contains multiple values.

Sequence During Handle Object Destruction

MATLAB invokes the delete methods in the following sequence when destroying an object:

  1. The delete method for the class of the object

  2. The delete method of each superclass class, starting with the immediate superclasses and working up the hierarchy to the most general superclasses

MATLAB invokes the delete methods of superclasses at the same level in the hierarchy in the order specified in the class definition. For example, the following class definition specifies supclass1 before supclass2 so MATLAB calls the delete function of supclass1 before the delete function of supclass2.

classdef myClass < supclass1 & supclass2

Superclass delete methods cannot call methods or access properties belonging to a subclass.

After calling each delete method, MATLAB destroys the property values belonging exclusively to the class whose method was called. The destruction of property values that contain other handle objects can cause MATLAB to call the delete methods for those objects, if there are no other references to those objects.

Destruction of Objects with Cyclic References

Consider a set of objects that reference other objects of the set such that the references form a cyclic graph. In this case, MATLAB:

  • Destroys the objects if they are referenced only within the cycle

  • Does not destroy the objects as long as there is an external reference to any of the objects from a MATLAB variable outside the cycle

MATLAB destroys the objects in the reverse of the order of construction.

Restrict Explicit Object Deletion

You can destroy handle objects by explicitly calling delete on the object:

delete(obj)

A class can prevent explicit destruction of an object by setting its delete method Access attribute to private. MATLAB issues an error if you explicitly call delete on a handle object whose delete method is private. However, a method of the class can call the private delete method.

Similarly, if the class delete method Access attribute has a value of protected, only methods of the class and any subclasses can explicitly delete objects of that class.

However, when an object's lifecycle ends, MATLAB calls the object's delete method when destroying the object regardless of method's Access attribute setting. See Object Lifecycle for information on when MATLAB destroys objects and Sequence During Handle Object Destruction for information on how MATLAB calls object delete methods.

Inherited Private Delete Methods

Class destructor behavior differs from the normal behavior of an overridden method. MATLAB executes each delete method of each superclass of an object upon destruction, even if that delete method is not public.

When you explicitly call an object's delete method, MATLAB checks the delete method Access attribute in the class defining the object, but not in the superclasses of the object. Therefore, a superclass with a private delete method does not prevent the destruction of subclass objects.

Declaring a private delete method makes most sense for sealed classes. The reason for this is because, in the case where classes are not sealed, subclasses can define their own delete methods with public access, and MATLAB calls a private superclass delete method as a result of an explicit call to a public subclass delete method.

Nondestructor Delete Methods

A class can implement a method named delete that is not a valid class destructor, and therefore is not called implicitly by MATLAB when destroying an object. In this case, delete behaves like a normal method.

For example, if the superclass implements a Sealed method named delete that is not a valid destructor, then MATLAB does not allow subclasses to override this method.

A delete method defined by a value class cannot be a class destructor. See Basic Difference for information on the difference between a value and handle class.

See Syntax of Class Destructor Method for information on how to implement a delete method that is a valid destructor.

Was this topic helpful?