Next: , Previous: Miscellaneous commands, Up: Debugger commands   [Contents][Index]


7.10.11 Experimental commands


histogram_all filename

Prints (to file filename) a histogram that counts all events at various depths since the start of the program. This histogram is available only in some experimental versions of the Mercury runtime system.


histogram_exp filename

Prints (to file filename) a histogram that counts all events at various depths since the start of the program or since the histogram was last cleared. This histogram is available only in some experimental versions of the Mercury runtime system.


clear_histogram

Clears the histogram printed by ‘histogram_exp’, i.e. sets the counts for all depths to zero.


dice [-pfilename] [-ffilename] [-nnum] [-s[pPfFsS]+] [-o filename] [-m module]

Display a program dice on the screen.


A dice is a comparison between some successful test runs of the program and a failing test run. Before using the ‘dice’ command one or more passing execution summaries and one failing execution summary need to be generated. This can be done by compiling the program with deep tracing enabled (either by compiling in a .debug or .decldebug grade or with the ‘--trace deep’ or ‘--trace rep’ compiler options) and then running the program under mtc. This will generate a file with the prefix ‘.mercury_trace_counts’ and a unique suffix, that contains a summary of the program’s execution This summary is called a slice. Copy the generated slice to a new file for each test case, to end up with a failing slice, say ‘fail’, and some passing slices, say ‘pass1’, ‘pass2’, ‘pass3’, etc. Union the passing slices with a command such as ‘mtc_union -p passes pass1 pass2 pass3’.


The ‘dice’ command can use these files to display a table of statistics comparing the passing test runs to the failing run. Here is an example of a dice displayed in an mdb session:


mdb> dice -f fail -p passes -s S -n 4
Procedure        Path/Port  File:Line Pass (3) Fail Suspicion
pred s.mrg/3-0   <s2;c2;e;> s.m:74       0 (0)    1      1.00
pred s.mrg/3-0   <s2;c2;t;> s.m:67      10 (3)    4      0.29
pred s.mrg/3-0   CALL       s.m:64      18 (3)    7      0.28
pred s.mrg/3-0   EXIT       s.m:64      18 (3)    7      0.28

This example tells us that the ‘else’ in ‘s.m’ on line 74 was executed once in the failing test run, but never in the passing test runs, so this would be a good place to start looking for a bug.


Each row in the table contains statistics about the execution of a separate goal in the program. Six columns are displayed:



The name of the file containing the failing slice can be specified with the ‘-f’ or ‘--fail-trace-counts’ option or with a separate ‘set fail_trace_count filename’ command.


The name of the file containing the union of the passing slices can be given with the ‘-p’ or ‘--pass-trace-counts’ option. Alternatively a separate ‘set pass_trace_counts filename’ command can be given. See Trace counts for more information about trace counts.


The table can be sorted on the Pass, Fail or Suspicion columns, or a combination of these. This can be done with the ‘-s’ or ‘--sort’ option. The argument of this option is a string made up of any combination of the letters ‘pPfFsS’. The letters in the string indicate how the table should be sorted:



For example, the string "SF" means sort the table by suspicion, descending, and if any two suspicions are the same, then by number of executions in the failing test case, descending.


The option ‘-n’ or ‘--top’ can be used to limit the number lines displayed. Only the top num lines, with respect to the ordering specified by the ‘-s’ option, will be displayed. By default the table is limited to 50 lines.


If the ‘-o’ or ‘--output-to-file’ option is given then the output will be written to the specified file instead of being displayed on the screen. Note that the file will be overwritten without warning if it already exists.


The ‘-m’ or ‘--module’ option limits the output to the given module and its submodules, if any.



Next: , Previous: Miscellaneous commands, Up: Debugger commands   [Contents][Index]