MONITOR(3C) — Silicon Graphics

NAME

monitor, resume_prof, suspend_prof − prepare execution profile

SYNOPSIS

void monitor (lowpc, highpc, buffer, bufsize, nfunc)
int (∗lowpc)( ), (∗highpc)( );
short ∗buffer;
int bufsize, nfunc;

void resume_prof ()

void suspend_prof ()

DESCRIPTION

An executable program created by cc −p automatically includes a call to monitor with default parameters. Explicit calls to monitor are not recommended unless the executable being profiled needs larger profiling buffers. In this case, it is recommended that monitor only be called once from main, and that it be called early in the program.

Monitor is an interface to profil(2). Lowpc and highpc are the addresses of two functions; buffer is the address of a (user supplied) array of bufsize short integers. Monitor arranges to record a histogram of periodically sampled values of the program counter, and of counts of calls of certain functions, in the buffer. The lowest address sampled is that of lowpc and the highest is just below highpc. Lowpc may not equal 0 for this use of monitor. At most nfunc call counts can be kept; only calls of functions compiled with the profiling option −p of cc(1) are recorded. (The C Library and Math Library supplied when cc -p is used also have call counts recorded.) For the results to be significant, especially where there are small, heavily used routines, it is suggested that the buffer be no more than a few times smaller than the range of locations sampled.

To profile the entire program, it is sufficient to use

extern etext;
...
monitor ((int (∗)())2, &etext, buf, bufsize, nfunc);

Etext lies just above all the program text; see end(3C).

To stop execution monitoring and write the results on the file mon.out, use

monitor ((int (∗)())NULL, 0, 0, 0, 0);

This call is performed by default before program exit.

prof(1) can then be used to examine the results.

After monitor has been invoked to set up the profiling buffers, profiling can be suspended and resumed during the program’s execution by invoking suspend_prof and resume_prof. These functions simply suspend and resume the accumulation of profiling time and invocation counts, using the buffers set up by the last call to monitor. A few simple rules must be followed when using suspend_prof and resume_prof to ensure that the histogram information accumulated by the program is consistent:

1) monitor must be called prior to any calls to suspend_prof and resume_prof.

2) Prior to entering a portion of the program on which profiling data is not desired, suspend_prof should be called.

3) If profiling is to resume, profiling must be resumed in the same function in which it was suspended. Profiling is resumed by calling resume_prof.

EXAMPLE

Users of the spline program below have complained of slowness in generating the menu on the screen. As the great majority of time in spline is spent performing calculations, it is helpful to exclude from profiling all but the function responsible for generating the menu. Below is an extract from the main routine of spline in which profiling has been suspended except during menu display:

main(argc,argv)
<declarations>
suspend_prof();
/* loop on the menu selection until valid input */
do {
resume_prof();
display_menu();
suspend_prof();
input_ok = select();
} while (!input_ok);

The resultant profile file will only contain data gathered during the display_menu routine.

FILES

mon.out

Museum