profile

Profile execution time for functions

collapse all in page

Use the Profiler to track execution time. Knowing the execution time of your MATLAB® code helps you to debug and optimize it. For information on the user interface to the Profiler, see Profiling for Improving Performance.

Syntax

Description

example

profile action profiles the execution time for functions. Use action to start, stop, and restart the Profiler, and view or clear profile statistics. For example, profile on starts the Profiler.

example

profile action option1 ... optionN starts or restarts the Profiler with the specified options. For example, profile resume -history restarts the Profiler and records the sequence of function calls.

example

profile option1 ... optionN sets the specified Profiler options. If the Profiler is on and you specify one of the options, MATLAB throws an error. To change options, first specify profile off, and then specify the new options.

example

p = profile('info') stops the Profiler and displays a structure containing the results. To access the data generated by profile, use this syntax.

example

s = profile('status') returns a structure with the Profiler status information.

Examples

collapse all

Turn on the Profiler, and call the magic function.

profile on
n = 100;
M = magic(n);

View the results in the Profiler window.

profile viewer

Save the results as HTML. By default, profsave saves the files to the profile_results subfolder in your current working folder.

profsave

Create the file myFunction.m using this main function and local function.

function c = myFunction(a,b)
c = sqrt(square(a)+square(b));
end

function y = square(x)
y = x.^2;
end

Turn on the Profiler, and enable the function call history option. Profile a call to the myFunction function.

profile on -history
a = rand(5);
b = rand(5);
c = myFunction(a,b);

Save the profile results.

p = profile('info')
p = 

      FunctionTable: [2x1 struct]
    FunctionHistory: [2x6 double]
     ClockPrecision: 3.3475e-07
         ClockSpeed: 3.0600e+09
               Name: 'MATLAB'
           Overhead: 0

Display the function call history.

p.FunctionHistory
ans =

     0     0     1     0     1     1
     1     2     2     2     2     1

Display function entry and exit information by iterating over the function call history.

numEvents = size(p.FunctionHistory,2);
for n = 1:numEvents
    name = p.FunctionTable(p.FunctionHistory(2,n)).FunctionName;
    
    if p.FunctionHistory(1,n) == 0
        disp(['Entered ' name]);
    else
        disp(['Exited ' name]);
    end
end
Entered myFunction
Entered myFunction>square
Exited myFunction>square
Entered myFunction>square
Exited myFunction>square
Exited myFunction

Set the function call history to the default value.

profile -nohistory
s = profile('status')
s = 

     ProfilerStatus: 'off'
        DetailLevel: 'mmex'
              Timer: 'performance'
    HistoryTracking: 'off'
        HistorySize: 1000000

Related Examples

Input Arguments

collapse all

Control options for the Profiler specified as one of these options.

OptionResult
on

Start the Profiler, clearing any previously recorded profile statistics.

off

Stop the Profiler.

resume

Restart the Profiler without clearing previously recorded statistics.

clear

Clear the recorded statistics.

viewer

Stop the Profiler and display the results in the Profiler window. For more information, see Profile to Improve Performance.

info

Stop the Profiler and return a structure containing the results.

status

Return a structure with the Profiler status information.

One or more profiling options, specified as character vectors corresponding to valid settings from the history and clock option tables. You can specify one or more of these options with one of the following syntaxes:

  • profile on option1 ... optionN

  • profile resume option1 ... optionN

  • profile option1 ... optionN

If you change the Profiler settings, the settings persist when you stop the Profiler or clear the statistics. To revert to default Profiler behavior, manually set the options to the default settings or start a new MATLAB session.

History Options

OptionResult
-history

Record the exact sequence of function calls, including function entry and exit events. By default, the -history option is not enabled.

-historysize integer

Specify the number of function entry and exit events to record. By default, historysize is 1,000,000. If the number of function calls exceeds the specified historysize, the profile function continues to record profiling statistics other than the sequence of calls.

