MATLAB Function Reference

profile

Profile execution time for function

Graphical Interface

As an alternative to the profile function, select Desktop -> Profiler from the desktop.

Syntax

• profile on
  profile on -detail level
  profile on -history
  profile off
  profile resume
  profile clear
  profile viewer
  s = profile('status')
  stats = profile('info')
  

Description

The profile function helps you debug and optimize M-files by tracking their execution time. For each function in the M-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 depfun for that purpose. To open the Profiler graphical user interface, use the profile viewer syntax. Profile 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.

profile on -detail level starts the Profiler, clearing previously recorded profile statistics, and specifying the set of functions you want to profile. Allowable values for level are

• 'builtin'--Gathers information about M-functions, M-subfunctions, and MEX-functions, plus built-in functions, such as eig.
• 'mmex'--Gathers information about M-functions, M-subfunctions, and MEX-functions. This is the default value.

profile on -history starts the Profiler, clearing previously recorded profile statistics, and recording the exact sequence of function calls. The profile function records up to 10,000 function entry and exit events. For more than 10,000 events, profile continues to record other profile statistics, but not the sequence of calls. By default, the history option is not enabled.

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.

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

Field	Values
ProfilerStatus	'on' or 'off'
DetailLevel	'mmex' or 'builtin'
HistoryTracking	'on' or 'off'

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 they appear in the structure.

Field	Description
FunctionTable	Structure array containing statistics about each functions called
FunctionHistory	Array containing function call history
ClockPrecision	Precision of profile's time measurement
Name	Name of the profiler
ClockSpeed	Estimated clock speed of the CPU

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

Field	Description
FunctionName	Function name, includes subfunction references
FileName	Fully qualified path
Type	M-functions, MEX-functions, and many other types of functions including M-subfunctions, nested functions, and anonymous functions
NumCalls	Number of times this function was called
TotalTime	Total time spent in this function and its child functions
TotalRecursiveTime	No longer used. Ignore value.
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 that line was executed Column 3: Total time spent on that line. Note: The sum of Column 3 does not necessarily add up to the function's TotalTime.
IsRecursive	Boolean value: Logical 1 (true) if recursive, otherwise logical 0 (false)
AcceleratorMessages	No longer used

Examples

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')
  

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)
  

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 1 means entrance into a function and 0 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

depdir, depfun, mlint, profsave

Profiling for Improving Performance in the MATLAB Desktop Tools and Development Environment documentation

prod

profsave

© 1994-2005 The MathWorks, Inc.