home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / p / python / pyhtmldoc / r / reference_ < prev    next >
Text File  |  1996-11-14  |  4KB  |  92 lines
  1. <TITLE>Reference Manual -- Python library reference</TITLE>
  2. Next: <A HREF="../l/limitations" TYPE="Next">Limitations</A>  
  3. Prev: <A HREF="../d/deterministic_profiling" TYPE="Prev">Deterministic Profiling</A>  
  4. Up: <A HREF="../t/the_python_profiler" TYPE="Up">The Python Profiler</A>  
  5. Top: <A HREF="../t/top" TYPE="Top">Top</A>  
  6. <H1>9.5. Reference Manual</H1>
  7. The primary entry point for the profiler is the global function
  8. <CODE>profile.run()</CODE>.  It is typically used to create any profile
  9. information.  The reports are formatted and printed using methods of
  10. the class <CODE>pstats.Stats</CODE>.  The following is a description of all
  11. of these standard entry points and functions.  For a more in-depth
  12. view of some of the code, consider reading the later section on
  13. Profiler Extensions, which includes discussion of how to derive
  14. ``better'' profilers from the classes presented, or reading the source
  15. code for these modules.
  16. <P>
  17. <DL><DT><B>profile.run</B> (<VAR>string</VAR>[, <VAR>filename</VAR>[, ...]]) -- profiler function<DD>
  18. This function takes a single argument that has can be passed to the
  19. <CODE>exec</CODE> statement, and an optional file name.  In all cases this
  20. routine attempts to <CODE>exec</CODE> its first argument, and gather profiling
  21. statistics from the execution. If no file name is present, then this
  22. function automatically prints a simple profiling report, sorted by the
  23. standard name string (file/line/function-name) that is presented in
  24. each line.  The following is a typical output from such a call:
  25. <P>
  26. @small{
  27. <UL COMPACT><CODE>      main()<P>
  28.       2706 function calls (2004 primitive calls) in 4.504 CPU seconds<P>
  29. <P>
  30. Ordered by: standard name<P>
  31. <P>
  32. ncalls  tottime  percall  cumtime  percall filename:lineno(function)<P>
  33.      2    0.006    0.003    0.953    0.477 pobject.py:75(save_objects)<P>
  34.   43/3    0.533    0.012    0.749    0.250 pobject.py:99(evaluate)<P>
  35.  ...<P>
  36. </CODE></UL>
  37. }
  38. <P>
  39. The first line indicates that this profile was generated by the call:*
  40. <CODE>profile.run('main()')</CODE>, and hence the exec'ed string is
  41. <CODE>'main()'</CODE>.  The second line indicates that 2706 calls were
  42. monitored.  Of those calls, 2004 were <DFN>primitive</DFN>.  We define
  43. <DFN>primitive</DFN> to mean that the call was not induced via recursion.
  44. The next line: <CODE>Ordered by: standard name</CODE>, indicates that
  45. the text string in the far right column was used to sort the output.
  46. The column headings include:
  47. <P>
  48. <DL>
  49. <DT><B>ncalls</B><DD>for the number of calls, 
  50. <P>
  51. <DT><B>tottime</B><DD>for the total time spent in the given function (and excluding time
  52. made in calls to sub-functions),
  53. <P>
  54. <DT><B>percall</B><DD>is the quotient of <CODE>tottime</CODE> divided by <CODE>ncalls</CODE>
  55. <P>
  56. <DT><B>cumtime</B><DD>is the total time spent in this and all subfunctions (i.e., from
  57. invocation till exit). This figure is accurate <I>even</I> for recursive
  58. functions.
  59. <P>
  60. <DT><B>percall</B><DD>is the quotient of <CODE>cumtime</CODE> divided by primitive calls
  61. <P>
  62. <DT><B>filename:lineno(function)</B><DD>provides the respective data of each function
  63. <P>
  64. </DL>
  65. When there are two numbers in the first column (e.g.: `<SAMP>43/3</SAMP>'),
  66. then the latter is the number of primitive calls, and the former is
  67. the actual number of calls.  Note that when the function does not
  68. recurse, these two values are the same, and only the single figure is
  69. printed.
  70. <P>
  71. </DL>
  72. <DL><DT><B>pstats.Stats</B> (<VAR>filename</VAR>[, ...]) -- profiler function<DD>
  73. This class constructor creates an instance of a ``statistics object''
  74. from a <VAR>filename</VAR> (or set of filenames).  <CODE>Stats</CODE> objects are
  75. manipulated by methods, in order to print useful reports.
  76. <P>
  77. The file selected by the above constructor must have been created by
  78. the corresponding version of <CODE>profile</CODE>.  To be specific, there is
  79. <I>NO</I> file compatibility guaranteed with future versions of this
  80. profiler, and there is no compatibility with files produced by other
  81. profilers (e.g., the old system profiler).
  82. <P>
  83. If several files are provided, all the statistics for identical
  84. functions will be coalesced, so that an overall view of several
  85. processes can be considered in a single report.  If additional files
  86. need to be combined with data in an existing <CODE>Stats</CODE> object, the
  87. <CODE>add()</CODE> method can be used.
  88. </DL>
  89. <H2>Menu</H2><DL COMPACT>
  90. <DT><A HREF="../t/the_stats_class" TYPE=Menu>The Stats Class</A>
  91. <DD></DL>
  92.