Doc/lib/libhotshot.tex

   1 \section{\module{hotshot} ---
   2          High performance logging profiler}
   3
   4 \declaremodule{standard}{hotshot}
   5 \modulesynopsis{High performance logging profiler, mostly written in C.}
   6 \moduleauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
   7 \sectionauthor{Anthony Baxter}{anthony@interlink.com.au}
   8
   9 \versionadded{2.2}
  10
  11
  12 This module provides a nicer interface to the \module{_hotshot} C module.
  13 Hotshot is a replacement for the existing \refmodule{profile} module. As it's
  14 written mostly in C, it should result in a much smaller performance impact
  15 than the existing \refmodule{profile} module.
  16
  17 \begin{classdesc}{Profile}{logfile\optional{,
  18                            lineevents\code{=0}\optional{,
  19                            linetimings\code{=1}}}}
  20 The profiler object. The argument \var{logfile} is the name of a log
  21 file to use for logged profile data. The argument \var{lineevents}
  22 specifies whether to generate events for every source line, or just on
  23 function call/return. It defaults to \code{0} (only log function
  24 call/return). The argument \var{linetimings} specifies whether to
  25 record timing information. It defaults to \code{1} (store timing
  26 information).
  27 \end{classdesc}
  28
  29
  30 \subsection{Profile Objects \label{hotshot-objects}}
  31
  32 Profile objects have the following methods:
  33
  34 \begin{methoddesc}{addinfo}{key, value}
  35 Add an arbitrary labelled value to the profile output.
  36 \end{methoddesc}
  37
  38 \begin{methoddesc}{close}{}
  39 Close the logfile and terminate the profiler.
  40 \end{methoddesc}
  41
  42 \begin{methoddesc}{fileno}{}
  43 Return the file descriptor of the profiler's log file.
  44 \end{methoddesc}
  45
  46 \begin{methoddesc}{run}{cmd}
  47 Profile an \keyword{exec}-compatible string in the script environment.
  48 The globals from the \refmodule[main]{__main__} module are used as
  49 both the globals and locals for the script.
  50 \end{methoddesc}
  51
  52 \begin{methoddesc}{runcall}{func, *args, **keywords}
  53 Profile a single call of a callable.
  54 Additional positional and keyword arguments may be passed
  55 along; the result of the call is returned, and exceptions are
  56 allowed to propogate cleanly, while ensuring that profiling is
  57 disabled on the way out.
  58 \end{methoddesc}
  59
  60
  61 \begin{methoddesc}{runctx}{cmd, globals, locals}
  62 Evaluate an \keyword{exec}-compatible string in a specific environment.
  63 The string is compiled before profiling begins.
  64 \end{methoddesc}
  65
  66 \begin{methoddesc}{start}{}
  67 Start the profiler.
  68 \end{methoddesc}
  69
  70 \begin{methoddesc}{stop}{}
  71 Stop the profiler.
  72 \end{methoddesc}
  73
  74
  75 \subsection{Using hotshot data}
  76
  77 \declaremodule{standard}{hotshot.stats}
  78 \modulesynopsis{Statistical analysis for Hotshot}
  79
  80 \versionadded{2.2}
  81
  82 This module loads hotshot profiling data into the standard \module{pstats}
  83 Stats objects.
  84
  85 \begin{funcdesc}{load}{filename}
  86 Load hotshot data from \var{filename}. Returns an instance
  87 of the \class{pstats.Stats} class.
  88 \end{funcdesc}
  89
  90 \begin{seealso}
  91   \seemodule{profile}{The \module{profile} module's \class{Stats} class}
  92 \end{seealso}
  93
  94
  95 \subsection{Example Usage \label{hotshot-example}}
  96
  97 Note that this example runs the python ``benchmark'' pystones.  It can
  98 take some time to run, and will produce large output files.
  99
 100 \begin{verbatim}
 101 >>> import hotshot, hotshot.stats, test.pystone
 102 >>> prof = hotshot.Profile("stones.prof")
 103 >>> benchtime, stones = prof.runcall(test.pystone.pystones)
 104 >>> prof.close()
 105 >>> stats = hotshot.stats.load("stones.prof")
 106 >>> stats.strip_dirs()
 107 >>> stats.sort_stats('time', 'calls')
 108 >>> stats.print_stats(20)
 109          850004 function calls in 10.090 CPU seconds
 110
 111    Ordered by: internal time, call count
 112
 113    ncalls  tottime  percall  cumtime  percall filename:lineno(function)
 114         1    3.295    3.295   10.090   10.090 pystone.py:79(Proc0)
 115    150000    1.315    0.000    1.315    0.000 pystone.py:203(Proc7)
 116     50000    1.313    0.000    1.463    0.000 pystone.py:229(Func2)
 117  .
 118  .
 119  .
 120 \end{verbatim}