PROFILE - profiling the execution of a B program.

Syntax:

boff PRofile hstar[,module] [SOurce=file]
             [options] ["command line"]

(+|-)Timing (-)        (+|-)Byline (+)

Examples:

boff pr .h so=/bprog
boff prof file,module "cmd +progopt"

Options:

hstar[,module]: is the name of the hstar file containing the program to be profiled. If this file contains more than one module, the "module" field must be included to specify which module is to be profiled.
SOurce=srcfile: specifies a single file containing B, C, or Pascal source code for the program. This file may not contain any "inclusion" directives.
+Timing: turns on timing. With this option in effect, the profiler will tell how long the program stays within each function.
-Byline: turns off the line-by-line trace (as described below).
"command line": is the command line for the program that you will be profiling.

Description:

The PRofile mode of BOFF lets you obtain a profile of a program as it runs. When the program has finished execution, BOFF will create a file called ".profile" and write execution statistics to this file. The profiler can tell how many times each function is called, the number of times each function is called recursively, the number of times each line of source code was executed, and the time spent inside each function.

If SOurce=file is used to specify a source file, and if the +Byline option is in effect, BOFF will try to match executable code to lines in the source file and describe how often each line was executed. Beside each executable statement, BOFF will print

TYPE  LL  PL  N  INST

where

TYPE: is a short word indicating the type of statement (e.g. "assign" for assignments, "while" for while loops, etc.).
LL: is the logical line number. Each new executable statement in a program is assigned the next consecutive logical line number. The first executable statement in a program has LL=1, even if there are many preceding source lines (e.g. declarations).
PL: is the physical line number. This is the number of the line in the source file.
N: is the number of times the statement is executed in the course of program execution.
I: is the number of machine instructions generated to implement the corresponding statement.

This output is not produced if the "-Byline" option is specified.

Output from the BOFF PRofiler also lists the external symbols defined for the program. It also gives how many times each function is executed, and how many times each function is executed recursively (i.e. while there is another invocation of that function already active).

Timing

BOFF's timing facilities can be invoked with "+Timing", provided that the dispatcher of your version of TSS contains modifications to allow such timing. There is no way for BOFF to find out if your TSS contains these modifications; if you specify +Timing without these modifications, the timing results will be meaningless. The modifications are available from Thinkage.

When "+Timing" is in effect, BOFF prints out the total CPU time spent inside each function, and the average CPU time. The time spent inside a function begins when the function is invoked and ends when the function returns. Therefore, the total time spent inside "main" will be the total running time of the program. All times are given in terms of CPU minutes.

The average time spent inside a function is just calculated from the total time divided by the number of function calls.

Note that recursion has an odd effect on calculating average times. Timing for a function begins when that function is first invoked. If the function is called recursively (before the previous invocation has returned), BOFF knows that it is already timing the function so it won't time the recursion individually; however, BOFF does add the recursive invocation to the number of times that the function has been invoked.

As a result, BOFF is only timing the top level function, but it is counting all the recursive invocations. This affects the average, since the time of the top function is averaged over all the recursive invocations. In our opinion, this gives a fairer picture of what the function is doing than any of the other ways to calculate the average; but we should point out that it may give surprising results on occasion.

The timing given by this option will vary depending on the type of processor that your machine has.

Notes:

The +Timing option adds an overhead of about 20% to the running time of your program. It is equivalent to about 20 more instructions per function call.

The +Byline option also adds overhead to running time. In addition, it requires a good deal of extra memory -- if your program is large to begin with, the extra memory requirements of +Byline may exceed space limitations.