3.4 Profiling: the Profile structure

3.4.4 Specifying scan frequency and profiling manner details

As we have seen, the profile function takes an argument options, which is a value of type options:

datatype options =
  Options of
  {scan : int,
   selector : function_id -> manner}

The fields are:

scan: The interval in "user" milliseconds between scans of the stack. If scan is 0, no scans will occur. (By "user" milliseconds, we mean milliseconds of execution time that are devoted solely to running your program, rather than on MLWorks internals.)
: The profiler may not be able to respect very small values for scan, because it relies on the underlying operating system clock. See options, page 34, for details of choosing a realistic value for scan.
selector: A function that determines the manner that will be used when profiling a particular function. When the profiler is invoked, the selector function is applied to every function in the MLWorks heap -- including those of MLWorks internals.

The selector function should take a value of type function_id. Function IDs are strings that begin with the name of the function they identify, but that also contain source and, possibly, compilation information. MLWorks generates a function ID for every function it compiles; you do not have to generate them yourself. The selector function should return a value of type manner.

An example best explains how manners and selectors are used. Suppose that an application contains a set of functions for writing data to disk. The functions write data in differing quantities: write_element, write_line, and write_record. Being involved in disk I/O, these functions spend a lot of time in execution. On the other hand, they are not called very often. You might construct a specific profiling manner for these functions, write_fns_manner, which ensures that time-profiling and space-profiling data is collected for write functions, but that call counts are not.

To construct the manner:

val write_fns_manner = make_manner { 
  time = true, 
  space = true, 
  calls = false,
  copies = true,
  depth = 1,
  breakdown = [ TOTAL ] 
};

See make_manner, page 30, for more details. A suitable selector function might be:

local 
  fun is_write_fn s = String.size s >= 5
    andalso String.substring (s,0,5) = "write"
in
  fun my_selector s = if is_write_fns s then write_fns_manner 
                      else generic_manner
end;

This selector returns write_fns_manner for profiling any function whose identifier has the prefix write. Any other function will be profiled with the manner generic_manner.

Now you can construct a set of options to pass to profile. A scan value of 10 (100 clock ticks per second) or so is typical on both UNIX and Windows.

val my_options = Options { scan = 10, selector = my_selector };

MLWorks Reference Manual (version 1.0) - 3 DEC 1996

Generated with Harlequin WebMaker