Automatic Updates for Modified Classes - MATLAB & Simulink (original) (raw)

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.

Updates to Property Definitions

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

Updates to Method Definitions

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

Updates to Event Definitions

See Also

Topics

• Use of Editor and Debugger with Classes