NAME

profile - profiling library

SYNOPSIS

include "profile.m";

profile := load Profile Profile->PATH;

Range: adt{
    l: int;
    u: int;
    f: int;
    n: cyclic ref Range;
};

Funprof: adt{
    name: string;
    line: int;
    count: int;
    counte: int;
};

Modprof: adt{
    name: string;
    path: string;
    srcpath: string;
    rawtab: array of (int, int);
    linetab: array of int;
    rngtab: array of ref Range;
    funtab: array of Funprof;
    total: int;
    totals: array of int;
    covered: int;
};

Prof: adt{
    mods: list of Modprof;
    total: int;
    totals: array of int;
};

Coverage: type list of (string, int, list of (list of (int, int, byte), string));

MODULE: con 1;	# give stats for each module
FUNCTION: con 2;	# give stats for each function
LINE: con 4;	# give stats for each line
VERBOSE: con 8;	# full stats
FULLHDR: con 16;	# file:lineno: on each line of output
FREQUENCY: con 32;	# show frequency rather than coverage

init: fn(): int;
profile: fn(m: string): int;
sample: fn(i: int): int;
start: fn(): int;
stop: fn(): int;
stats: fn() : Prof;
show: fn(p: Prof, v: int): int;
end: fn(): int;

# coverage profiling specific functions

cpstart: fn(pid: int): int;
cpstats: fn(rec: int, v: int): Prof;
cpfstats: fn(v: int): Prof;
cpshow: fn(p: Prof, v: int): int;

coverage: fn(p: Prof, v: int): Coverage;

# memory profiling specific functions

memstart: fn(): int;
memstats: fn(): Prof;
memshow: fn(p: Prof, v: int): int;

lasterror: fn(): string;

DESCRIPTION

Profile provides an interface to the kernel profile device. It contains routines to start and stop profiling, to gather profiling statistics and to display these statistics in relation to the relevant limbo source code. All of these routines apart from lasterror return a negative integer if an error occurred during their execution. Once this happens, a call to lasterror will give the error message.

init initializes the module and binds the kernel profile device onto the /prof directory. It should be called before any other functions in this module.

profile takes a module name or a path name as its argument and indicates a module to be profiled. Repeated calls of this function allow a number of modules to be profiled together. In the absence of any calls to this routine, the profile device profiles all modules loaded by the kernel.

sample sets the sampling interval of the profiling. The argument is in ms. The default value in the profile device is 100ms.

start starts profiling.

stop stops profiling.

stats returns profiling statistics. It is recommended that this is called once profiling has been stopped, otherwise the results may be slightly inaccurate. It returns an adt of type Prof. Its first field mods is a list of profile statistics for each module under profile. Its second field total is the number of samples made altogether. The statistics for each module are represented in the Modprof adt. Its fields are

name

The name of the module.

path

The path of the module's corresponding dis file.

srcpath

The path of the module's corresponding source file.

linetab

The line frequency count table. The number of samples made on a particular line of the above source file is found by indexing this table.

funtab

The function frequency count table. This array of Funprof adt gives the name, line number and number of samples made for each function in the above source file.

total

The total number of samples made in this module.

stats will ignore modules if it fails to locate the symbol (.sbl) file for a particular dis file.

show simply prints out the profile information returned by stats. For each module it will print out either the line number statistics or the function statistics or both. The former gives the line number, percentage of time spent on this line and the source code for each line in the source file. The latter gives the line number, function name and percentage of time spent in this function for each function in the source file. The amount of output can be controlled by the second argument to show. The following should be ored together in the required combination to get the desired effect.

FUNCTION

Print the function table.

LINE

Print the line number table.

VERBOSE

Normally lines and functions are not shown if the sample frequency for them is zero. This option prevents this.

FULLHDR

Prints the file name as well as the line number in a form that can be selected in acme to show that particular line in a window.

show will ignore modules if it fails to locate the source (.b) file for a particular dis file.

end ends the profiling session. This should be called when all statistics have been gathered in order to clean up the device profile's data structures.

In order to support coverage profiling as well the following new routines are provided.

cpstart Start coverage profiling on the process whose pid is given.

cpstats Returns coverage profiling statistics from the profile device. If the first argument is true, the raw results will be stored in a profile file whose name is <file>.prf where <file> is the prefix of the corresponding dis file.

cpfstats Returns coverage profiling statistics from any saved profile files.

cpshow Shows the coverage profiling statistics.

coverage Given the coverage profiler statistics this returns the list of modules profiled. Each module has a name, a boolean indicating whether all instructions in the module were executed and a list of lines. Each line consists of a list of ranges and the source code. The list of ranges contains the character positions on the line of code corresponding to instructions that were not executed and an indicator of whether partial execution was performed.

For the further support of memory profiling the following routines are available.

memstart Start memory profiling.

memstats Return the memory profile statisics.

memshow Send memory profile statistics to standard output.

SOURCE

/module/profile.m
/appl/lib/profile.b

SEE ALSO

prof(3)

PROFILE(2 )

Rev:  Tue Mar 31 02:42:39 GMT 2015