3.4.9 Profile structure values

function_time_profile

Type

Summary

Records time-profiling information gathered for a particular function.

Signature

MLWORKS.Profile

Structure

MLWorks.Profile

Type

datatype function_time_profile = 
  Function_Time_Profile of 
    {found: int,
     top: int,
     scans: int,
     depth: int,
     self: int,
     callers: function_caller list}

Description

This datatype records time-profiling information about a function. If you ask the profiler to time-profile a particular function, the results of profiling will be stored in a function_time_profile value in the time field of the function_profile returned by the profiler. See make_manner for a discussion of how to ask for time profiling.

The record contains the following data:

found: The number of times that the function was found on the stack. This will be -1 if time profiling was not requested in the profiling manner used.
top: The number of times that the function was found on the top of the stack.
scans: The number of scans in which the function was found on the stack at least once.
depth: The maximum number of recursions performed in a single scan.
self: The maximum number of self-recursions performed in a single scan.
callers: A list of the functions that called the profiled function, with timing data for those functions attached.

Roughly, top indicates how much time was spent in f alone, and scans how much time was spent in f and all the functions it called. The average recursion of the function is roughly found divided by scans, and depth and self are indicators of the maximum recursion of the function. These are all rough indicators because of the random element introduced by time-based sampling and because optimizations such as tail-call removal have an effect on the stack.

Example

Suppose the function f was found in two scans. On the first occasion the stack looked like this (the top of the stack is listed first):

f,f,f,f,g,f,g,f,g,f,g,f,g,f,g,f

On the second occasion it looked like this (the top is again listed first):

g,g,g,g,f,g,f,g,f,g,f,f,g,g,f,f

Then:

found would be 17.

top would be 1. (From the first scan.)

scans would be 2.

depth would be 9. (From the first scan.)

self would be 3. (From the first scan.)