Documentation Center

  • Trial Software
  • Product Updates

profile

Profile execution time for function

Syntax

profile on
profile -history
profile -nohistory
profile -history -historysize integer
profile -timer clock
profile -history -historysize integer -timer clock
profile off
profile resume
profile clear
profile viewer
S = profile('status')
stats = profile('info')

Description

The profile function helps you debug and optimize MATLAB® code files by tracking their execution time. For each MATLAB function, MATLAB local function, or MEX-function in the file, profile records information about execution time, number of calls, parent functions, child functions, code line hit count, and code line execution time. Some people use profile simply to see the child functions; see also matlab.codetools.requiredFilesAndProducts for that purpose. To open the Profiler graphical user interface, use the profile viewer syntax. By default, Profiler time is CPU time. The total time reported by the Profiler is not the same as the time reported using the tic and toc functions or the time you would observe using a stopwatch.

profile on starts the Profiler, clearing previously recorded profile statistics. Note the following:

  • You can specify all, none, or a subset, of the —history, —historysize and —timer options with the profile on syntax.

  • You can specify options in any order, including before or after on.

  • If the Profiler is currently on and you specify profile with one of the options, MATLAB software returns an error message and the option has no effect. For example, if you specify profile —timer real, MATLAB returns the following error: The profiler has already been started. TIMER cannot be changed.

  • To change options, first specify profile off, and then specify profile on or profile resume with new options.

profile -history records the exact sequence of function calls. The profile function records, by default, up to 1,000,000 function entry and exit events. For more than 1,000,000 events, profile continues to record other profile statistics, but not the sequence of calls. To change the number of function entry and exit events that the profile function records, use the –historysize option. By default, the history option is not enabled.

profile -nohistory disables further recording of the history (exact sequence of function calls). Use the -nohistory option after having previously set the -history option. All other profiling statistics continue to be collected.

profile -history -historysize integer specifies the number of function entry and exit events to record. By default, historysize is set to 1,000,000.

profile -timer clock specifies the type of time to use. Valid values for clock are:

  • 'cpu' — The Profiler uses computer time (the default).

  • 'real' — The Profiler uses wall-clock time.

For example, cpu time for the pause function is typically small, but real time accounts for the actual time paused, and therefore would be larger.

profile -history -historysize integer -timer clock specifies all of the options. Any order is acceptable, as is a subset.

profile off stops the Profiler.

profile resume restarts the Profiler without clearing previously recorded statistics.

profile clear clears the statistics recorded by profile.

profile viewer stops the Profiler and displays the results in the Profiler window. For more information, see Profiling for Improving Performance in the Desktop Tools and Development Environment documentation.

S = profile('status') returns a structure containing information about the current status of the Profiler. The table lists the fields in the order that they appear in the structure.

Field

Values

Default Value

ProfilerStatus

'on' or 'off'

off

DetailLevel

'mmex'

'mmex'

Timer

'cpu' or 'real'

'cpu'

HistoryTracking

'on' or 'off'

'off'

HistorySize

integer

1000000

stats = profile('info') stops the Profiler and displays a structure containing the results. Use this function to access the data generated by profile. The table lists the fields in the order that they appear in the structure.

Field

Description 

FunctionTable

Structure array containing statistics about each function called

FunctionHistory

Array containing function call history

ClockPrecision

Precision of the profile function's time measurement

ClockSpeed

Estimated clock speed of the CPU

Name

Name of the profiler

The FunctionTable field is an array of structures, where each structure contains information about one of the functions or local functions called during execution. The following table lists these fields in the order that they appear in the structure.

Field

Description 

CompleteName

Full path to FunctionName, including local functions

FunctionName

Function name; includes local functions

FileName

Full path to FunctionName, with file extension, excluding local functions

Type

MATLAB functions, MEX-functions, and many other types of functions including MATLAB local functions, nested functions, and anonymous functions

NumCalls

Number of times the function was called

TotalTime

Total time spent in the function and its child functions

TotalRecursiveTime

No longer used.

Children

FunctionTable indices to child functions

Parents

FunctionTable indices to parent functions

ExecutedLines

Array containing line-by-line details for the function being profiled.

Column 1: Number of the line that executed. If a line was not executed, it does not appear in this matrix.

Column 2: Number of times the line was executed

Column 3: Total time spent on that line. Note: The sum of Column 3 entries does not necessarily add up to the function's TotalTime.

IsRecursive

BOOLEAN value: Logical 1 (true) if recursive, otherwise logical 0 (false)

PartialData

BOOLEAN value: Logical 1 (true) if function was modified during profiling, for example by being edited or cleared. In that event, data was collected only up until the point when the function was modified.

Examples

Profile, View Results, and Save Profile Data as HTML

This example profiles the MATLAB magic command and then displays the results in the Profiler window. The example then retrieves the profile data on which the HTML display is based and uses the profsave command to save the profile data in HTML form.

profile on
plot(magic(35))
profile viewer
p = profile('info');
profsave(p,'profile_results')

Profile, Save Profile Data to a MAT-File, and View Results

Another way to save profile data is to store it in a MAT-file. This example stores the profile data in a MAT-file, clears the profile data from memory, and then loads the profile data from the MAT-file. This example also shows a way to bring the reloaded profile data into the Profiler graphical interface as live profile data, not as a static HTML page.

p = profile('info');
save myprofiledata p
clear p
load myprofiledata
profview(0,p)

Profile and Show Results Including History

This example illustrates an effective way to view the results of profiling when the history option is enabled. The history data describes the sequence of functions entered and exited during execution. The profile command returns history data in the FunctionHistory field of the structure it returns. The history data is a 2-by-n array. The first row contains Boolean values, where 0 means entrance into a function and 1 means exit from a function. The second row identifies the function being entered or exited by its index in the FunctionTable field. This example reads the history data and displays it in the MATLAB Command Window.

profile on -history
plot(magic(4));
p = profile('info');

for n = 1:size(p.FunctionHistory,2)
 if p.FunctionHistory(1,n)==0
        str = 'entering function: ';
 else
        str = 'exiting function: ';
 end
 disp([str p.FunctionTable(p.FunctionHistory(2,n)).FunctionName])
end

See Also

| |

Related Examples

Was this topic helpful?