Handle Class Destructor
Class destructor – a method named
delete that MATLAB® calls implicitly before destroying an object of a handle class. Also, user-defined code can call
delete explicitly to destroy an object.
Nondestructor – a method named
delete that does not meet the syntax requirements of a valid destructor. Therefore, MATLAB does not call this method implicitly when destroying handle objects. A method named
delete in a value class is not a destructor. A method named
delete in a value class that sets the
HandleCompatible attribute to
true is not a destructor.
Syntax of Handle Class Destructor Method
MATLAB calls the destructor of a handle class when destroying objects of the class. MATLAB recognizes a 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
Must define one, scalar input argument, which is an object of the class.
Must not define output arguments
argumentsblocks for input argument validation.
In addition, the
delete method should not:
Throw errors, even if the object is invalid.
Create new handles to the object being destroyed
Call methods or access properties of subclasses
MATLAB does not call a noncompliant
delete method when destroying objects of the class. A noncompliant
delete method can prevent the destruction of the object by shadowing the
handle class delete method.
delete method defined by a value class that is handle compatible is not a destructor, even if the
delete method is inherited by a handle subclass. For information on handle compatible classes, see Handle Compatible Classes.
delete as an ordinary method:
methods function delete(obj) % obj is always scalar ... end end
delete Called Element-Wise on Array
MATLAB calls the
delete method separately for each element in an array. Therefore, a
delete method is passed only one scalar argument with each invocation.
delete on a deleted handle should not error and can take no action. This design enables
delete to work on object arrays containing a mix of valid and invalid objects.
Handle Object During
delete Method Execution
delete method on an object always results in the destruction of the object. The object is destroyed when the call to
delete is made explicitly in MATLAB code or when called by MATLAB because an object is no longer reachable from any workspace. Once called, a
delete method cannot abort or prevent object destruction.
delete method can access properties of the object being deleted. MATLAB does not destroy these properties until after the
delete methods for the class of the object and all superclasses finish executing.
delete method creates new variables that contain a handle to the object being deleted, those handles are invalid. After the
delete method finishes execution, handles to the deleted object in any variables in any workspace are invalid.
isvalid method returns
false for the handle object within the
delete method because object destruction begins when the method is called.
delete methods in the inverse of the construction order. That is, MATLAB invokes subclass
delete methods before superclass
If a superclass expects a property to be managed by subclasses, then the superclass should not access that property in its
delete method. For example, if a subclass uses an inherited abstract property to store an object handle, then the subclass should destroy this object in its
delete method, but the superclass should not access that property in its
Support Destruction of Partially Constructed Objects
Errors that occur while constructing an object can result in a call to
delete before the object is fully created. Therefore, class
delete methods must be able to work with partially constructed objects.
For example, the
delete method determines if the
Data property is empty before accessing the data this property contains. If an error occurs while assigning the constructor argument to the
Name property, MATLAB passes the partially constructed object to delete.
classdef PartialObject < handle properties % Restrict the Name property % to a cell array Name cell Data end methods function h = PartialObject(name) if nargin > 0 h.Name = name; h.Data.a = rand(10,1); end end function delete(h) % Protect against accessing properties % of partially constructed objects if ~isempty(h.Data) t = h.Data.a; disp(t) else disp('Data is empty') end end end end
An error occurs if you call the constructor with a
char vector, instead of the required cell array:
obj = PartialObject('Test')
MATLAB passes the partially constructed object to the
delete method. The constructor did not set the value of the
Data property because the error occurred when setting the
Data is empty Error setting 'Name' property of 'PartialObject' class: ...
When to Define a Destructor Method
delete method to perform cleanup operations before MATLAB destroys the object. MATLAB calls the
delete method reliably, even if execution is interrupted with Ctrl-c or an error.
If an error occurs during the construction of a handle class, MATLAB calls the class destructor on the object along with the destructors for any objects contained in properties and any initialized base classes.
For example, suppose that a method opens a file for writing and you want to close the file in your
delete method. The
delete method can call
fclose on a file identifier that the object stores in its
function delete(obj) fclose(obj.FileID); end
Destructors in Class Hierarchies
If you create a hierarchy of classes, each class can define its own
delete method. When destroying an object, MATLAB calls the
delete method of each class in the hierarchy. Defining a
delete method in a
handle subclass does not override the
delete method. Subclass
delete methods augment the superclass
Inheriting a Sealed Delete Method
Classes cannot define a valid destructor that is
Sealed. MATLAB returns an error when you attempt to instantiate a class that defines a
Normally, declaring a method as
Sealed prevents subclasses from overriding that method. However, a
Sealed method named
delete that is not a valid destructor does not prevent a subclass from defining its own destructor.
For example, if a superclass defines a method named
delete that is not a valid destructor, but is
Sealed, then subclasses:
Can define valid destructors (which are always named
Cannot define methods named
deletethat are not valid destructors.
Destructors in Heterogeneous Hierarchies
Heterogeneous class hierarchies 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.
For information on heterogeneous hierarchies, see Designing Heterogeneous Class Hierarchies
MATLAB invokes the
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
deleteon 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 in 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 and 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:
deletemethod for the class of the object
deletemethod 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
supclass2. MATLAB calls the
delete method of
supclass1 before the
delete method of
classdef myClass < supclass1 & supclass2
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 a call the
delete methods for those objects when there are no other references to those objects.
delete methods cannot call methods or access properties belonging to a subclass.
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. for more information, see Handle Object During delete Method Execution.
Restrict Access to Object Delete Method
Destroy handle objects by explicitly calling
delete on the object:
A class can prevent explicit destruction of an object by setting its
Access attribute to
private. However, a method of the class can call the
If the class
Access attribute is
protected, only methods of the class and of subclasses can explicitly delete objects of that class.
However, when an object lifecycle ends, MATLAB calls the object’s
delete method when destroying the object regardless of the method’s
Inherited Private Delete Methods
Class destructor behavior differs from the normal behavior of an overridden method. MATLAB executes each
delete method of each superclass upon destruction, even if that
delete method is not
When you explicitly call an object’s
delete method, MATLAB checks the
Access attribute in the class defining the object, but not in the superclasses of the object. A superclass with a
delete method cannot prevent the destruction of subclass objects.
Declaring a private delete method makes most sense for sealed classes. In the case where classes are not sealed, subclasses can define their own delete methods with public access. MATLAB calls a private superclass
delete method as a result of an explicit call to a public subclass
Nondestructor Delete Methods
A class can implement a method named
delete that is not a valid class destructor. MATLAB does not call this method implicitly when destroying an object. In this case,
delete behaves like an ordinary 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.
delete method defined by a value class cannot be a class destructor.
External References to MATLAB Objects
MATLAB does not manage object lifecycles that involve external languages that perform their own object lifecycle management (aka, garbage collection). MATLAB cannot detect when it is safe to destroy objects used in cyclic references because the external environment does not notify MATLAB when external reference have been destroyed.
If you cannot avoid external references to MATLAB objects, explicitly break the cyclic reference by destroying the objects in MATLAB.
The following section describes how to manage this situation when using Java® objects that reference MATLAB objects.
Java References Can Prevent Destructor Execution
Java does not support the object destructors that MATLAB objects use. Therefore, it is important to manage the lifecycle of all objects used in applications that include both Java and MATLAB objects.
Java objects that hold references to MATLAB objects can prevent deletion of the MATLAB objects. In these cases, MATLAB does not call the handle object
delete method even when there is no handle variable referring to that object. To ensure your
delete method executes, call
delete on the object explicitly before the handle variable goes out of scope.
Problems can occur when you define callbacks for Java objects that reference MATLAB objects.
For example, the
CallbackWithJava class creates a Java
com.mathworks.jmi.Callback object and assigns a class method as the callback function. The result is a Java object that has a reference to a handle object via the function-handle callback.
classdef CallbackWithJava < handle methods function obj = CallbackWithJava jo = com.mathworks.jmi.Callback; set(jo,'DelayedCallback',@obj.cbFunc); % Assign method as callback jo.postCallback end function cbFunc(obj,varargin) c = class(obj); disp(['Java object callback on class ',c]) end function delete(obj) c = class(obj); disp(['ML object destructor called for class ',c]) end end end
Suppose that you create a
CallbackWithJava object from within a function:
function testDestructor cwj = CallbackWithJava ... end
Creating an instance of the
CallbackWithJava class creates the
com.mathworks.jmi.Callback object and executes the callback function:
cwj = CallbackWithJava with no properties. Java object callback on class CallbackWithJava
The handle variable,
cwj, exists only in the function workspace. However, MATLAB does not call the class
delete method when the function ends. The
com.mathworks.jmi.Callback object still exists and holds a reference to the object of the
CallbackWithJava class, which prevents destruction of the MATLAB object.
Warning: Objects of 'CallbackWithJava' class exist. Cannot clear this class or any of its superclasses.
To avoid causing inaccessible objects, call
delete explicitly before losing the handle to the MATLAB object.
function testDestructor cwj = CallbackWithJava ... delete(cwj) end
Manage Object Lifecycle in Applications
MATLAB applications that use Java or other external-language objects should manage the lifecycle of the objects involved. A typical user interface application references Java objects from MATLAB objects and creates callbacks on Java objects that reference MATLAB objects.
You can break these cyclic references in various ways:
deleteon the MATLAB objects when they are no longer needed
Unregister the Java object callbacks that reference MATLAB objects
Use intermediate handle objects that reference both the Java callbacks and the MATLAB objects.