-nohistory

Default setting. Disable recording of the exact sequence of function calls. The profile function collects all other profiling statistics.

Clock Options

OptionResult
-timer 'performance'

Default setting. Use wall-clock time from the clock that the operating system supplies to measure performance.

-timer 'processor'

Use the wall-clock time directly from the processor. Sometimes your power savings settings or use of multiple processors influence this measurement.

-timer 'real'

Use system time reported by the operating system. This option is the most computationally expensive measurement and has the most impact on the performance of profiled code. Changing the time on the operating system clock influences this measurement.

-timer 'cpu'

Use computer time and sums time across all threads. This measurement is different from wall-clock time. For example, the computer time for the pause function is typically small, but wall-clock time accounts for the actual time paused, which is larger.

Output Arguments

collapse all

Profiler statistics, returned as a structure containing these fields.

Field

Description

FunctionTable

Function statistics, returned as a structure array. Each structure in the array contains information about one of the functions or local functions called during profiling. Each structure contains the following fields:

  • CompleteName – Full path to FunctionName.

  • FunctionName – Name of function. If the function is a local function, FunctionName includes the main function.

  • FileName – Full path to FunctionName, with the file extension. If the function is a local function, FileName is the full path to the main function.

  • Type – Type of function. For example, MATLAB function, MEX-function, local function, or nested function.

  • NumCalls – Number of times the profiled code called the function.

  • TotalTime – Total time spent in the function and its child functions.

  • TotalRecursiveTime – MATLAB no longer uses this field.

  • Children – Information about functions that the function called. Each entry in the array contains information about one child function. The structure contains these fields:

    • Index – Index to child function information structure within FunctionTable.

    • NumCalls – Number of times the profiled code called the child function.

    • TotalTime – Total time spent in the child function.

  • Parents – Information about the parent functions of FunctionName. Each structure in the array contains information about one of the parents. The structure contains these fields:

    • Index – Index to parent function information structure within FunctionTable.

    • NumCalls – Number of times the parent function called this function.

  • ExecutedLines – Array containing line-by-line details for the profiled function.

    • Column 1 – Line number for the executed line of code in FileName.

    • Column 2 – Number of times the profiled code executed the line of code.

    • Column 3 – Total time spent on the line of code. The sum of Column 3 entries does not necessarily add up to the TotalTime.

  • IsRecursive – Indicator of whether the function is recursive. If the value is 1 (true), the function is recursive. If the value is 0 (false), the function is nonrecursive.

  • PartialData – Indicator of whether the profile statistics are incomplete. If the value is logical 1 (true), the function was modified during profiling. For example, if you edited the function or cleared it from memory. In that event, the Profiler collects data only up until you modified the function.

FunctionHistory

Function call history, returned as an array.

  • Row 1 – Indicator of function entry or exit. The Profiler records function entry with a 0, and function exit with a 1.

  • Row 2 – Index to function information structure within FunctionTable.

ClockPrecision

Precision of the time measurement of the profile function, returned as a double.

ClockSpeed

Estimated CPU clock speed, returned as a double.

Name

Name of the profiler, returned as a character array.

Overhead

Reserved for future use.

Profiler status, returned as a structure containing these fields.

Field

Values

Default Value

ProfilerStatus

'on' or 'off'

'off'

DetailLevel

'mmex'

'mmex'

Timer

'performance', 'processor', 'cpu', or 'real'

'performance'

HistoryTracking

'on' or 'off'

'off'

HistorySize

integer

1000000

More About

collapse all

Tips

  • To open the Profiler user interface, use the profile viewer syntax or see Profiling for Improving Performance.

  • As of MATLAB R2015b, the default timer is 'performance'. In previous versions of MATLAB, the default profiler timer was 'cpu', which measures compute time instead of wall-clock time.

See Also

| |

Introduced before R2006a

Was this topic helpful?
MATLAB Documentation
Other Documentation
Support