Next: Mode analysis
Up: Development Support Tools
Previous: Port Profiler
  Index
Subsections
Line coverage
The line coverage library provides a means to ascertain exactly how
many times individual clauses are called during the evaluation of a
query.
The library works by placing coverage counters at strategic
points throughout the code being analysed. These counters are
incremented each time the evaluation of a query passes them. There
are three locations in which coverage counters can be inserted.
- 1.
- At the beginning of a code block.
- 2.
- Between predicate calls within a code block.
- 3.
- At the end of a code block.
A code block is defined to be a conjunction of predicate calls. ie. a
sequence of goals separated by commas.
The counter values do not only show whether all code points were
reached but also whether subgoals failed or aborted (in which case
the counter before a subgoal will have a higher value than the
counter after it).
Compilation
In order to add the coverage counters to code, it must be compiled with
the ccompile/1
predicate which can be found in the
coverage library.
The ccompile/1 predicate (note the initial `c' stands for
coverage) can be used in place of the normal compile/1
predicate to compile a file with coverage counters.
The following shows the results of compiling the n-queens example:
?- coverage:ccompile(queen).
queen.ecl compiled traceable 6016 bytes in 0.01 seconds
coverage: inserted 20 coverage counters into module queen
Yes (0.14s cpu)
Once compiled, predicates can be called as usual and will (by default)
have no visible side effects. Internally however, the counters will
be incremented as the execution progresses. The following demonstrates
this for a single solution to the queen predicate:
?- queen:queen([1,2,3,4,5,6,7,8,9], Out).
The counter results are retrieved as demonstrated in the subsequent section.
The two argument predicate ccompile/2
can take a list of name:value pairs
which can be used to control the exact manner in which coverage
counters are inserted. The documentation for the
ccompile/2 predicate
provides for a full list of the available flags.
Results
To generate an HTML file
containing the coverage counter results, the
result/1 predicate is used:
?- coverage:result(queen).
Writing /examples/coverage/queen.html
index.pl compiled traceable 335304 bytes in 0.17 seconds
Yes (0.18s cpu)
This creates the result file coverage/queens.html which
can be viewed using any browser. It contains a pretty-printed form of
the source, annotated with the values of the code coverage counters as
described above. As a side effect, the coverage counters will be reset.
Next: Mode analysis
Up: Development Support Tools
Previous: Port Profiler
  Index
Warwick Harvey
2004-08-07