Automatic Updates for Modified Classes

When MATLAB Loads Class Definitions

MATLAB^® loads a class definition:

The first time the class is referenced, such as creating an instance, accessing a constant property, or calling a static method of the class.
Whenever the definition of a loaded class changes and MATLAB returns to the command prompt.
When you change the MATLAB path and cause a different definition of the class to be used. The change takes effect after MATLAB returns to the command prompt.
Whenever you access the class metadata.

MATLAB allows only one definition for a class to exist at any time. Therefore, MATLAB attempts to update all existing objects of a class automatically to conform to the new class definition. You do not need to call clear classes to remove existing objects when you change their defining class.

Note

Using an editor other than the MATLAB editor or using MATLAB Online™ can result in delays to automatic updating.

Consequences of Automatic Update

MATLAB follows a set of basic rules when updating existing objects. An automatic update can result in:

Existing objects being updated to the new class definition.
An error if MATLAB cannot convert the objects to the new class definition or if there is an error in the class definition itself.

Here is an example of what happens when you create an instance of a concrete class edit the class definition to make the class abstract.

a = MyClass;
% Edit MyClass to make it Abstract

a

Error using MyClass/display
Cannot update object because the class 'MyClass' is now abstract.

Note

MATLAB does not update metaclass instances when you change the definition of a class. You must get new metaclass data after updating a class definition.

What Happens When Class Definitions Change

MATLAB updates existing objects when a class definition changes, including the following situations:

Value change to handle — Existing objects become independent handles referring to different objects.
Enumeration member added — Existing objects preserve the enumeration members they had previously, even if the underlying values have changed.
Enumeration member removed — Existing objects that are not using the removed member have the same enumeration members that they had previously. Existing objects that use the removed member replace the removed member with the default member of the enumeration.
Enumeration block removed — Enumeration members are taken out of use.
Superclass definition changed — Changes applied to all subclasses in the hierarchy of that superclass.
Superclass added or removed — Change of superclass applied to all existing objects.

Ensure Defining Folder Remains in Scope

Changes to the MATLAB path that result in removing the class definition file from the path, even temporarily, can produce side effects. If a function changes from the current folder, which contains the class definition, and that folder is not on the path, then the function cannot call methods of the class that is now out of scope. To avoid potential problems, add the class defining folder to the path before changing to another folder.

For example, suppose the class of the input obj is defined in the current folder, which is not on the path. Before changing the current folder to another folder, add the current folder to the path using the addpath function.

function runFromTempFolder(obj)
    % Add current folder to path
    addpath(pwd)
    definingFolder = cd('myTempFolder');
    obj.myMethod;
    cd(definingFolder)
end

Actions That Do Not Trigger Updates

These actions do not update existing objects:

Calling the class function on an out-of-date object
Assigning an out-of-date object to a variable
Calling a method that does not access class data
Changing property validation in the class definition (Validate Property Values)

Objects do not update until referenced in a way that exposes the change, such as invoking the object display or assigning to a property.

Multiple Updates to Class Definitions

Updates do not occur incrementally. Updates conform to the latest version of the class.

Object Validity with Deleted Class File

Deleting a class definition file does not make instances of that class invalid. However, you cannot call methods on existing objects of that class.

When Updates Are Not Possible

Some class updates result in an invalid class definition. In these cases, objects do not update until the error is resolved:

Adding a superclass can result in a property or method being defined twice.
Changing a superclass to be Sealed when objects of one of its subclasses exists results in an invalid subclass definition.

Some class updates cause situations in which MATLAB cannot update existing objects to conform to a modified class definition. These cases result in errors until you delete the objects:

Adding an enumeration block to a non-enumeration class
Redefining a class to be abstract
Removing a class from a heterogeneous hierarchy that results in there being no default object to replace existing objects in a heterogeneous array
Updating a class to restrict array formation behavior, such as overloading array indexing and concatenation.
Inheriting a subsref, subsasgn, cat, vertcat, or horzcat method
Redefining a handle class to be a value class.

Potential Consequences of Class Updates

Following an update, existing objects can be incompatible with the new class definition. For example, a newly added property can require execution of the constructor to be valid.
Removing or renaming properties can lose the data held in the property. For example, if a property holds the only reference to another object and you remove that property from the class, the MATLAB deletes the object because there are no longer any references to it.
Removing a class from a heterogeneous class hierarchy can result in invalid heterogeneous array elements. In this case, the default object for the heterogeneous hierarchy replaces these array elements.

Interactions with the Debugger

Since R2021a.

