matlab.lang.WeakReference Class

R2026b

Namespace: matlab.lang

Weak reference to handle object

Since R2024b

Description

Use the matlab.lang.WeakReference class to create a weak reference to a handle object. The handle object can already exist, or you can create an instance of this class with a placeholder handle object. For more information on weak reference behavior in MATLAB^®, see Weak References.

Creation

Description

wr = matlab.lang.WeakReference creates a weak reference to a handle object. When no argument is specified, the Handle property is set to a handle to a deleted object of type matlab.lang.HandlePlaceholder.

wr = matlab.lang.WeakReference(obj) creates an instance with the Handle property set to a scalar handle object obj.

Properties

Handle — Object for which weak reference is defined

handle to deleted matlab.lang.HandlePlaceholder object (default) | scalar handle object

Object for which the weak reference is defined, specified as a scalar handle object.

Attributes:

GetAccess	public
SetAccess	public

ValidHandle — Object for which weak reference is defined (for debugging)

handle to deleted matlab.lang.HandlePlaceholder object (default) | scalar handle object

Since R2026b

Object for which the weak reference is defined, specified as a scalar handle object. This property holds the same value as Handle, but if you access the property when it holds an invalid handle, MATLAB errors. Use this property to help debug your code when you want to break cycles using weak references.

Attributes:

GetAccess	public
Dependent	true

Examples

Create Array of matlab.lang.WeakReference Placeholders

Create a 2-by-3 array of weak reference placeholders by calling createArray with matlab.lang.WeakReference as the class.

weakArray = createArray(2,3,"matlab.lang.WeakReference")
 

weakArray = 

  2×3 WeakReference array with properties:

    Handle

Verify that the Handle property of the array elements is set to a handle to a deleted matlab.lang.HandlePlaceholder object.

weakArray(1,1).Handle
 

ans = 

  handle to deleted HandlePlaceholder

Define Weak Reference for Handle Object

Construct an instance of the TrialData handle class.

classdef TrialData < handle
    properties
        trialNumber string = "A001"
        trialResults double = 0
    end
end

ref = TrialData;

Construct a weak reference to the object ref.

weakref = matlab.lang.WeakReference(ref)

weakref = 

  WeakReference with properties:

    Handle: [1×1 TrialData]

Clear the original reference to the object.

clear("ref")

Access the Handle property of weakref. Because the only remaining reference to the original object is a weak reference, MATLAB deletes the object.

weakref.Handle

ans = 

  handle to deleted TrialData

Check for Invalid Handle Object

Use the ValidHandle property of WeakReference to check for an invalid handle.

Create a weak reference to an instance of a handle class.

obj = matlab.lang.HandlePlaceholder;
weakobj = matlab.lang.WeakReference(obj)

weakobj = 

  WeakReference with properties:

    Handle: [1×1 matlab.lang.HandlePlaceholder]

Clear the variable obj. Because obj no longer has any strong references, the object is deleted. Both the Handle and ValidHandle properties contain a handle to a deleted object, but ValidHandle errors if you try to access it.

clear("obj")
weakobj.ValidHandle

Error using matlab.lang.WeakReference/get.ValidHandle
Error getting matlab.lang.WeakReference property ValidHandle of 
class matlab.lang.HandlePlaceholder because the object is an 
invalid handle. Ensure that strong references to the object exist to 
prevent it from being deleted.

Version History

Introduced in R2024b

R2026b: New ValidHandle property

The ValidHandle property holds the same value as the Handle property, but if they hold a reference to an invalid handle object, MATLAB errors when you try to access ValidHandle.