MATLAB calls the destructor of a handle class when destroying
objects of the class. MATLAB recognizes a method named
the class destructor only if you define
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
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
when destroying objects of the class. A
that is not a valid destructor shadows the handle base class
delete method can prevent the destruction
of the object by shadowing the
delete as an ordinary method:
methods function delete(obj) % obj is always scalar ... end end
MATLAB calls the
delete method separately
for each element in an array. Therefore, a
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
work on object arrays containing a mix of valid and invalid objects.
Errors that occur while constructing an object can result in
a call to
delete before the object is fully created.
delete methods must be able to
work with partially constructed objects.
For example, the
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
instead of the required cell array:
obj = PartialObject('Test')
MATLAB passes the partially constructed object to the
The constructor did not set the value of the
because the error occurred when setting the
Data is empty Error setting 'Name' property of 'PartialObject' class: ...
delete method to perform cleanup operations
before MATLAB destroys the object. MATLAB calls the
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 can call
a file identifier that the object stores in its
function delete(obj) fclose(obj.FileID); end
If you create a hierarchy of classes, each class can define
delete method. When destroying an object, MATLAB calls
delete method of each class in the hierarchy.
delete method in a
does not override the
delete methods augment the superclass
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
subclasses from overriding that method. However, a
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
is not a valid destructor, but is
Can define valid destructors (which are always named
Cannot define methods named
are not valid destructors.
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
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.
MATLAB invokes the
delete methods in
the following sequence when destroying an object:
delete method for the class
of the object
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
supclass2. MATLAB calls
delete method of
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
for those objects when there are no other references to those objects.
delete methods cannot call methods
or access properties belonging to a subclass.
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.
Destroy handle objects by explicitly calling
A class can prevent explicit destruction of an object by setting
private. However, a method of the class can
If the class
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
delete method when destroying the
object regardless of the method’s
Class destructor behavior differs from the normal behavior of
an overridden method. MATLAB executes each
of each superclass upon destruction, even if that
When you explicitly call an object’s
delete method, MATLAB checks
in the class defining the object, but not in the superclasses of the
object. A superclass with a
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
A class can implement a method named
is not a valid class destructor. MATLAB does not call this method
implicitly when destroying an object. In this case,
like an ordinary method.
For example, if the superclass implements a
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.
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
delete method executes, call
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
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
from within a function:
function testDestructor cwj = CallbackWithJava ... end
Creating an instance of 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
when the function ends. The
still exists and holds a reference to the object of the
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 the delete explicitly before losing the handle to the MATLAB object.
function testDestructor cwj = CallbackWithJava ... delete(cwj) end
MATLAB applications that use Java 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:
Explicitly call delete on 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.