Documentation

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 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 that 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;
disp(sr)

8192

gongSound.SampleRate = sr*2;

You can use gongSound2 to access the same audio source:

disp(gongSound2.SampleRate)

16384

Play the gong sound with the new sample rate:

play(gongSound2)

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 myfunc:

x = 12;
myFunc(x)

The value of x has not changed after executing myFunc(x):

disp(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);
disp(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 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);
disp(gongSound.SampleRate)

8192

modifySampleRate(gongSound,16384)
disp(gongSound.SampleRate)

16384

The 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 function. isa returns logical true (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 isa and isvalid:

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 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:

delete(gongSound)

However, the handle variable still exists:

disp(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                  0  audioplayer              
  y              42028x1             336224  double      

The handle gongSound no longer refers to a valid object, as shown by the isvalid handle method:

isvalid(gongSound)

ans =

  logical

   0

Calling 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:

gongSound.SampleRate

Invalid or deleted object.

Functions and methods that access object properties cause an error:

play(gongSound)

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