Using the Statistics Facility

The statistics tool is predicate based. The user can switch on statistics collection for all predicates or for selected ones.

The statistics tool is closely related to the debugger. In order to apply it to a program, this program must be compiled in dbgcomp-mode and it must be run with the debugger switched on.

A sample output from the statistics tool looks like this:

 PROCEDURE         #    MODULE    #CALL   #EXIT    #TRY    #CUT   #NEXT   #FAIL
true               /0   sepia_k       2       2       0       0       0       0
fail               /0   sepia_k      27       0       0       0       0      27
set_flag           /3   sepia_k       1       1       0       0       0       0
env                /0   sepia_k       1       1       1       0       2       0
spaces             /1   sepia_k     309     309     309     286      23       0
!                  /0   sepia_k     286     286       0       0       0       0
open               /3   sepia_k       1       1       0       0       0       0
|TOTAL:     PROCEDURES: 7           627     600     310     286      25      27

The numbers show how often the execution passed the various predicate ports (for a description of the ports see ). In coroutine mode the table has 2 more columns for DELAY and WAKE ports. The relation between the debugger ports and the statistics counters is as follows:

CALL -

counts CALL ports

EXIT -

counts EXIT and *EXIT ports

TRY -

there is no corresponding port, it stands for entering the first of several matching clauses or a disjunction (choicepoint creation)

CUT -

counts CUT ports

NEXT -

counts NEXT ports

FAIL -

counts FAIL and *FAIL ports

DELAY -

counts DELAY ports (in coroutine mode only)

WAKE -

counts WAKE ports (in coroutine mode only)

Ports that can not be displayed by the debugger are not available for the statistics tool either, ie.

• subgoals of predicates that are set to skipped (user predicates are not skipped by default)
• subgoals of predicates that are compiled in nodbgcomp-mode
• untraceable predicates (user predicates and all built-ins are traceable by default)

There is a global flag statistics (accessed with set_flag/2, get_flag/2) that can take four possible values:

• off - no procedure is counted
• some - some specified (using set_flag/3 or set_statistics/2) procedures are counted
• all - all traceable procedures are counted
• mode - like all, but the mode usage is also collected

The output of the statistics tool goes to the output stream. Most of the time it is useful to write it into a file using

?- open(table, write, output), print_statistics, close(output).

sort -n -r +4 table

To improve the performance of a program, the following considerations might apply:

• The CALL ports show how often a procedure is called and hence procedures with many CALLS are crucial to the program's performance.

• Many TRY ports show that either the procedure is really nondeterministic, or that it is written in such a manner that the compiler cannot decide which clause will match a given call and so it has to create a choice point and try several clauses in sequence.

• NEXT ports mean most often that the compiler did not succeed to pick up the right clause at the first try and so another one had to be tried. Rewriting the procedure might help, as well as providing mode declarations.

• If there are much less CUT ports than CALL ports of the procedure !/0, it means that some cuts in the program source are redundant.

• Exhaustive Collection
• Selective Collection
• Obtaining mode information