9.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:

• ‘Procedure’: The procedure in which the goal appears.
• ‘Path/Port’: The goal path and/or port of the goal. For atomic goals, statistics about the CALL event and the corresponding EXIT, FAIL or EXCP event are displayed on separate rows. For other types of goals, the displayed text shows the goal path, except for NEGE, NEGS and NEGF events, where it contains both the goal path and the port.
• ‘File:Line’: The file name and line number of the goal. This can be used to set a breakpoint on the goal.
• ‘Pass (total passing test runs)’: The total number of times the goal was executed in all the passing test runs. This is followed by a number in parentheses, which indicates the number of test runs the goal was executed in. The heading of this column also has a number in parentheses, which is the total number of passing test cases. In the example above we can see that three passing tests were run.
• ‘Fail’: The number of times the goal was executed in the failing test run.
• ‘Suspicion’: A number between 0 and 1 which gives an indication of how likely a particular goal is to be buggy. This is calculated as Suspicion = Fail / (Pass + Fail), where Fail is the number of times the goal was executed in the failing test run, and Pass is the number of times the goal was executed in passing test runs.

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_counts 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, users can give a separate ‘set pass_trace_counts filename’ command. See Trace counts for more information about trace counts.

The table is normally sorted on the identification of the event, meaning it is sorted

• first on the identification of the procedure containing the event (consisting of a pred/func indication, the name of the predicate or function, its arity, and its mode number),
• then on the port (if any),
• then on the path (if any),
• then on the file name, and
• then on the line number.

However, users can also ask for it to be sorted on the Pass, Fail and/or Suspicion columns, or on a combination of these. This can be done with the ‘-s’ or ‘--sort’ option. The argument of this option is a nonempty string consisting of any combination of the letters ‘pPfFdDsS’. The letters in the string indicate how the table should be sorted:

• ‘p’: Pass ascending
• ‘P’: Pass descending
• ‘f’: Fail ascending
• ‘F’: Fail descending
• ‘d’: Difference (Pass minus Fail) ascending
• ‘D’: Difference (Pass minus Fail) descending
• ‘s’: Suspicion ascending
• ‘S’: Suspicion descending

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.

To limit the number of sorted lines displayed, users can specify the ‘-n’ option or its ‘--top’ synonym, both of which take an integer argument; this will cause only the specified number of the top lines of the table to be displayed.

The ‘-m’ or ‘--module’ option, if specified, limits the output to the given module and (if they exist) its submodules.

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