|On this page…|
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 information. Handle-object behavior affects what happens when you copy handle objects and when you pass them to functions.
All copies of a handle object variable refer to the same underlying object. This means that if h identifies a handle object, then,
h2 = h;
Creates another variable, h2, that refers to the same object as h.
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 you copy the gongSound object handle to another variable (gongSound2):
gongSound2 = gongSound;
The variables gongSound and 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 sr = 8192 gongSound.SampleRate = sr*2;
You can use gongSound2 to access the same audio source:
gongSound2.SampleRate ans = 16384
Play the gong sound with the new sample rate:
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 an ordinary (nonhandle) variable to a function does not affect the original variable. 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 myfunc:
x = 12; myFunc(x)
The value of x has not changed after executing myFunc(x):
x x = 12
The 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 myfunc:
x = 12; x = myFunc(x) x ans = 13
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
Create an audioplayer object and pass it to the modifySampleRate function:
load gong Fs y gongSound = audioplayer(y,Fs); gongSound.SampleRate ans = 8192 modifySampleRate(gongSound,16384) gongSound.SampleRate ans = 16384
The modifySampleRate function does not need to return a modified gongSound object because audioplayer objects are handle objects.
Handle objects are members of the handle class. Therefore, you can always identify an object as a handle using the isa function. isa returns logical true (1) when testing for a handle variable:
load gong Fs y00 gongSound = audioplayer(y,Fs); isa(gongSound,'handle') ans = 1
To determine if a variable is a valid handle object, use isa and isvalid:
if isa(gongSound,'handle') && isvalid(gongSound) ... end
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 audioplayer object:
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:
gongSound gongSound = handle to deleted audioplayer
The whos command shows gongSound as an audioplayer object:
whos Name Size Bytes Class Attributes Fs 1x1 8 double gongSound 1x1 104 audioplayer y 42028x1 336224 double
The handle gongSound no longer refers to a valid object:
isvalid(gongSound) ans = 0
You cannot call functions on the invalid handle variable:
play(gongSound) Invalid or deleted object.
You cannot access properties with the invalid handle variable:
gongSound.SampleRate Invalid or deleted object.
To remove the variable, gongSound, use clear:
clear gongSound whos Name Size Bytes Class Attributes Fs 1x1 8 double y 42028x1 336224 double