This topic describes the behavior of handle objects for users of handle objects. For information on defining handle classes, see Handle Classes.
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.
All copies of a handle object variable refer to the same underlying
object. This reference behavior means that if
a handle object, then,
h2 = h;
Creates another variable,
h2, that refers
to the same object as
For example, the MATLAB
creates a handle object that contains the audio source data to reproduce
a specific sound segment. The variable returned by the
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
handle to another variable (
gongSound2 = gongSound;
copies of the same handle and, therefore, refer to the same audio
source. Access the
audioplayer information using
For example, set the sample rate for the gong audio source by
assigning a new value to the
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
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 a nonhandle variable to a function does not affect the
original variable that is in the caller's workspace. For example,
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
x = 12
myFunc function can return the modified
value, which you could assign to the same variable name (
or another variable.
function out = myFunc(var) out = var + 1; end
Modify a value in
x = 12; x = myFunc(x)
x = 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
audioplayer sample rate:
function modifySampleRate(audioObj,sr) audioObj.SampleRate = sr; end
audioplayer object and pass it
load gong Fs y gongSound = audioplayer(y,Fs); gongSound.SampleRate
ans = 8192
ans = 16384
modifySampleRate function does not need
to return a modified
gongSound object because
are handle objects.
Handle objects are members of the
Therefore, you can always identify an object as a handle using the
1) when testing
for a handle variable:
load gong Fs y gongSound = audioplayer(y,Fs); isa(gongSound,'handle')
ans = 1
To determine if a variable is a valid handle object, use
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
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
delete deletes the object along
with the audio source information it contains:
However, the handle variable still exists:
gongSound = handle to deleted audioplayer
whos command shows
Name Size Bytes Class Attributes Fs 1x1 8 double gongSound 1x1 104 audioplayer y 42028x1 336224 double
The value for Bytes returned by the
gongSound no longer refers to
a valid object, as shown by the
isvalid handle method:
ans = 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