3.4.9 Profile structure values

function_time_profile

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.)

See also

function_caller, page 38

function_profile, page 35

Generated with Harlequin WebMaker