1\function{profile_on}
2\synopsis{Enable code generation to support profiling hooks}
3\usage{profile_on ( [line_by_line] )}
4\description
5  This function will turn cause the interpreter to generate code to
6  call hooks that are used to profile code.  The \exmp{profile_on}
7  function does not establish those hooks, rather it causes code to be
8  generated to support such hooks.
9
10  With no optional argument, only code to support function call hooks
11  will be generated.  To enable support for line-by-line profile
12  hooks, a value of 1 should be passed to this function.
13\seealso{profile_off, profile_begin, profile_end, profile_calibrate, profile_report}}
14\done
15
16\function{profile_off}
17\synopsis{Turn off code generation for profiling hooks}
18\usage{profile_off ()}
19\description
20  This function turns off the generation of code to support profiling
21  hooks.
22\seealso{profile_on, profile_begin, profile_end, profile_calibrate, profile_report}}
23\done
24
25\function{profile_begin}
26\synopsis{Establish profiling hooks and reset the profiler}
27\usage{profile_begin ( [line_by_line] )}
28\description
29  This function establishes the profiling hooks and resets or
30  initializes the profiler state.  By default, only hooks to gather
31  function call information are created.  To enable the gathering of
32  line-by-line information, a value of 1 should be passed to this
33  function.
34\seealso{profile_end, profile_on, profile_off, profile_calibrate, profile_report}}
35\done
36
37\function{profile_end}
38\synopsis{Remove profiling hooks and turn off profiler code generation}
39\usage{profile_end ()}
40\description
41  The \sfun{profile_end} function turns off the code generation to
42  support profiling hooks and removes any profiling hooks that are in
43  place.
44\seealso{profile_begin, profile_on, profile_off, profile_calibrate, profile_report}
45\done
46
47\function{profile_calibrate}
48\synopsis{Calibrate the profiler}
49\usage{profile_calibrate ([ N ])}
50\description
51 This function may be used to ``calibrate'' the profiler.  As the
52 performance of the profiler and the interpreter varies with a
53 platform and load-dependent manner, this function should be called
54 prior to enabling the profiler.  It tries to determine the average
55 amount of overhead per statement executed and function call by
56 executing a series of statements and functions many times to
57 determine statistically accurate values.  The optional parameter
58 \exmp{N} may be used to control the amount of code executed
59 for the calibration process.  If no value is provided, the \exmp{N}
60 will default to 1000.  The higher the value, the more accurate the
61 calibration will be and the longer the calibration process will take.
62\seealso{profile_begin, profile_end, profile_on, profile_off, profile_report}
63\done
64
65\function{profile_report}
66\synopsis{Generate the profile report}
67\usage{profile_report (file)}
68\description
69  The function may be used to format the profile report and write it
70  to the specified file.  If the \exmp{file} parameter represents a
71  \dtype{File_Type} file descriptor, then the report will be written
72  the the descriptor.
73\seealso{profile_begin, profile_end, profile_on, profile_off, profile_calibrate}
74\done
75