doc/guide/src/ProfilingCounts.adoc

   1 ProfilingCounts
   2 ===============
   3
   4 With MLton and `mlprof`, you can <:Profiling:profile> your program to
   5 find out how many times each function is called and how many times
   6 each branch is taken.  To do so, compile your program with
   7 `-profile count -profile-branch true`. For example, suppose that
   8 `tak.sml` contains the following.
   9
  10 [source,sml]
  11 ----
  12 sys::[./bin/InclGitFile.py mlton master doc/examples/profiling/tak.sml]
  13 ----
  14
  15 Compile with count profiling and run the program.
  16 ----
  17 % mlton -profile count -profile-branch true tak.sml
  18 % ./tak
  19 ----
  20
  21 Display the profiling data, along with raw counts and file positions.
  22 ----
  23 % mlprof -raw true -show-line true tak mlmon.out
  24 623,610,002 ticks
  25             function               cur       raw
  26 --------------------------------- ----- -------------
  27 Tak.tak1.tak2  tak.sml: 5         38.2% (238,530,000)
  28 Tak.tak1.tak2.<true>  tak.sml: 7  27.5% (171,510,000)
  29 Tak.tak1  tak.sml: 3              10.7%  (67,025,000)
  30 Tak.tak1.<true>  tak.sml: 14      10.7%  (67,025,000)
  31 Tak.tak1.tak2.<false>  tak.sml: 9 10.7%  (67,020,000)
  32 Tak.tak1.<false>  tak.sml: 16      2.0%  (12,490,000)
  33 f  tak.sml: 23                     0.0%       (5,001)
  34 f.<branch>  tak.sml: 25            0.0%       (5,000)
  35 f.<branch>  tak.sml: 23            0.0%           (1)
  36 uncalled  tak.sml: 29              0.0%           (0)
  37 f.<branch>  tak.sml: 24            0.0%           (0)
  38 ----
  39
  40 Branches are displayed with lexical nesting followed by `<branch>`
  41 where the function name would normally be, or `<true>` or `<false>`
  42 for if-expressions.  It is best to run `mlprof` with `-show-line true`
  43 to help identify the branch.
  44
  45 One use of `-profile count` is as a code-coverage tool, to help find
  46 code in your program that hasn't been tested.  For this reason,
  47 `mlprof` displays functions and branches even if they have a count of
  48 zero.  As the above output shows, the branch on line 24 was never
  49 taken and the function defined on line 29 was never called.  To see
  50 zero counts, it is best to run `mlprof` with `-raw true`, since some
  51 code (e.g. the branch on line 23 above) will show up with `0.0%` but
  52 may still have been executed and hence have a nonzero raw count.