MATLAB disables the debugger during class updates. Before R2021a, a breakpoint could potentially interrupt the class update process and allow for the introduction of errors when the update resumes. For example, the breakpoint allows a class author to introduce invalid syntax into the class definition or remove the class from the path entirely, potentially causing MATLAB to crash.

Example of a Disabled Breakpoint

This class defines a property validation function:

classdef ClassWithBreakpoint
    properties (Constant)
        Prop1 (1,1) {myPropertyValidator} = 32
    end
end

function myPropertyValidator(~)
end % Add breakpoint here

Create an instance of this class. Then add a breakpoint where indicated, and update the definition of Prop1 to a different initial value:

Prop1 (1,1) {myPropertyValidator} = 10

In version R2020b and earlier, MATLAB hits the breakpoint, and the class update is interrupted. In R2021a, the debugger is disabled, and the breakpoint does not interrupt the update.

Updates to Class Attributes

Changing class attributes can change existing object behavior or make the objects invalid. MATLAB returns an error when you access the invalid objects.

Change	Effect
Make `Abstract = true`	Accessing existing objects returns an error.
Change `AllowedSubclasses`	Newly created objects can inherit from different superclasses than existing objects.
Change `ConstructOnLoad`	Loading classes obeys the current value of `ConstructOnLoad`.
Change `HandleCompatible`	Newly created objects can have different class hierarchy than existing objects.
Change `Hidden`	Appearance of class in list of superclasses and access by `help` function can change
Change `InferiorClasses`	Method dispatching for existing objects can change.
Make `Sealed = true`	Existing subclass objects return errors when accessed.

Updates to Property Definitions

When you change the definition of class properties, MATLAB applies the changes to existing objects of the class.

Change	Effect
Add property	Adds the new property to existing objects of the class. Sets the property values to the default value (which is `[]` if the class definition does not specify a default).
Remove property	Removes the property from existing objects of the class. Attempts to access the removed property fail.
Change property default value	Does not apply the new default value to existing objects of the class.
Move property between subclass and superclass	Does not apply different default value when property definition moves between superclass and subclass.
Change property attribute value	Applies changes to existing objects of the class. Some cases require transitional steps: `Abstract` — Existing objects of a class that becomes abstract cannot be updated. Delete these objects. `Access` — Changes to the `public`, `protected`, or `private` property access settings affect access to existing objects. Changes to the access lists do not change existing objects. However, if you add classes to the access list, instances of those classes have access to this property. If you remove classes from the access list, objects of those classes no longer have access to this property. `Dependent` — If changed to `true`, existing objects no longer store property values. If you want to query the property value, add a property get method for the property. `Transient` — If changed to `true`, objects already saved, reload this property value. If changed to `false`, objects already saved reload this property using the default value.

Updates to Method Definitions

When you change the definition of class methods, MATLAB changes the affected class member in existing objects as follows.

Change	Effect
Add method	You can call the new method on existing objects of the class.
Modify method	Modifications are available to existing objects.
Remove method	You can on longer call deleted method on existing objects.
Change method attribute value	Apply changes to existing objects of the class. Some cases require transitional steps: `Abstract` — Existing objects of a class that becomes abstract cannot be updated. Delete these objects. `Access` — Changes to method `public`, `protected`, or `private` access settings affect access to existing objects. Changes to the access lists do not change existing instances. However, if you add classes to the access list, instances of those classes have access to this method. If you remove classes from the access list, objects of those classes no longer have access to this method. `Sealed` — If changed to `true` and existing subclasses already have defined the method, MATLAB returns an error because the new class definition cannot be applied to existing subclasses.

Updates to Event Definitions

Change	Effect
Add event	Existing objects of the class support the new event.
Change event name	New event name is visible to existing objects of the class. MATLAB: Does not update existing metaclass objects Does update newly acquired metaclass objects Does not update listeners to use new event name
Remove event	Existing objects no longer support deleted event.
Change event attribute value	Apply changes to existing objects of the class. Some cases require transitional steps: `ListenAccess` — Changes to event `public`, `protected`, or `private` listen access settings affect access to existing objects. Changes to the access list do not change existing objects. However, if you add classes to the access list, objects of those classes can create listeners for this event. If you remove classes from the access list, objects of those classes are not allowed to create listeners for this event. `NotifyAccess` — Changes to event `public`, `protected`, or `private` notify access settings affect access to existing objects. Changes to the access list do not change existing objects. However, if you add classes to the access list, instances of those classes can trigger this event. If you remove classes, objects of those classes are not able to trigger this event.