changeset 12976:2e20c26b1007

Document the profiler functions. debug.txi: Document profile and profshow in the manual.
author Daniel Kraft <d@domob.eu>
date Thu, 18 Aug 2011 18:43:58 +0200
parents 6590446c2498
children 9db4e9b352d6
files doc/interpreter/debug.txi
diffstat 1 files changed, 42 insertions(+), 0 deletions(-) [+]
line wrap: on
line diff
--- a/doc/interpreter/debug.txi
+++ b/doc/interpreter/debug.txi
@@ -35,6 +35,7 @@
 * Breakpoints::
 * Debug Mode::
 * Call Stack::
+* Profiling::
 @end menu
 
 @node Entering Debug Mode
@@ -182,3 +183,44 @@
 @DOCSTRING(dbup)
 
 @DOCSTRING(dbdown)
+
+@node Profiling
+@section Profiling
+@cindex profiler
+@cindex code profiling
+
+Octave supports profiling of code-execution on a per-function level.  If
+profiling is enabled, each call to a function (supporting built-ins,
+operators, functions in oct- and mex- files, user-defined functions
+in Octave code and anonymous functions) is recorded while running
+Octave code.  After that, this data can aid in analyzing the code-behaviour,
+and is in particular helpful for finding ``hot spots'' in the code
+which use up a lot of computation time and are the best targets to spend
+optimization efforts on.
+
+The main command for profiling is @code{profile}, which can be used
+to start / stop the profiler and also to query collected data afterwards.
+The data is returned in an Octave data-structure which can then be
+examined or further processed by other routines or tools.
+
+@DOCSTRING(profile)
+
+An easy way to get an overview over the collected data is @code{profshow}.
+This function takes the profiler-data returned by @code{profile} as input
+and prints a flat profile, for instance:
+
+@example
+ Function Attr     Time (s)        Calls
+----------------------------------------
+   >myfib    R        2.195        13529
+binary <=             0.061        13529
+ binary -             0.050        13528
+ binary +             0.026         6764
+@end example
+
+This shows that most of the runtime was spent executing the function
+@samp{myfib}, and some minor proportion evaluating the listed binary operators.
+Furthermore, it is shown how often the function was called and the profiler
+also found out that it is recursive.
+
+@DOCSTRING(profshow)