Handle Object Behavior
More than one variable can refer to the same handle object. Therefore, users interact with instances of handle classes differently than instances of value classes. Understanding how handle objects behave can help you determine whether to implement a handle or a value class. This topic illustrates some of those interactions.
For more information on handle classes, see Handle Classes.
What Is a Handle?
Certain kinds of MATLAB® objects are handles. When a variable holds a handle, it actually holds a reference to the object.
Handle objects enable more than one variable to refer to the same object. Handle-object behavior affects what happens when you copy handle objects and when you pass them to functions.
Copies of Handles
All copies of a handle object variable refer to the same underlying object. This reference behavior means that if
h identifies a handle object, then,
h2 = h;
Creates another variable,
h2, that refers to the same object as
For example, the MATLAB
audioplayer function creates a handle object that contains the audio source data to reproduce a specific sound segment. The variable returned by the
audioplayer function identifies the audio data and enables you to access object functions to play the audio.
MATLAB software includes audio data that you can load and use to create an
audioplayer object. This sample load audio data, creates the audio player, and plays the audio:
load gong Fs y gongSound = audioplayer(y,Fs); play(gongSound)
Suppose that you copy the
gongSound object handle to another variable (
gongSound2 = gongSound;
gongSound2 are copies of the same handle and, therefore, refer to the same audio source. Access the
audioplayer information using either variable.
For example, set the sample rate for the gong audio source by assigning a new value to the
SampleRate property. First get the current sample rate and then set a new sample rate:
sr = gongSound.SampleRate; disp(sr)
gongSound.SampleRate = sr*2;
You can use
gongSound2 to access the same audio source:
Play the gong sound with the new sample rate:
Handle Objects Modified in Functions
When you pass an argument to a function, the function copies the variable from the workspace in which you call the function into the parameter variable in the function’s workspace.
Passing a nonhandle variable to a function does not affect the original variable that is in the caller’s workspace. For example,
myFunc modifies a local variable called
var, but when the function ends, the local variable
var no longer exists:
function myFunc(var) var = var + 1; end
Define a variable and pass it to
x = 12; myFunc(x)
The value of
x has not changed after executing
myFunc function can return the modified value, which you could assign to the same variable name (
x) or another variable.
function out = myFunc(var) out = var + 1; end
Modify a value in
x = 12; x = myFunc(x); disp(x)
When the argument is a handle variable, the function copies only the handle, not the object identified by that handle. Both handles (original and local copy) refer to the same object.
When the function modifies the data referred to by the object handle, those changes are accessible from the handle variable in the calling workspace without the need to return the modified object.
For example, the
modifySampleRate function changes the
audioplayer sample rate:
function modifySampleRate(audioObj,sr) audioObj.SampleRate = sr; end
audioplayer object and pass it to the
load gong Fs y gongSound = audioplayer(y,Fs); disp(gongSound.SampleRate)
modifySampleRate function does not need to return a modified
gongSound object because
audioplayer objects are handle objects.
Determine If an Object Is a Handle
Handle objects are members of the
handle class. Therefore, you can always identify an object as a handle using the
isa returns logical
1) when testing for a handle variable:
load gong Fs y gongSound = audioplayer(y,Fs); isa(gongSound,'handle')
To determine if a variable is a valid handle object, use
if isa(gongSound,'handle') && isvalid(gongSound) ... end
Deleted Handle Objects
When a handle object has been deleted, the handle variables that referenced the object can still exist. These variables become invalid because the object they referred to no longer exists. Calling
delete on the object removes the object, but does not clear handle variables.
For example, create an
load gong Fs y gongSound = audioplayer(y,Fs);
The output argument,
gongSound, is a handle variable. Calling
delete deletes the object along with the audio source information it contains:
However, the handle variable still exists:
handle to deleted audioplayer
whos command shows
gongSound as an
Name Size Bytes Class Attributes Fs 1x1 8 double gongSound 1x1 0 audioplayer y 42028x1 336224 double
The value for Bytes returned by the
whos command does not include the data referenced by a handle because many variables can reference the same data.
gongSound no longer refers to a valid object, as shown by the
isvalid handle method:
ans = logical 0
delete on a deleted handle does nothing and does not cause an error. You can pass an array containing both valid and invalid handles to
delete. MATLAB deletes the valid handles, but does not issue an error when encountering handles that are already invalid.
You cannot access properties with the invalid handle variable:
Invalid or deleted object.
Functions and methods that access object properties cause an error:
Invalid or deleted object.
To remove the variable,
clear gongSound whos
Name Size Bytes Class Attributes Fs 1x1 8 double y 42028x1 336224 double