.\" ---------------------- seca2.t ----------------------
.sh 1 "Profiling Programs"
.pp
SB-Prolog provides a utility for profiling programs interactively.  Two kinds of
profiling are supported: one may count the number of calls to a predicate,
or compute the time spent in a predicate.  It is important that the
predicates being profiled are either consulted, or compiled with the \fBt\fR
option, so that calls to the relevant predicates can be intercepted by the
profiler.
.pp
To use the profiler, predicates whose calls are to be counted must be
passed to \fIcount\fR/1, e.g.
.(l
	| ?\- count([\fIp\fR/1, \fIq\fR/2]), count(\fIr\fR/3).
.)l
will set up ``count-points'' on the predicates \fIp\fR/1, \fIq\fR/2 and
\fIr\fR/3.  Predicates whose calls are to be timed have to be passed to
\fItime\fR/1, e.g.
.(l
	| ?\- time([\fIs\fR/1, \fIt\fR/2]), time(\fIu\fR/3).
.)l
will set up ``time-points'' on the predicates \fIs\fR/1, \fIt\fR/2 and
\fIu\fR/3.  It is possible to set both count-points and time-points on the
same predicate.  After count-points and time-points have been set, the
program may be executed as many times as desired: the profiling system will
accumulate call counts and execution times for the appropriate predicates.
Execution profiles may be obtained using the
predicates \fIprof_\|stats\fR/0 or \fIprof_\|stats\fR/1.  Using
\fIprof_\|stats\fR/0 to display the execution profile will cause the call
counts and execution times of predicates being profiled to be reset to 0
(this may be avoided by using \fIprof_\|stats\fR/1).
.pp
It should be noted that in this context, the ``execution time'' for a predicate
is an estimate of the total time spent in the subtrees below calls to that
predicate (including failed subtrees): thus, the execution time figures may
be dilated slightly if the subtree below a timed predicate contains
predicates that are being profiled, because of the time taken for updating
the call counts and execution times.  For each predicate, the execution
time is displayed as the fraction of time spent, in computation in subtrees
under calls to that predicate, relative to the time elapsed from the last
time profiling was timed on or the last time profiling statistics were
taken, whichever was more recent.
.pp
The following summarizes the library predicates supporting
profiling:
.sp
.lp
\fBcount\fR(\fIL\fR)
.(x b
(L)	 count/1
.)x
.ip
Sets up a count-point on the predicates \fIL\fR, which causes calls to
these predicates to be counted, and turns profiling on.  \fIL\fR is either
a term \fIPred\fR/\fIArity\fR, where \fIPred\fR is a predicate
symbol and \fIArity\fR its arity, or a set of such terms represented as a list.
\fIL\fR must be instantiated, and the predicates specified in it defined, at
the time of the call to \fIcount\fR/1.  
.lp
\fBtime\fR(\fIL\fR)
.(x b
(L)	 time/1
.)x
.ip
Sets up a time-point on the predicates \fIL\fR, which causes execution times
for calls to these predicates to be accumulated, and turns profiling on.
\fIL\fR is either a term \fIPred\fR/\fIArity\fR, where \fIPred\fR is a predicate
symbol and \fIArity\fR its arity, or a set of such terms represented as a list.
\fIL\fR must be instantiated, and the predicates specified in it defined, at
the time of the call to \fItime\fR/1.  
.lp
.lp
\fBnocount\fR(\fIL\fR)
.(x b
(L)	 nocount/1
.)x
.ip
Deletes the count-point on the predicates \fIL\fR.  \fIL\fR is either a term
\fIPred\fR/\fIArity\fR, where \fIPred\fR is a predicate
symbol and \fIArity\fR its arity, or a set of such terms represented as a list.
\fIL\fR must be instantiated, and the predicates specified in it defined, at
the time of the call to \fInocount\fR/1.
.lp
\fBnotime\fR(\fIL\fR)
.(x b
(L)	 notime/1
.)x
.ip
Deletes the time-point on the predicates \fIL\fR.  \fIL\fR is either a term
\fIPred\fR/\fIArity\fR, where \fIPred\fR is a predicate
symbol and \fIArity\fR its arity, or a set of such terms represented as a list.
\fIL\fR must be instantiated, and the predicates specified in it defined, at
the time of the call to \fItime\fR/1.
.lp
\fBprofiling\fR
.(x b
(L)	 profiling/0
.)x
.ip
Displays information about whether profile mode is on or not, and lists
predicates that have count- and time-points set on them.
.lp
\fBprof_\|reset\fR(\fIL\fR)
.(x b
(L)	 prof_\|reset/1
.)x
.ip
Resets call counts and/or execution times for the predicates \fIL\fR.
\fIL\fR is either a term \fIPred\fR/\fIArity\fR, where \fIPred\fR is
a predicate symbol and \fIArity\fR its arity, or a set of such terms
represented as a list.  \fIL\fR must be instantiated, and the predicates
specified in it defined, at the time of the call to \fIprof_\|reset\fR/1.
.lp
\fBresetcount\fR(\fIL\fR)
.(x b
(L)	 resetcount/1
.)x
.ip
Resets call counts for the predicates \fIL\fR.
\fIL\fR is either a term \fIPred\fR/\fIArity\fR, where \fIPred\fR is
a predicate symbol and \fIArity\fR its arity, or a set of such terms
represented as a list.  \fIL\fR must be instantiated, and the predicates
specified in it defined, at the time of the call to \fIresetcount\fR/1.
.lp
\fBresettime\fR(\fIL\fR)
.(x b
(L)	 resettime/1
.)x
.ip
Resets execution times for the predicates \fIL\fR.
\fIL\fR is either a term \fIPred\fR/\fIArity\fR, where \fIPred\fR is
a predicate symbol and \fIArity\fR its arity, or a set of such terms
represented as a list.  \fIL\fR must be instantiated, and the predicates
specified in it defined, at the time of the call to \fBresettime\fR/1.
.lp
\fBprofile\fR
.(x b
(L)	 profile/0
.)x
.ip
Turns profiling on.  This causes subsequent execution of predicates with
count- or time-points to be profiled, and is a no-op if there are no such
predicates.  The predicates \fIcount\fR/1 and \fItime\fR/1 cause profiling
to be turned on automatically.
.lp
\fBnoprofile\fR
.(x b
(L)	 noprofile/0
.)x
.ip
Turns profiling off.  This causes count- and time-points to be ignored.
.lp
\fBtimepreds\fR(\fIL\fR)
.(x b
(L)	 timepreds/1
.)x
.ip
Unifies \fIL\fR to a list of terms \fIP\fR/\fIN\fR where the predicate
\fIP\fR of arity \fIN\fR has a time point set on it.
.lp
\fBcountpreds\fR(\fIL\fR)
.(x b
(L)	 countpreds/1
.)x
.ip
Unifies \fIL\fR to a list of terms \fIP\fR/\fIN\fR where the predicate
\fIP\fR of arity \fIN\fR has a count point set on it.
.lp
\fBprof_\|stats\fR
.(x b
(L)	 prof_\|stats/0
.)x
.ip
Causes the call counts and/or execution times accumulated since the last
call to \fIprof_\|stats\fR/0 to be printed out for predicates that are
being profiled.  The execution times are given as fractions of the total
time elapsed since the last time profiling was turned on, or the last time
\fIprof_\|stats\fR was called, whichever was most recent.  This also
results in the call counts and relative execution times of these predicates
being reset to 0.  Equivalent to \fIprof_\|stats\fR(1).
.lp
\fBprof_\|stats\fR(\fIN\fR\^)
.(x b
(L)	 prof_\|stats/1
.)x
.ip
Causes the call counts and/or execution times accumulated since the last
call to \fIprof_\|stats\fR/0 to be printed out for predicates that are
being profiled.  The execution times are given as fractions of the total
time elapsed since the last time profiling was turned on, or the last time
\fIprof_\|stats\fR was called, whichever was most recent.  If \fIN\fR is
1, then this also results in the call counts and execution times of these
predicates being reset to 0; otherwise, the call counts and execution times
are not reset.
.\" ---------------------- end of section seca2.t ----------------------